Блокировка ключей

Lingo.dev CLI позволяет заблокировать определённые ключи перевода, чтобы их значения оставались одинаковыми во всех языках. При блокировке ключей CLI исключает их из процесса перевода и напрямую копирует исходные значения во все целевые файлы.

Настройка блокировки ключей

Добавьте lockedKeys в конфигурацию вашего bucket в i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["system/component", "config/engine", "modules/processor"]
    }
  }
}

Массив lockedKeys использует запись через прямой слэш (/) для указания вложенных ключей и звёздочку (*) для выбора нескольких ключей.

Как работает блокировка ключей

Во время процесса перевода Lingo.dev CLI:

  1. Находит заблокированные ключи в вашей конфигурации
  2. Исключает их из перевода — заблокированный контент никогда не отправляется в AI-модели
  3. Копирует исходные значения напрямую во все целевые файлы
  4. Сохраняет一致ность во всех языках

Пример рабочего процесса:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "system": {
    "component": "Lingo.dev CLI",
    "processor": "Translation Engine"
  },
  "config": {
    "engine": "Lingo.dev Engine"
  }
}

С конфигурацией заблокированных ключей:

{
  "lockedKeys": ["system/component", "system/processor", "config/engine"]
}

Сгенерированный перевод на испанский:

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "system": {
    "component": "Lingo.dev CLI",
    "processor": "Translation Engine"
  },
  "config": {
    "engine": "Lingo.dev Engine"
  }
}

Только welcome переводится, а заблокированные ключи остаются такими же, как в исходнике.

Без блокировки ключей "Lingo.dev Engine" может быть ошибочно переведён как "Motor de Lingo.dev" на испанском или "Lingo.devエンジン" на японском, чего мы не хотим в этом примере.

Вложенные пути ключей

Используйте запись через прямой слэш (/), чтобы заблокировать ключи на любом уровне вложенности:

{
  "lockedKeys": [
    "system/engine/component",
    "modules/ai/processor",
    "config/translation/handler"
  ]
}

Эта запись работает с любыми сложными вложенными структурами:

// Source structure
{
  "system": {
    "engine": {
      "component": "Lingo.dev Engine"
    }
  }
}

Путь system/engine/component блокирует значение имени компонента.

Ключи с точками

Запись через прямой слэш позволяет работать с ключами, в названиях которых есть точки:

// Source with dotted key names
{
  "modules": {
    "ai.translation": "AI Translation",
    "content.processor": "Content Processor"
  }
}

Заблокируйте эти ключи с помощью:

{
  "lockedKeys": ["modules/ai.translation", "modules/content.processor"]
}

Несколько типов бакетов

Разные форматы файлов могут иметь разные заблокированные ключи:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["config/engine", "system/component"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "lockedKeys": ["service/name", "module/title"]
    }
  }
}

Каждый тип бакета ведёт свой собственный список заблокированных ключей в зависимости от структуры содержимого.

Значения-массивы

Для ключей со значениями-массивами добавьте /* после имени ключа:

// Source file
{
  "navigation": {
    "menuItems": ["Home", "About", "Contact"],
    "title": "Main Navigation"
  }
}

Заблокируйте массив с помощью:

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

Результат:

// locales/es.json
{
  "navigation": {
    "menuItems": ["Home", "About", "Contact"],
    "title": "Navegación Principal"
  }
}