Как перенести существующие сообщения React

Перенесите небольшой тестовый пример React на явные сообщения с исходным текстом и контекстом, сохранив плейсхолдеры, правила множественного числа и утверждённые переводы.

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

Зафиксируйте прежнее поведение перед сменой идентификаторов #

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

Например, существующий вызов в стиле i18next может выглядеть так:

tsx
t("account.greeting", { name });

В исходном каталоге может быть Welcome, {{name}}. Не копируйте этот синтаксис интерполяции в новый контракт сообщений без изменений. В явном сообщении React используется именованная переменная {name}:

tsx
l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

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

Сопоставляйте поведение сообщений, а не только имена методов #

Используйте text для простых сообщений со значениями, rich — для именованных слотов компонентов, plural — для форм, зависящих от количества, а select — для вариантов по точному значению с запасным вариантом other. Полный пример всех четырёх подходов есть в разделе Интерактивные сообщения с разметкой.

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

Выберите контекст, который объясняет, где и как используется сообщение. Новый идентификатор строится на основе исходной формулировки и контекста, а не account.greeting. Ведите таблицу переноса: старый ключ, локаль, извлечённый новый ключ и изменения синтаксиса. Для приветствия укажите в этой строке преобразование {{name}} в {name}. По такому сопоставлению при проверке можно проследить, как утверждённая формулировка попала в новый каталог, и увидеть сообщения, для которых соответствия ещё нет.

Внимательно извлеките и импортируйте небольшой каталог #

Установите @lingo.dev/react и настройте LingoProvider по краткому руководству по React. Для текущей реализации провайдера используйте React 19. Заявленный диапазон совместимости с React 18 в peer-зависимостях не заменяет тестирование приложения на более старой версии. После преобразования компонента запустите установленный CLI:

sh
lingo extract --src src --source-locale en

Если пути не переопределены, проверьте locales/en.jsonc и lingo.d.ts. Найдите каждое исходное сообщение и его контекст, затем скопируйте в таблицу переноса ключ, полученный при извлечении. Если оставить старый ключ или придумать хеш, среда выполнения не сможет найти соответствующий перевод.

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

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

Проверьте, что происходит с отсутствующими и некорректными сообщениями #

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

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

Для некорректного тега разметки или сообщения ICU изучите результат и диагностические сообщения. Новая среда выполнения может показать разметку как обычный текст или оставить шаблон без форматирования. Прежде чем удалять старую среду выполнения, проверьте, соответствует ли такое поведение требованиям приложения. Эти ограничения описаны в разделе Устранение неполадок React.

Проверяйте работу, выполненную с помощью агента #

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

Когда тестовый пример пройдёт проверки отображения и проверки в целевой среде, продолжайте перенос по компонентам или пространствам имён. Сохраняйте оба каталога, пока не проверите, куда перенесены каждый вызов и каждый утверждённый перевод. Удаляйте старый провайдер и зависимость, только когда в коде больше нет обращений к ним. У клиентов API и адаптеров маршрутизатора свои задачи: смена среды выполнения сообщений их не заменяет.