Сообщения и контекст
Пишите исходные сообщения целиком, объясняйте их смысл и подставляйте меняющиеся значения, сохраняя идентичность сообщений.
Чтобы перевод сохранял смысл сообщения или описанное в нём действие, нужно достаточно информации. Пишите исходный текст целиком и объясняйте, как он используется, в context. Передавайте имена, количества и другие меняющиеся данные через values.
import { useLingo } from "@lingo.dev/react";
export function Greeting({ name }: { name: string }) {
const l = useLingo();
return (
<h1>
{l.text("Welcome back, {name}.", {
context: "Greeting at the top of the account dashboard",
values: { name },
})}
</h1>
);
}Результат — строка. Для TextOptions обязателен context: string, также можно передать values?: Record<string, string | number>. В каталоге хранится шаблон предложения. В переводе {name} можно переместить туда, где этого требует грамматика.
Объясняйте смысл неоднозначных сообщений #
«Save» может означать отправку формы или добавление статьи в закладки. Контекст позволяет различать эти сообщения, хотя их исходный текст на английском совпадает:
import { computeKey } from "@lingo.dev/react";
const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");У сообщений разные ключи, поэтому переводчик может выбрать подходящий глагол для каждого действия. Контекст вроде «Текст, который видит пользователь» не устраняет неоднозначность. Опишите действие, аудиторию или ограничение, которое может повлиять на формулировку.
Инструмент извлечения записывает эту информацию в комментарий @context в каталоге. Это подсказка для перевода, а не текст интерфейса. Общую терминологию, инструкции и требования к тону общения задавайте в контексте перевода движка локализации, а смысл конкретного сообщения описывайте рядом с вызовом.
Идентичность сообщения #
computeKey(source: string, context?: string): string создаёт ключ из восьми символов на основе исходного текста и контекста. Он соединяет непустой контекст с исходным текстом через нулевой разделитель, нормализует результат в Unicode NFC и хеширует его байты в UTF-8.
Канонически эквивалентные записи Unicode получают один и тот же ключ. Изменение формулировки, пунктуации, регистра, пробельных символов или контекста может привести к появлению нового ключа. Значения не участвуют в хешировании, поэтому для любого имени в приветствии используется одна и та же запись сообщения.
После изменения исходного текста или контекста снова запустите извлечение и проверьте новые записи и записи, которые больше не используются. Если скопировать перевод под новый ключ без проверки смысла, можно сохранить именно ту формулировку, которую и нужно было заменить. Число возможных хешей ограничено. Инструмент извлечения обнаруживает коллизии среди собранных сообщений.
Пишите вызовы так, чтобы сообщения можно было извлечь #
В вызовах вроде l.text(...) задавайте исходный текст и контекст строковыми литералами. Во время выполнения можно передать вычисленную строку, но инструмент извлечения не может определить все строки, которые программа способна создать. В качестве получателя вызова используйте l или поддерживаемую переменную, созданную через useLingo или createLingo. Распознаваемые формы описаны в справочнике по extract.
Используйте плейсхолдеры для меняющихся данных вместо того, чтобы создавать исходные строки вроде "Welcome, " + name. Неизменный шаблон можно извлечь, перевести один раз для каждого смысла и использовать повторно с разными значениями.
Интерполяция и ICU #
У простых плейсхолдеров есть имена, например {name}. Переданные значения преобразуются в текст. Если значение для простого плейсхолдера не передано, он остаётся видимым. Если не передать объект values, выбранный шаблон вернётся без интерполяции.
Когда грамматика зависит от количества или категории, текстовый форматтер поддерживает сложные шаблоны ICU через intl-messageformat:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
context: "Number of files attached to a message",
values: { count: 0 },
});Этот вызов возвращает No files. Явно заданная ветвь =0 обрабатывает ноль отдельно от обычных категорий множественного числа локали. Передавайте все аргументы, которые нужны выбранному шаблону. Если не удаётся разобрать или отформатировать сложный шаблон ICU, среда выполнения возвращает этот шаблон и сообщает об ошибке в режиме разработки, не дублируя одинаковые сообщения. Она не заменяет некорректный перевод заново отформатированным исходным текстом.
В разделе Множественное число и выбор вариантов описаны вспомогательные функции для полных вариантов текста. Форматированный текст позволяет вставлять элементы React с помощью отдельного парсера именованных тегов. Выбирайте подходящий способ, а не смешивайте сложные выражения ICU с шаблонами форматированного текста.