Сама по себе строка часто неоднозначна. "Records" может означать медицинские карты, музыкальные записи или строки в базе данных. В исходных файлах JSONC комментарий над ключом передаётся движку как контекст, чтобы он выбрал верное значение при переводе:
{
// Medical context: patient medical records
"records": "Records"
}Комментарий никогда не попадает в результат — он только направляет перевод.
Где работают заметки#
Заметки для переводчика считываются из исходных файлов JSONC (.jsonc). Укажите такой файл в записи files[]:
{ "pattern": "content/en/app.jsonc" }В JSON (.json) комментариев нет, поэтому добавить заметки в него нельзя. Если они нужны, используйте для этого файла JSONC.
Переходите с устаревшего CLI? Он тоже считывал заметки из каталогов строк Xcode (.xcstrings). Текущий CLI этот формат не поддерживает, поэтому сегодня комментарии 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), ничего не дают — их можно не писать.
Заметки и конфигурация движка#
Заметки для переводчика задаются для отдельных строк и хранятся в исходниках. Если правило должно действовать для всей локали — например, терминология, тон или тональность бренда, — лучше задать его в движке, чтобы оно применялось везде без заметки у каждого ключа.
