Lingo.dev Docs

Appearance

Key Locking for JSON and YAML ​

Preserve specific values across all translations by locking keys that should remain identical in every language.

Note: Key locking is currently supported only for JSON and YAML formats.

When to Use Key Locking ​

Lock keys for:

  • Technical values (URLs, email addresses, API endpoints)
  • Brand names and product identifiers
  • Configuration values that must remain consistent
  • Version numbers and other technical identifiers

Setting Up Key Locking ​

Add the lockedKeys array to your bucket configuration in i18n.json:

json
{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": [
        "app/version",
        "config/apiEndpoint",
        "branding/productName"
      ]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "lockedKeys": ["contact/email", "site/domain"]
    }
  }
}

How Key Locking Works ​

During translation processing:

  1. Locked keys retain their original values from the source locale
  2. These values are excluded from translation requests
  3. Values remain consistent during both translation and cache restoration

Working with Complex Data Structures ​

Key locking supports nested objects and arrays using forward slash (/) path notation:

json
{
  "lockedKeys": [
    "level1/level2/level3/lockedValue",
    "settings/advanced/apiKeys/0",
    "configuration/endpoints/auth"
  ]
}

Important: Always use forward slash (/) as the separator for nested keys, not dot (.). This allows locking keys that contain dots in their names.

This powerful notation enables you to:

  • Lock deeply nested properties
  • Lock specific array elements using numeric indices
  • Lock entire object subtrees

Practical Example ​

Source JSON file (en.json):

json
{
  "welcome": "Welcome to our application",
  "config": {
    "api.url": "https://api.example.com",
    "version": "1.2.3"
  },
  "branding": {
    "name": "TechApp",
    "slogan": "Technology made simple"
  }
}

Configuration in i18n.json:

json
{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["config/api.url", "branding/name"]
    }
  }
}

Resulting Spanish translation (es.json):

json
{
  "welcome": "Bienvenido a nuestra aplicación",
  "config": {
    "api.url": "https://api.example.com",
    "version": "1.2.3"
  },
  "branding": {
    "name": "TechApp",
    "slogan": "Tecnología simplificada"
  }
}

Notice how config/api.url and branding/name remain unchanged while other content is properly translated. The forward slash notation in lockedKeys correctly identifies keys even when they contain dots in their names.