JSON

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

В каталоге JSON приложение находит ключ и показывает его значение. Обработчик файлов json меняет строковые значения, сохраняя ключи объектов, позиции в массивах, числа, логические значения и null как данные. Он заново собирает целевой файл из текущего исходного, подставляя новые переводы или сохранённый текст целевого файла.

Обработчик поддерживает каталоги с вложенными объектами и массивами, а также строку в корне. CLI определяет json по .json. Настройте источник в разделе Конфигурация CLI или через GitHub App.

Какие значения попадают на перевод #

Например:

json
{
  "checkout": {
    "title": "Complete your order",
    "delivery": "Delivery within {days} days"
  },
  "plans": [
    { "name": "Personal", "seats": 1 },
    { "name": "Team", "seats": 10 }
  ],
  "enabled": true
}

Обработчик выбирает checkout.title, checkout.delivery, plans[0].name и plans[1].name. Числа seats и логическое значение enabled остаются без изменений. Явно задавайте защиту для строковых идентификаторов: тип значения в JSON говорит обработчику, что это текст, но не указывает, предназначен ли он для чтения людьми.

В краткой записи пути точки обозначают переходы по объектам, а квадратные скобки — позиции в массивах: checkout.title выбирает вложенное значение, а plans[0].name — название первого плана. Если ключ буквально называется checkout.title, используйте запись JSONPath с кавычками: $['checkout.title']. Синтаксис выбора описан в разделе управления ключами.

Как обновления используют готовые переводы #

Запуск с обработкой изменений использует три отдельных набора входных данных:

Входные данныеРоль
Текущий исходный файлЗадаёт структуру и строки нового результата.
Предыдущий исходный файлПомогает определить, изменилась ли исходная строка по тому же пути.
Существующий целевой файлСодержит переводы, которые можно сохранить.

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

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

Храните предыдущий исходный файл в паре с принятым целевым. Если одного из них нет, обработчик работает со строками как при первом запуске. Lockfile и кэш CLI связывают эти входные данные между запусками.

Выберите, что делать с защищёнными путями #

Эти настройки по-разному влияют на результат:

НастройкаПри переводеВ результате
Заблокированный путьИсключён из перевода.Значение берётся из текущего исходного файла.
Сохраняемый путьИсключён из перевода.Если путь есть в целевом файле, сохраняется его текущее значение. Иначе остаётся исходное значение.
Игнорируемый путьИсключён из перевода.Путь удаляется из создаваемого целевого файла.
Подстановка локалиУказанное поле локали исключается из перевода.В это поле записывается целевая локаль.

Заблокируйте общий идентификатор, если во всех локалях нужно использовать исходное значение. Сохраните URL, заданный для целевой локали, если у каждой локали свой адрес назначения. Игнорируйте примечание только для исходного файла, если оно не должно попадать в переведённый файл. Эти настройки не означают одно и то же — «не переводить».

Для одного и того же пути блокировка имеет приоритет над сохранением: если значение указано в обоих списках, оно берётся из исходного файла. Игнорирование удаляет значение, даже если оно также заблокировано, сохраняется или выбрано для подстановки локали. В месте подстановки локаль имеет приоритет над блокировкой и сохранением. Старайтесь задавать для каждого значения одно управляющее правило. Если правила пересекаются в объекте или массиве, проверяйте результат.

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

Задайте эти настройки с помощью полей записи файла в CLI или параметров записи файла в GitHub.

Область обновления и ограничения пересборки #

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

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

Рабочий процесс перевода проверяет структуру поддерживаемых плейсхолдеров и ICU, в том числе изменённые или отсутствующие аргументы. Изучите предупреждения и ошибки, затем отобразите принятый шаблон со значениями из приложения. Эти проверки не определяют, передаёт ли переведённое сообщение нужный смысл.

Загрузите результат в приложение с типичными значениями. Убедитесь, что защищённые пути сохраняют нужные исходные или целевые данные, а сообщение о доставке после подстановки по-прежнему передаёт то же обещание. Разбор проверяет синтаксис JSON, а отображение и чтение — сообщение, которое увидят люди.