Key Locking

Locked keys are copied from the source file to all target files without translation. The Lingo.dev CLI excludes them from translation processing entirely and preserves their source values across all languages.

Configuration#

Add lockedKeys to a bucket in i18n.json:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "config/apiUrl", "system/version"]
    }
  }
}

How it works#

Given this source file:

{
  "welcome": "Welcome to our platform",
  "brand": {
    "name": "Lingo.dev"
  },
  "config": {
    "apiUrl": "https://api.example.com"
  }
}

With "lockedKeys": ["brand/name", "config/apiUrl"], the Spanish target file becomes:

{
  "welcome": "Bienvenido a nuestra plataforma",
  "brand": {
    "name": "Lingo.dev"
  },
  "config": {
    "apiUrl": "https://api.example.com"
  }
}

Only welcome is translated. Locked keys retain their source values exactly.

Key path notation#

Use forward slash (/) to target nested keys:

{ "lockedKeys": ["system/engine/component"] }

Use asterisk (*) to match multiple keys:

{ "lockedKeys": ["navigation/menuItems/*"] }

Keys containing dots in their names work naturally - modules/ai.translation targets the key "ai.translation" inside "modules".

Key Locking vs. Key Ignoring#

Next Steps#