CLI v0: управление ключами и ручные правки

Разделяйте значения, задаваемые исходным текстом, переводы под ручным управлением и обычные исправления в каталогах прежнего формата.

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

Как исправить обычный перевод #

Отредактируйте перевод напрямую и сохраните утверждённую формулировку в коммите. Если исходный текст не изменился, обычная дельта-обработка может сохранить перевод. Изменение контрольной суммы исходного текста позволяет снова перевести этот ключ, а принудительный режим может заменить перевод, даже если исходный текст не менялся.

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

Явно укажите, кто управляет значением #

ПараметрКак формируется вывод в прежней версии
lockedKeysКопировать исходное значение. Это может перезаписать ручную правку перевода.
ignoredKeysИсключить выбранное содержимое из перевода и вывода.
preservedKeysЗаполнить отсутствующее значение исходным, а затем сохранять целевое значение для ручного редактирования.
json
{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name"],
      "ignoredKeys": ["internal/*"],
      "preservedKeys": ["legal/terms"]
    }
  }
}

Здесь название бренда остаётся неизменным, внутренние записи исчезают, а юридические формулировки остаются под ручным управлением. Если для новой заглушки на исходном языке включено сохранение значения, её всё равно нужно перевести перед выпуском. Если приложение ожидает игнорируемый ключ, предусмотрите резервное значение или измените это требование.

Проверяйте пересекающиеся шаблоны управления, а не полагайтесь на недокументированный порядок приоритетов. Так работает v0. В текущей версии механизмы сохранения целевых значений работают иначе.

Как обращаться к вложенным ключам и ключам с точками в имени #

В прежней версии уровни вложенности в путях разделяются косой чертой. brand/name выбирает name внутри brand, а modules/ai.translation — ключ с точкой в имени внутри modules. Подстановочные знаки работают по прежним правилам сопоставления. Их нужно проверять на нужной глубине вложенности. Современный синтаксис с точками и скобками не взаимозаменяем с прежним.

Как повторно использовать перевод при переименовании #

Прежняя дельта-обработка может сопоставить хеш исходного значения нового ключа с предыдущим хешем удалённого ключа в контексте того же обрабатываемого пути. Если текст не изменился, существующий перевод может перейти к переименованному ключу без нового перевода.

Если изменить и ключ, и исходный текст, потребуется новый перевод. При перемещении между независимыми путями или использовании повторяющихся одинаковых строк результат нужно проверить: у такого сопоставления есть ограничения, это не полноценная память переводов. В текущей версии элементы JSON идентифицируются по путям, и прежний механизм к ним не применяется.

Для намеренной замены перевода используйте раздел Повторный перевод, а для пояснений по контексту — Примечания для переводчика. Но в любом случае нужно решить, кто управляет выходным значением.