Обычно требуется переводить все строки в файле. Но для исключений — названий брендов, feature flag, юридических текстов, внутреннего мусора — в CLI есть три настройки на уровне файла, которые задаются внутри записи files[] в .lingo/config.json.
| Настройка | Поле конфигурации | Что делает движок |
|---|---|---|
| Lock | lockedKeys | Копирует исходное значение во все целевые локали без перевода. |
| Preserve | preservedKeys | Сохраняет всё, что уже есть в целевом файле, и никогда это не перезаписывает. |
| Ignore | ignoredKeys | Полностью исключает ключ из целевого файла. |
Все три принимают пути к ключам в dot/bracket notation, которая повторяет структуру файла:
{
"files": [
{
"pattern": "content/en/app.json",
"lockedKeys": ["meta.version"],
"preservedKeys": ["legal.terms"],
"ignoredKeys": ["internal.debug"]
}
]
}Lock — чтобы значение везде оставалось одинаковым#
lockedKeys копирует исходное значение в каждый целевой файл без перевода. Используйте это для значений, которые должны оставаться побайтно идентичными во всех локалях:
{
"pattern": "content/en/app.json",
"lockedKeys": ["meta.version", "config.apiUrl"]
}de.json и fr.json получают meta.version с точной строкой из исходника. Измените исходник — и следующий lingo push распространит новое значение на все локали, по-прежнему без перевода.
Preserve — защитите перевод, сделанный вручную#
preservedKeys указывает движку никогда не перезаписывать уже существующее целевое значение. Используйте это, когда ключу нужен человеческий перевод — юридический текст, compliance-тексты и всё, что вы уже проверили и не хотите, чтобы модель трогала:
{
"pattern": "content/en/settings.jsonc",
"preservedKeys": ["featureFlags"]
}При первом переводе движок подставляет значение из исходника, а затем оставляет ваши правки нетронутыми при каждом следующем запуске. Сравните с overrides ниже.
Ignore — уберите ключ из выходного файла#
ignoredKeys полностью удаляет ключ из целевых файлов — он не переводится, не копируется и не записывается. Используйте это для отладочных строк, внутренних флагов и тестовых данных, которые не должны попадать в локализованную сборку:
{
"pattern": "content/en/app.json",
"ignoredKeys": ["internal.debug", "dev.testData"]
}JSON и JSONC
Управление ключами работает со структурированными форматами ключ/значение — json и jsonc. Для форматов семейства Markdown вместо этого ограничивайте область перевода с помощью translateFrontmatterFields и translateComponentProps (см. Formats).
Overrides и preserve#
Существующее целевое значение может пережить запуск двумя способами:
- Preserve (
preservedKeys) — декларативный подход. Ключ защищён конфигурацией во всех локалях и навсегда. - Локальные правки —
lingo pushсравнивает хеш каждого целевого файла с lockfile. Если вы вручную изменили целевой файл, push помечает это какskipped (local edits)и оставляет без изменений. Передайте--force(с областью действия), чтобы перезаписать. См. lingo push.
Используйте preservedKeys, если защита должна быть постоянной и действовать для всех локалей; для разовых ручных правок полагайтесь на обнаружение локальных изменений.
Переход с legacy CLI#
В legacy CLI также было переименование ключей (перенос существующего перевода при изменении идентификатора ключа). В текущем CLI этого нет — состояние перевода отслеживается по хешу файла, поэтому при переименовании ключ будет переведён заново при следующем push. Lock, preserve и ignore сохраняются, но с одним изменением: пути используют dot/bracket notation (meta.version) вместо прежней slash notation (meta/version).
