Отдельная строка часто бывает неоднозначной. "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), ничего не дают — их лучше пропустить.
Примечания и конфигурация движка#
Примечания для переводчика задаются для отдельных строк и хранятся в исходных файлах. А правила, которые должны действовать для всей локали — терминология, тон, тональность бренда, — лучше задавать в движке, чтобы они применялись везде без примечания у каждого ключа.
