Управление ключами
Выберите, откуда брать значение: из исходного содержимого, существующего целевого значения, перевода или метаданных локали.
Некоторые значения каталога должны быть одинаковыми на всех языках. Другие нужно брать из перевода, который обновляют вручную. Параметры управления ключами явно задают эти правила, когда обработчик файла с их поддержкой формирует результат.
Это параметры записи о файле в .lingo/config.json. Они не выбирают файлы и не запрашивают обновление ключей — за это отвечают области перевода.
| Параметр | Как формируется результат |
|---|---|
lockedKeys | Копировать исходное значение без перевода. |
preservedKeys | Сохранять существующее значение перевода, если оно есть. |
ignoredKeys | Исключать выбранное содержимое из результата, если формат это поддерживает. |
injectLocale | Записывать целевую локаль в указанное место. |
Задайте источник для каждого значения #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}Здесь ИД продукта берётся из исходника, существующее юридическое уведомление — из перевода, а внутренняя заметка исключается. Подстановка локали записывает целевую локаль в meta.locale, при необходимости создавая недостающие объекты-контейнеры. Для записи в массив укажите существующий массив и выберите существующий элемент или позицию сразу после конца массива. Пути, которые создают пропуски или проходят через несовместимые значения, приводят к ошибке.
Сохранение не создаёт ручной перевод там, где его нет. При обычной инкрементальной обработке существующий перевод уже используется, чтобы сохранять правки в значениях неизменённых ключей. preservedKeys даёт дополнительную, явно заданную защиту. Изменение исходника или переименование ключа JSON всё равно может потребовать новой обработки.
Пути и пересечение правил #
В JSON/JSONC параметры управления используют имена, разделённые точками, и индексы в квадратных скобках, например checkout.submit или items[0].title. Защищённый путь может охватывать вложенные элементы. Если точка входит в само имя ключа, используйте свойство JSONPath в кавычках, например $['checkout.submit']. lingo push также читает списки, записанные для прежней версии CLI с помощью /: каждое имя между / воспринимается целиком, поэтому checkout/submit равнозначно checkout.submit, а common/error.message обозначает ключ error.message внутри common. Имена с процентным кодированием, например legal/Terms%20of%20use, декодируются. Шаблон без / считается путём с точками и не декодируется, поэтому отдельное закодированное имя записывайте как JSONPath, например $['Terms of use']. Так как все шаблоны с / читаются таким образом, для ключа, в имени которого есть /, нужен JSONPath, например $.routes['/about'].title. Завершающий *, как в internal/*, охватывает значения непосредственно внутри internal, но не вложенные туда объекты или массивы — как и в прежней версии CLI. Прежняя версия CLI также находила ключи, имена которых продолжаются с - или ., поэтому legal/terms охватывал legal/terms-short. Теперь совпадение по префиксу не поддерживается. Указывайте такие ключи отдельно. GitHub App не принимает запись через косую черту: если приложение читает ту же конфигурацию, записывайте эти списки через точки или как JSONPath. Этот синтаксис описан в разделе Области перевода.
Для одного и того же пути правило игнорирования удаляет значение, в том числе подставленную локаль. Подстановка локали имеет приоритет над блокировкой и сохранением. Блокировка имеет приоритет над сохранением, поэтому ключ в обоих списках получает исходное значение. Игнорирование родительского элемента также удаляет все вложенные элементы. По возможности задавайте каждому значению один источник и проверяйте результат, если правила пересекаются внутри объекта или массива.
Принудительная обработка всего файла очищает артефакт текущего перевода, отправляемый на сервер. Без этого контекста правило сохранения не может сохранить прежние формулировки ручного перевода. Перед принудительной заменой сохраните копию, из которой можно восстановить данные.
Ограничения обработчиков #
JSON и JSONC поддерживают все четыре механизма управления. TypeScript, PHP, YAML и YAML с локалью в корне поддерживают блокировку, сохранение и игнорирование, а stringsdict — блокировку и сохранение. Java properties поддерживает блокировку, сохранение, игнорирование и область видимости ключей. Каждый шаблон сопоставляется с ключом целиком, как и в предыдущей версии CLI. CSV не поддерживает ни одно из трёх правил для ключей: CLI и GitHub App отклоняют запись CSV, в которой задано lockedKeys, preservedKeys или ignoredKeys. О том, как формируются выходные данные, читайте в справочнике по выбранному формату.
Краткая запись пути поддерживает * вместо целого сегмента, числовые индексы и пустые квадратные скобки. Подстановочные знаки для части сегмента не допускаются. При использовании lingo push три списка правил для ключей также принимают запись через косую черту. GitHub App и путь для подстановки локали её не поддерживают. Для имён со знаками пунктуации используйте свойства JSONPath в кавычках. Явные запросы $ передаются без изменений. Для подстановки нужно указать одно место. Если подстановка включена, по умолчанию используется ключ language.