Как локализовать веб-приложение
Подключите переведённые каталоги к выбору локали, загрузке ресурсов и проверкам отображения в вашем фреймворке.
Если веб-приложение уже отображает сообщения из файлов локалей, сохраните эту рабочую схему. Lingo.dev может переводить исходные каталоги, а существующая библиотека — по-прежнему выбирать локаль, загружать и отображать сообщения. Пройдите весь цикл для одного экрана, прежде чем переводить остальное приложение.
В этом руководстве мы разберём работу с существующими каталогами на основе ключей в разных фреймворках. Для сообщений, заданных исходным текстом и контекстом с помощью @lingo.dev/react, используйте краткое руководство по React или руководство по миграции. Идентификаторы, полученные при извлечении таких сообщений, отличаются от ключей в существующем каталоге i18next или next-intl.
Подготовьте один пример для сквозной проверки #
Выберите экран с подписью, сообщением с переменной и сообщением с формами множественного числа или условием. Отобразите его на исходном языке через существующую библиотеку. Сохраните пространства имён, синтаксис интерполяции и ключи поиска. Универсальный переводчик JSON не преобразует грамматику сообщений одной библиотеки в грамматику другой.
Если исходный файл react-i18next уже находится по пути public/locales/en/translation.json, инициализируйте CLI из корня проекта:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo linkПосле привязки .lingo/config.json должен выглядеть так:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}Сохраните фактические ИД организации и движка локализации, полученные при привязке. Для другого фреймворка подставьте путь к исходному файлу из соответствующего раздела ниже. Выбирайте только исходные каталоги, а целевой путь задайте так, чтобы он соответствовал загрузчику. Для структур без сегмента локали используйте явные целевые пути.
Чтобы создать недостающие переводы, выполните:
lingo push --backfill-missing --waitКогда перевод завершится, проверьте созданный каталог и откройте экран на испанском. Сравните сообщения с одинаковыми значениями переменных и вариантами множественного числа на обоих языках. В разделе для вашего фреймворка ниже описано, как подключить этот файл к реальному запросу или сборке. Первый обычный push позволяет сохранить начальное состояние, не запрашивая недостающие переводы.
Не меняйте целевые файлы, пока ожидаете обратную запись. Если нужно защитить существующие локальные исправления от конфликтов, отправьте запрос без --wait, проверьте lingo pull --dry-run, затем получите результаты в том же checkout, из которого отправляли запрос. См. Как сохранить проверенные переводы.
React с react-i18next #
При работе с react-i18next сохраните существующие пространства имён и вызовы поиска. Исходному файлу public/locales/en/translation.json соответствует public/locales/es/translation.json. Если приложение использует несколько пространств имён, укажите каждый английский исходный файл отдельно. Не используйте glob-шаблон, который захватит и созданные испанские файлы.
Настройте загрузчик ресурсов i18next так, чтобы он запрашивал целевую локаль и пространство имён. Затем отобразите тестовый пример с помощью существующих вызовов useTranslation. Проверьте подстановку переменных и правила именования ключей множественного числа в установленной версии i18next. Универсальный переводчик JSON не преобразует схему множественного числа одной библиотеки в схему другой. В клиентском приложении проверьте не только видимый текст, но и сетевой запрос ресурса: подстановка английского текста может скрыть отсутствие испанского файла.
Next.js App Router с next-intl #
В next-intl исходный файл часто находится по пути messages/en.json, а результат — по пути messages/es.json. Настройте в next-intl определение локали при обработке запроса и загрузку соответствующих сообщений. Маршруты и навигация с учётом локали должны соответствовать этому выбору.
Отобразите тестовый пример двумя способами: через прямой запрос с целевой локалью и через переход из другой локали. Проверьте содержимое, сформированное на сервере, гидратацию на клиенте, а также переменные или формы множественного числа ICU. Сам по себе перевод файла сообщений не добавляет сегмент локали в App Router или переключатель языка. Для объёмных документов, которые используются наряду с этими каталогами интерфейса, используйте Markdoc с Next.js.
Next.js Pages Router с next-i18next #
При работе с next-i18next настройте шаблон исходных файлов в соответствии с существующей папкой локалей и пространствами имён. Если это public/locales/en/common.json и public/locales/en/checkout.json, создайте для обоих файлов соответствующие испанские версии. Если вы используете messages/en.json, сохраните собственный загрузчик, который читает этот файл.
Загрузите нужные пространства имён через существующий механизм загрузки данных страницы — серверный или статический. Проверьте прямой запрос локализованной страницы и смену маршрута на клиенте. Убедитесь, что начальные данные страницы и клиентская среда используют одну и ту же локаль и пространство имён. Переведённого файла на диске недостаточно, если страница его не подключает.
Vue с vue-i18n #
vue-i18n может загружать словари вроде src/locales/en.json и src/locales/es.json. Переведите английский исходный файл и зарегистрируйте или динамически загрузите испанский словарь в существующем экземпляре i18n. Задайте выбранную локаль там, где приложение уже ею управляет.
Проверьте на тестовом примере вызовы $t или useI18n, вложенные ключи, интерполяцию и синтаксис сообщений с формами множественного числа в установленной библиотеке. Протестируйте переключение локали без перезагрузки и загрузку страницы с нуля. Если словари подключаются к сборке через импорт, убедитесь, что переведённый файл тоже в неё попал.
Nuxt с модулем i18n #
Для Nuxt i18n переведите исходный файл, например locales/en.json, в locales/es.json. Зарегистрируйте локаль и файл в конфигурации модуля с учётом установленной версии. Указанная папка языков должна соответствовать пути вывода CLI.
Используйте принятую в проекте стратегию маршрутизации с учётом локали, а не создавайте вторую в задании перевода. На тестовой странице проверьте серверное отображение, отложенную загрузку, локализованную навигацию и метаданные. Добавление целевой локали в конфигурацию перевода само по себе не добавляет её в список локалей Nuxt.
Словари Svelte и SvelteKit #
Для svelte-i18n переведите словарь, например src/lib/locales/en.json. Зарегистрируйте целевой словарь или его загрузчик для отложенной загрузки. Инициализируйте выбранную локаль до того, как она понадобится компоненту.
Отобразите тестовый пример через существующее хранилище переводов приложения. Если приложение использует SSR, проверьте новый запрос с серверным отображением, затем смените локаль на клиенте. Убедитесь, что состояние локали изолировано между серверными запросами, а целевой словарь полностью загружается. Отображение резервного текста не подтверждает, что перевод готов.
Angular XLIFF #
Сначала разметьте и извлеките сообщения с помощью рабочего процесса i18n в Angular. Обработчик XLIFF поддерживает XLIFF 1.2 и 2.x, включая обычный текст и встроенные коды. Текст внутри парных кодов, таких как <g> и <pc>, переводится с сохранением их структуры. Одиночные коды, такие как <ph>, остаются защищёнными. Не меняйте идентификаторы сообщений и встроенных кодов. Прежде чем импортировать целевой каталог, проверьте плейсхолдеры в результате.
Для поддерживаемых исходных файлов src/locale/en/messages.xlf соответствует src/locale/es/messages.xlf. XLIFF не использует замену суффикса messages.en.xlf на messages.es.xlf. Используйте папку локали или явный шаблон целевого пути. При возврате переводов в Angular сохраняйте идентификаторы сообщений.
Зарегистрируйте целевой файл в настройках локализованной сборки Angular, соберите пакет для целевой локали и запустите его, чтобы проверить экран. Локализация Angular на этапе компиляции отличается от загрузки JSON во время выполнения: смена локали браузера не создаст отсутствующую локализованную сборку. Прежде чем принять сборку, проверьте полноту перевода сообщений и отображение плейсхолдеров.
Astro #
Для подписей интерфейса переведите src/i18n/en.json в соответствующий целевой файл и настройте собственный загрузчик словарей так, чтобы он выбирал этот файл. Для коллекций контента переводите исходные файлы Markdown или MDX нужной локали и используйте рабочий процесс для статического контента.
Настройте маршрутизацию локалей Astro отдельно от перевода. Выполните сборку и откройте созданные маршруты для целевой локали. Проверьте ссылки между языковыми версиями и клиентские острова, которые загружают собственные сообщения. Для коллекции контента и словаря интерфейса острова могут потребоваться отдельные исходные файлы.
Laravel #
При локализации Laravel исходному PHP-файлу, например lang/en/messages.php, соответствует lang/es/messages.php. Сохраняйте ключи массивов и имена подстановок, используемых во время выполнения. Прежде чем выбирать файлы с исполняемым кодом за пределами поддерживаемой структуры каталога, изучите справочник по формату PHP.
Задайте локаль запроса через существующее промежуточное ПО или правила контроллера и отображайте сообщения с помощью функций перевода Laravel. Проверьте подстановку значений и выбор форм множественного числа. Протестируйте запрос для каждой поддерживаемой локали и случай с резервным языком. Переведённые файлы сами по себе не задают локаль запроса.
Django #
Создайте locale/en/LC_MESSAGES/django.po с помощью рабочего процесса извлечения сообщений Django, затем переведите этот исходный PO-файл, сохранив результат в папке целевой локали. Сохраните идентификаторы сообщений gettext, контекст и интерполяцию. На существующем этапе сборки gettext в проекте скомпилируйте переведённый PO-файл в ресурс, который загружает Django.
Настройте выбор языка в Django и список языков. Проверьте локализованный запрос через промежуточное ПО перевода и отобразите сообщения с помощью вызовов для единственного и множественного числа. Наличие PO-файла на диске не означает, что его скомпилированный каталог актуален. Требования к файлу см. в разделе Gettext.
Rails #
Rails определяет локаль YAML-файла по корневому ключу. Выберите yaml-root-key, затем проверьте настройки локалей Rails, вспомогательные функции и интерполяцию. Полный порядок работы описан в руководстве Как локализовать приложение Rails, включая отдельные файлы по функциональным областям, переключение локали запроса и обновления в заданных пределах.
Настройте регулярный перевод так, чтобы результаты было удобно проверять #
Когда экран заработает, добавьте остальные исходные каталоги и их загрузчики. Сохраняйте принятые целевые файлы вместе с ревизией исходных файлов и Lockfile CLI. При последующих изменениях исходного текста используйте lingo push --wait для обычной обработки изменений. Если вместо этого передать шаблон файлов как позиционный аргумент, планирование ограничится выбранными файлами.
Настройте запуск при изменении исходных файлов и обратную запись через GitHub App или рецепты CI. Рецепты для GitLab, Bitbucket и GitHub Actions запускают CLI, а обратную запись в репозиторий для них нужно настроить отдельно. Проверьте полученные файлы с помощью сборки фреймворка или проверок ресурсов, затем проверьте смысл перевода. lingo check не проверяет все фреймворки и не подтверждает полноту файлов PHP, PO или XLIFF.
Агент может помочь изучить загрузчики и предложить изменения конфигурации. Прежде чем расширять рабочий процесс, проверьте эти изменения по тем же критериям: выбор исходных файлов, сборка и отображение экрана.