strapi-to-lokalise-plugin/README.md

Preview and sync Lokalise translations from Strapi admin

# Lokalise Sync - Strapi Plugin

[![npm version](https://badge.fury.io/js/strapi-to-lokalise-plugin.svg)](https://badge.fury.io/js/strapi-to-lokalise-plugin)
[![Strapi v4](https://img.shields.io/badge/Strapi-v4.x-blue)](https://strapi.io)
[![Strapi v5](https://img.shields.io/badge/Strapi-v5.x-purple)](https://strapi.io)

Preview and sync Lokalise translations directly from your Strapi admin panel. This plugin is fully compatible with **Strapi v4.x** and **Strapi v5.x**.

---

## 🔴 CRITICAL: STRAPI V4 INSTALLATION GUIDE

> **⚠️ MUST READ BEFORE INSTALLING ON STRAPI V4!**
> 
> This section contains **ALL critical steps and common mistakes** to ensure the plugin works correctly on Strapi v4.25.15 and all v4.x versions.

### ✅ Step-by-Step Installation for Strapi v4

#### **1. Verify Node.js Version (REQUIRED)**

**Strapi v4.25.15 requires Node.js 18.x - 20.x**

```bash
node --version
```

**Must show:** `v18.x.x`, `v19.x.x`, or `v20.x.x`

**If wrong version:**
- **Windows:** Install nvm-windows from https://github.com/coreybutler/nvm-windows/releases
  ```bash
  nvm install 20.19.5
  nvm use 20.19.5
  ```
- **Mac/Linux:** Use nvm
  ```bash
  nvm install 20.19.5
  nvm use 20.19.5
  ```

#### **2. Install the Plugin**

```bash
npm install strapi-to-lokalise-plugin@latest
```

> ⚠️ **Use `--legacy-peer-deps` if you get dependency errors:**
> ```bash
> npm install strapi-to-lokalise-plugin@latest --legacy-peer-deps
> ```

#### **3. Configure the Plugin (CRITICAL - MOST COMMON MISTAKE!)**

**❌ MISTAKE:** Thinking the plugin will work without configuration  
**✅ CORRECT:** You MUST create `config/plugins.js` - it doesn't exist by default!

**Create this file:** `config/plugins.js` (in your Strapi project root)

**Copy and paste this EXACT code:**

```js
module.exports = {
  'lokalise-sync': {
    enabled: true,
  },
};
```

**⚠️ CRITICAL NOTES:**
- ✅ File must be named `plugins.js` (not `plugins.ts`)
- ✅ File must be in `config/` folder (NOT `src/config/`)
- ✅ Plugin ID is `'lokalise-sync'` (with quotes and hyphen)
- ❌ **DO NOT use** `strapi-to-lokalise-plugin` (that's the npm package name, not the plugin ID!)

**Full path example:**
- ✅ `C:\your-project\config\plugins.js`
- ❌ `C:\your-project\src\config\plugins.js` (WRONG!)

#### **4. Create Environment File (REQUIRED)**

**❌ MISTAKE:** Missing `.env` file causes authentication errors  
**✅ CORRECT:** Create `.env` file with required secrets

**Create this file:** `.env` (in your Strapi project root)

**Minimum required variables:**

```env
HOST=0.0.0.0
PORT=1337

# Generate these using: node -e "console.log(require('crypto').randomBytes(16).toString('base64'))"
# Run the command 4 times to get 4 keys
APP_KEYS=yourKey1,yourKey2,yourKey3,yourKey4

# Generate using: node -e "console.log(require('crypto').randomBytes(16).toString('base64'))"
API_TOKEN_SALT=yourApiTokenSalt

# Generate using: node -e "console.log(require('crypto').randomBytes(16).toString('base64'))"
ADMIN_JWT_SECRET=yourAdminJwtSecret

# Generate using: node -e "console.log(require('crypto').randomBytes(16).toString('base64'))"
TRANSFER_TOKEN_SALT=yourTransferTokenSalt
```

**Quick generate script (Windows):**

Create `CREATE_ENV.bat` in your project root:

```batch
@echo off
echo HOST=0.0.0.0 > .env
echo PORT=1337 >> .env
node -e "console.log('APP_KEYS=' + Array(4).fill(0).map(() => require('crypto').randomBytes(16).toString('base64')).join(','))" >> .env
node -e "console.log('API_TOKEN_SALT=' + require('crypto').randomBytes(16).toString('base64'))" >> .env
node -e "console.log('ADMIN_JWT_SECRET=' + require('crypto').randomBytes(16).toString('base64'))" >> .env
node -e "console.log('TRANSFER_TOKEN_SALT=' + require('crypto').randomBytes(16).toString('base64'))" >> .env
echo .env file created successfully!
```

Then run: `CREATE_ENV.bat`

#### **5. Configure Server Settings (REQUIRED for Cookies/Auth)**

**File:** `config/server.js`

**Ensure it contains:**

```js
module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'), // CRITICAL for cookies!
  },
  proxy: true,
  url: env('PUBLIC_URL', 'http://localhost:1337'),
});
```

#### **6. Configure Admin Settings (REQUIRED for Cookies)**

**File:** `config/admin.js`

**Ensure it contains:**

```js
module.exports = ({ env }) => ({
  auth: {
    secret: env('ADMIN_JWT_SECRET'),
  },
  cookies: {
    secure: false, // MUST be false for localhost
  },
});
```

#### **7. Configure Database (REQUIRED)**

**File:** `config/database.js`

**For SQLite (development):**

```js
module.exports = ({ env }) => ({
  connection: {
    client: 'sqlite', // Use 'sqlite' NOT 'sqlite3' or 'better-sqlite3'
    connection: {
      filename: env('DATABASE_FILENAME', '.tmp/data.db'),
    },
    useNullAsDefault: true,
  },
});
```

**⚠️ CRITICAL:** 
- ✅ Use `client: 'sqlite'` (Strapi v4 recognizes this)
- ✅ Install `better-sqlite3` package: `npm install better-sqlite3 --legacy-peer-deps`
- ❌ **DO NOT use** `client: 'sqlite3'` or `client: 'better-sqlite3'`

#### **8. Clear Cache and Restart (REQUIRED After Installation)**

**⚠️ MISTAKE:** Not clearing cache causes old errors  
**✅ CORRECT:** Always clear cache after installing/updating

```bash
# Windows
rmdir /s /q .cache build

# Mac/Linux
rm -rf .cache build

# Then restart
npm run develop
```

**Also clear browser cache:**
- Press `Ctrl+Shift+R` (Windows) or `Cmd+Shift+R` (Mac)
- Or: DevTools (F12) → Right-click refresh → "Empty Cache and Hard Reload"

#### **9. Common Mistakes to Avoid**

| ❌ **WRONG** | ✅ **CORRECT** |
|--------------|---------------|
| Plugin ID: `strapi-to-lokalise-plugin` | Plugin ID: `'lokalise-sync'` |
| File: `src/config/plugins.js` | File: `config/plugins.js` |
| File: `config/plugins.ts` (v4) | File: `config/plugins.js` (v4) |
| Database: `client: 'sqlite3'` | Database: `client: 'sqlite'` |
| Missing `.env` file | Create `.env` with APP_KEYS, etc. |
| Not clearing cache | Always clear `.cache` and `build` folders |
| Wrong Node version | Use Node 18.x - 20.x for v4.25.15 |

#### **10. Verify Installation**

After following all steps above, check:

1. **Plugin appears in sidebar:**
   - Log in to admin panel
   - Look for "Lokalise Sync" in left sidebar
   - If missing → check `config/plugins.js` exists and has correct content

2. **Routes registered:**
   - Check terminal logs when Strapi starts
   - Should see: `[lokalise-sync] Routes count: 18`
   - Should see: `POST /lokalise-sync/settings route registered: true`

3. **Settings page loads:**
   - Click on "Lokalise Sync" in sidebar
   - Should see settings form
   - If 405 error → clear cache and restart

#### **11. If Plugin Doesn't Appear**

**Check in order:**

1. ✅ `config/plugins.js` exists and contains correct code
2. ✅ Plugin ID is `'lokalise-sync'` (not package name)
3. ✅ File is in `config/` folder (not `src/config/`)
4. ✅ Restarted Strapi after creating config file
5. ✅ Cleared cache (`.cache` and `build` folders)
6. ✅ Cleared browser cache (hard refresh)
7. ✅ Check terminal for errors when Strapi starts

---

## 🟢 STRAPI V5 INSTALLATION (SIMPLER!)

**Strapi v5 installation is simpler:**

1. **Install:**
   ```bash
   npm install strapi-to-lokalise-plugin@latest
   ```

2. **Configure:** Edit existing `config/plugins.ts`:
   ```ts
   export default {
     'lokalise-sync': {
       enabled: true,
     },
   };
   ```

3. **Restart:** `npm run develop`

That's it! Strapi v5 handles most configuration automatically.

---

## 🔴 CRITICAL ISSUES & SOLUTIONS

### Issue 1: "405 Method Not Allowed" When Saving Settings

**This is FIXED in version 0.1.71+**

**If you still see 405 errors:**

1. **Update to latest version:**
   ```bash
   npm install strapi-to-lokalise-plugin@latest
   ```

2. **Clear all cache:**
   ```bash
   rmdir /s /q .cache build    # Windows
   rm -rf .cache build          # Mac/Linux
   ```

3. **Restart Strapi:**
   ```bash
   npm run develop
   ```

4. **Clear browser cache:**
   - Press `Ctrl+Shift+R` or `Cmd+Shift+R`

### Issue 2: Plugin Not Appearing in Sidebar

**Most common cause:** Missing or incorrect `config/plugins.js`

**Solution:**
1. ✅ Ensure `config/plugins.js` exists (create it if missing!)
2. ✅ Contains exactly:
   ```js
   module.exports = {
     'lokalise-sync': {
       enabled: true,
     },
   };
   ```
3. ✅ Restart Strapi after creating file
4. ✅ Clear cache

### Issue 3: "401 Unauthorized" Errors

**Causes:**
- Missing `APP_KEYS` in `.env` file
- Missing cookie configuration
- External auth conflict (Clerk/Auth0)

**Solutions:**

1. **Ensure `.env` has APP_KEYS:**
   ```env
   APP_KEYS=key1,key2,key3,key4
   ADMIN_JWT_SECRET=yourSecret
   ```

2. **Ensure `config/server.js` has:**
   ```js
   app: {
     keys: env.array('APP_KEYS'),
   },
   ```

3. **Ensure `config/admin.js` has:**
   ```js
   cookies: {
     secure: false,
   },
   ```

### Issue 4: Slow Content Type Creation/Save (50+ seconds)

**⚠️ THIS IS NORMAL BEHAVIOR - NOT A PLUGIN ISSUE!**

When you create or save a content type in Strapi v4, Strapi automatically:
1. Restarts the server
2. Rebuilds all routes
3. Regenerates TypeScript types

**This can take 30-60 seconds** - this is **expected behavior**, not an error!

**Why it happens:**
- Strapi needs to rebuild the entire route structure
- TypeScript types need to be regenerated
- The admin panel needs to reload with new content types

**This is NOT caused by the plugin** - it's how Strapi v4 works.

**To speed up (slightly):**
- Use `--watch-admin` flag: `npm run develop -- --watch-admin`
- Avoid creating multiple content types in quick succession
- Be patient - the restart is required for Strapi to work correctly

**What to do:**
- ✅ Wait for the restart to complete (30-60 seconds is normal)
- ✅ Don't interrupt the process
- ✅ The "restart taking longer than expected" message is normal - just wait

---

## ✨ Features

- 🔄 **Bi-directional Sync**: Sync translations between Strapi and Lokalise
- 👀 **Preview Mode**: Preview translations before syncing
- 🎯 **Selective Sync**: Choose which content types and locales to sync
- ⚡ **Fast & Efficient**: Optimized sync process with progress tracking
- 🔐 **Secure**: API credentials stored securely in plugin settings
- 🎨 **Zero Dependencies**: No conflicts with Strapi design system packages

## 📋 Requirements

### Strapi Version Compatibility

- **Strapi v4.1.0+ through v4.x** (all versions)
- **Strapi v5.0.0+** (all versions)

### Node.js Version Requirements

**⚠️ IMPORTANT: Node.js version depends on your Strapi version!**

- **For Strapi v4.x:** Node.js **14.19.1** through **18.x.x** (recommended: **18.x** or **20.x**)
- **For Strapi v5.x:** Node.js **18.0.0** through **22.x.x** (recommended: **18.x** or **20.x**)

**Check your Node.js version:**
```bash
node --version
```

**If you have the wrong Node.js version:**

1. **Use nvm (Node Version Manager) - Recommended:**
   
   **Windows:**
   - Install from: https://github.com/coreybutler/nvm-windows/releases
   - Then run:
     ```bash
     nvm install 20.19.5
     nvm use 20.19.5
     ```
   
   **Mac/Linux:**
   - Install from: https://github.com/nvm-sh/nvm
   - Then run:
     ```bash
     nvm install 20.19.5
     nvm use 20.19.5
     ```

2. **Or download Node.js directly:**
   - Download from: https://nodejs.org/
   - Choose LTS version 18.x or 20.x for maximum compatibility

### Other Requirements

- **Lokalise Account**: Valid API token with appropriate permissions

## 📦 Quick Installation

### For Strapi v4

```bash
# 1. Install
npm install strapi-to-lokalise-plugin@latest --legacy-peer-deps

# 2. Create config/plugins.js
# Copy code from Step 3 in CRITICAL section above

# 3. Create .env file with required variables
# Copy code from Step 4 in CRITICAL section above

# 4. Clear cache and restart
rmdir /s /q .cache build    # Windows
rm -rf .cache build          # Mac/Linux
npm run develop
```

### For Strapi v5

```bash
# 1. Install
npm install strapi-to-lokalise-plugin@latest

# 2. Edit config/plugins.ts
# Add plugin configuration (see CRITICAL section above)

# 3. Restart
npm run develop
```

---

## ⚙️ Configuration

### Initial Setup

1. **Navigate to Lokalise Sync** in the admin sidebar
2. **Configure Settings:**
   - Enter your **Lokalise Project ID** (found in your Lokalise project settings)
   - Enter your **Lokalise API Token** (create one in Lokalise Account Settings → API tokens)
   - Optionally configure the **Lokalise Base URL** (defaults to `https://api.lokalise.com/api2`)
3. **Test Connection:** Click "Test connection" to verify your credentials
4. **Save Settings:** Click "Save settings" to store your configuration

### API Token Permissions

Your Lokalise API token needs the following permissions:
- **Read** - To preview and read translations
- **Write** - To sync translations back to Lokalise

## 🚀 Usage

### Preview Translations

1. Click **"Run preview"** to see what will be synced
2. Review the list of content types, keys, and values
3. Use the search bar to filter specific content
4. Select individual keys or entire content types using checkboxes

### Sync to Lokalise

1. After previewing, select the keys you want to sync
2. Click **"Sync selected keys"**
3. Enter a **tag name** (optional, helps organize syncs in Lokalise)
4. Select the **locale** to sync
5. Click **"Sync now"**
6. Monitor the progress bar until sync completes

### Sync Options

- **Select All:** Use "Select filtered" to select all visible keys
- **Preview Filters:** Click "Preview options" to filter by content type, sync status, etc.
- **Search:** Search by content type, group, key name, key ID, or key value

## 🐛 Troubleshooting

### HTTP 500: "Cannot access 'data2' before initialization"

**Solution (Already Fixed in v0.1.51+):**
1. **Update to latest version:**
   ```bash
   npm install strapi-to-lokalise-plugin@latest
   ```

2. **Clear ALL caches:**
   ```bash
   rmdir /s /q .cache build          # Windows
   rm -rf .cache build                # Mac/Linux
   ```

3. **Clear browser cache:**
   - Press `Ctrl+Shift+R` or `Cmd+Shift+R`

4. **Restart Strapi:**
   ```bash
   npm run develop
   ```

### 401 Unauthorized Errors

See "Issue 3: 401 Unauthorized Errors" in the CRITICAL ISSUES section above.

### API Connection Fails

**Check these:**

1. **Valid credentials:**
   - Verify Project ID is correct
   - Verify API token is valid
   - Ensure token hasn't expired

2. **Token permissions:**
   - Token must have Read and Write permissions
   - Check in Lokalise: Account Settings → API tokens

3. **Network/firewall:**
   - Ensure your server can reach `api.lokalise.com`

### Installation Errors

See "Common Mistakes to Avoid" section in the CRITICAL installation guide above.

## 📋 Peer Dependencies

The plugin relies on the host Strapi project for these packages:

- `@strapi/strapi`: ^4.1.0 || ^5.0.0
- `react`: >=17.0.0
- `react-dom`: >=17.0.0
- `@strapi/utils`: * (provided by Strapi)
- `lodash`: * (provided by Strapi)

**Optional:**
- `@strapi/plugin-i18n`: * (only needed if you use i18n features)

## 🔧 Advanced Configuration

### Environment Variables

You can optionally set a secret key for token encryption:

```bash
LOKALISE_SYNC_SECRET_KEY=your-secret-key-here
```

This enables AES-256-GCM encryption for stored API tokens.

### Custom Lokalise Base URL

If you're using a self-hosted Lokalise instance, set the base URL in plugin settings or via environment:

```bash
LOKALISE_BASE_URL=https://your-lokalise-instance.com/api2
```

## 🤝 Getting Help

### Reporting Issues

If you encounter a bug or have a feature request:

1. Check the troubleshooting section above
2. Check the CRITICAL ISSUES section above
3. Create a new issue with:
   - Strapi version
   - Node.js version
   - Plugin version
   - Error messages/logs
   - Steps to reproduce

## 📚 Additional Resources

- [Strapi Documentation](https://docs.strapi.io)
- [Lokalise API Documentation](https://developers.lokalise.com/reference/rest-api)
- [Lokalise API Tokens Guide](https://docs.lokalise.com/en/articles/1929556-api-tokens)

## 📝 License

MIT License - see [LICENSE](./LICENSE) file for details.

---

**Made with care to ensure smooth installation and zero dependency conflicts across all Strapi versions.**