Getting Started

Install

npm install --save-dev lingosync

lingosync is a plain devDependency — no account, no signup, nothing to configure outside your own package.json.

DeepL only, for now

lingosync only ships with one real translation provider today: DeepL. The built-in manual provider below is a no-op stand-in for testing — it doesn't call any translation API. For actual translations you'll need a DeepL API key (step 2). Other providers (Google Translate, OpenAI, etc.) aren't built yet — see Providers if you want to add one.

1. Point it at your master file

Add a lingosync block to package.json. This example assumes an English master at locales/en.json and Spanish + French as targets:

{
  "lingosync": {
    "master": "locales/en.json",
    "masterLocale": "en",
    "output": "locales",
    "languages": ["es", "fr"],
    "provider": {
      "name": "manual"
    }
  }
}

Using "manual" as the provider means lingosync won't call any real translation API yet — it just prefixes each string with the target locale ([es] Hello), which is perfect for trying out the whole flow before you have an API key.

2. Add your DeepL API key

manual is fine for kicking the tires, but it isn't a real translation provider — it just prefixes each string. For actual translations, switch to the DeepL adapter, the only real provider lingosync ships right now:

{
  "lingosync": {
    "master": "locales/en.json",
    "masterLocale": "en",
    "output": "locales",
    "languages": ["es", "fr"],
    "provider": {
      "name": "deepl",
      "apiKeyEnv": "DEEPL_API_KEY"
    }
  }
}

Put your key in a .env file at the project root — lingosync loads it automatically (see API Keys & .env):

DEEPL_API_KEY=your-key-here

3. Run your first sync

npx lingosync sync

This creates locales/es.json and locales/fr.json, translated by DeepL and matching the exact key structure of your master. A .translations-lock.json file also appears at your project root — commit it. It's how lingosync knows what's already been synced, so the next run only touches what actually changed.

4. Change something and sync again

Edit a value in your master file, then run sync again:

npx lingosync sync

Master (en): +0 new, ~1 changed, -0 removed
  es: 1 translated, 0 overridden, N unchanged
  fr: 1 translated, 0 overridden, N unchanged

Only the key you changed gets re-translated. Everything else is left exactly as it was — no wasted API calls, no accidental overwrites.

Next steps

• Configuration reference — every config field, explained.
• CLI Reference — sync, override, prune-overrides.
• Overrides & the Lock File — how lingosync decides what to (re)translate.