Сохранение ключей

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

Когда вы сохраняете ключи, CLI инициализирует их исходными значениями и пропускает при следующих запусках перевода.

Настройка сохранения ключей

Добавьте preservedKeys в конфиг вашего bucket в i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms", "marketing/tagline"]
    }
  }
}

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

Как работает сохранение ключей

Во время обработки перевода Lingo.dev CLI:

  1. Находит сохраняемые ключи из вашей конфигурации
  2. Исключает их из перевода — такие ключи никогда не отправляются в движок перевода
  3. Инициализирует отсутствующие ключи — копирует исходные значения как плейсхолдеры для новых файлов перевода
  4. Защищает существующие значения — вручную переведённый контент не меняется

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

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

С конфигом сохраняемых ключей:

{
  "preservedKeys": ["legal/privacy", "legal/terms"]
}

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

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

Ключ welcome переводится. Раздел legal копируется как есть для ручного перевода позже.

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

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

{
  "preservedKeys": [
    "legal/privacy/full",
    "legal/terms/conditions",
    "marketing/campaigns/holiday"
  ]
}

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

// Source structure
{
  "legal": {
    "privacy": {
      "full": "Full privacy policy text..."
    }
  }
}

Путь legal/privacy/full сохраняет этот конкретный вложенный ключ.

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

Слэш-нотация работает и для ключей, в которых есть точки в названии:

// Source with dotted key names
{
  "legal": {
    "privacy.policy": "Privacy policy content",
    "terms.of.service": "Terms of service content"
  }
}

Сохраняйте эти ключи с помощью:

{
  "preservedKeys": ["legal/privacy.policy", "legal/terms.of.service"]
}

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

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

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "preservedKeys": ["compliance/gdpr", "compliance/ccpa"]
    }
  }
}

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

Сохранение ключей и блокировка ключей

Сохранение ключей и блокировка ключей выполняют разные задачи:

Сохранение ключей (preservedKeys):

  • Ключи инициализируются один раз с исходными значениями как плейсхолдерами
  • Существующие значения для целевого языка никогда не перезаписываются через CLI
  • Используется для контента, требующего ручного перевода или юридической проверки

Блокировка ключей (lockedKeys):

  • Ключи включаются в процесс перевода, но значения остаются неизменными
  • Заблокированные ключи всегда совпадают с исходными значениями
  • Используется для технических идентификаторов, имён компонентов или значений, которые должны оставаться неизменными

Пример сравнения:

// Source file
{
  "welcome": "Welcome",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

// Configuration
{
  "lockedKeys": ["system/component"],
  "preservedKeys": ["legal/privacy"]
}

// Generated target file
{
  "welcome": "Bienvenido",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

После ручного перевода legal/privacy на испанский, при последующих запусках ручной перевод сохраняется. Ключ system/component всегда остаётся на английском независимо от содержимого целевого файла.