Lokalise Sync - Strapi Plugin

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

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

  nvm install 20.19.5
  nvm use 20.19.5

• Mac/Linux: Use nvm

  nvm install 20.19.5
  nvm use 20.19.5

2. Install the Plugin

npm install strapi-to-lokalise-plugin@latest

⚠️ Use --legacy-peer-deps if you get dependency errors:

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:

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:

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:

@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:

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:

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):

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

# 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:

   npm install strapi-to-lokalise-plugin@latest

2. Configure: Edit existing config/plugins.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:

   npm install strapi-to-lokalise-plugin@latest

2. Clear all cache:

   rmdir /s /q .cache build    # Windows
   rm -rf .cache build          # Mac/Linux

3. Restart Strapi:

   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:

   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:

   APP_KEYS=key1,key2,key3,key4
   ADMIN_JWT_SECRET=yourSecret

2. Ensure config/server.js has:

   app: {
     keys: env.array('APP_KEYS'),
   },

3. Ensure config/admin.js has:

   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:

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:

     nvm install 20.19.5
     nvm use 20.19.5

   Mac/Linux:

   • Install from: https://github.com/nvm-sh/nvm
   • Then run:

     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

# 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

# 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:

   npm install strapi-to-lokalise-plugin@latest

2. Clear ALL caches:

   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:

   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:

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:

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
• Lokalise API Documentation
• Lokalise API Tokens Guide

📝 License

MIT License - see LICENSE file for details.

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