Заметки для переводчика

Сама по себе строка часто неоднозначна. "Records" может означать медицинские карты, музыкальные записи или строки в базе данных. В исходных файлах JSONC комментарий над ключом передаётся движку как контекст, чтобы он выбрал верное значение при переводе:

jsonc

{
  // Medical context: patient medical records
  "records": "Records"
}

Комментарий никогда не попадает в результат — он только направляет перевод.

Где работают заметки#

Заметки для переводчика считываются из исходных файлов JSONC (.jsonc). Укажите такой файл в записи files[]:

json

{ "pattern": "content/en/app.jsonc" }

В JSON (.json) комментариев нет, поэтому добавить заметки в него нельзя. Если они нужны, используйте для этого файла JSONC.

Переходите с устаревшего CLI? Он тоже считывал заметки из каталогов строк Xcode (.xcstrings). Текущий CLI этот формат не поддерживает, поэтому сегодня комментарии JSONC — основной способ добавить контекст.

Как писать полезные заметки#

Хорошая заметка добавляет контекст, которого нет в самой строке:

jsonc

{
  // Button in the checkout flow — keep it short
  "checkout.pay": "Pay now",

  // "Set" here means a collection, not the verb
  "library.set": "Set",

  // Formal tone — shown in the legal footer
  "footer.terms": "Terms of Service"
}

Заметка	Чем помогает
`// Appears in the top nav`	подсказывает движку, где будет показан текст и насколько кратким он должен быть
`// "Light" is the theme, not weight`	снимает неоднозначность слова с несколькими значениями
`// Formal register`	задаёт нужный тон

Заметки, которые просто повторяют строку (// This says Welcome), ничего не дают — их можно не писать.

Заметки и конфигурация движка#

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