Configuration

Everything lives under a lingosync key in your project's package.json — there's no separate config file to keep in sync with anything else.

{
  "lingosync": {
    "master": "src/locales/en.json",
    "masterLocale": "en",
    "output": "src/locales",
    "languages": [
      "es",
      "fr",
      { "code": "en-US", "providerLocale": "EN-US" },
      { "code": "en-GB", "providerLocale": "EN-GB" }
    ],
    "provider": {
      "name": "deepl",
      "apiKeyEnv": "DEEPL_API_KEY"
    },
    "lockFile": ".translations-lock.json",
    "overridesFile": ".translations-overrides.json"
  }
}

Fields

master (required)

Path to the master JSON file, relative to your project root (the folder containing package.json). Can be a nested object — lingosync flattens it internally using dot notation (greeting.title) and rebuilds the same nesting on write.

masterLocale (required)

The locale code of your master file, e.g. "en". Sent to the translation provider as the source language — it needs to know what it's translating from, not just to.

output (required)

Folder where target locale files are written, one per language: <output>/<code>.json.

languages (required)

An array of target locales. Each entry is either:

• A string, used as both the output file name and the code sent to the provider: "es".
• An object { code, providerLocale }, when the code you want as your file name doesn't match what the provider expects. This is the common case for regional variants: some providers (like DeepL) treat en-US and en-GB as genuinely distinct targets, while others (like Google Translate) only translate to "English" without a regional distinction. providerLocale lets you keep meaningful file names while sending the provider whatever code it actually understands. It also covers fully custom, non-standard codes ("formal-en") that need to map to a real locale for the provider call.

See Providers for more on what each provider actually supports for regional variants.

provider (required)

• name: which provider to use. Built in: "manual" (no network, returns [locale] original text — great for testing) and "deepl".
• apiKeyEnv: the name of the environment variable holding your API key. Never put the key itself in package.json — it gets committed to git. lingosync reads it from process.env at run time, and automatically loads a .env file from your project root if present (see API Keys & .env).

lockFile / overridesFile (optional)

Override the default paths for lingosync's two state files. Both default to your project root and should be committed to git so your whole team shares the same sync state.

Master file format

Plain JSON, nested or flat — your call:

{
  "greeting": {
    "title": "Hello {{name}}",
    "subtitle": "Welcome back"
  },
  "footer": "See you soon"
}

Only string leaves are treated as translatable keys. Numbers, booleans, null, and arrays are left untouched and don't participate in sync — useful if your locale files also carry structural data alongside text.