Как локализовать статический контент

Сопоставьте переведённые документы и каталоги с файлами, которые загружает сайт или рендерер, затем проверьте структуру, ссылки и итоговый результат.

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

Составьте список файлов по системам, которые их используют #

Отделите объёмные документы от структурированных каталогов и специализированных ресурсов. Для Markdown, MDX и Markdoc нужны рендерер и схема. Для каталогов JSON, YAML, TypeScript и PHP — загрузчик. PO и XLIFF работают со своими системами сообщений. SRT используется в рабочем процессе для медиа с привязкой ко времени.

Выберите по одному типичному исходнику из каждой группы. Определите путь к выходному файлу и загрузчик, который будет его использовать. Создаваемые переводы не должны попадать под шаблоны путей к исходникам. Сохраняйте ИД документов, URL, примеры кода, ключи каталогов и атрибуты компонентов, значения которых управляют поведением.

Выберите нужный обработчик в разделе Форматы. Обычный YAML отличается от YAML с локалью в корневом ключе и от YAML для OpenAPI. .xml не распознаёт ресурс Android автоматически. Одинаковое расширение ещё не означает, что обработчик понимает структуру документа.

Соблюдайте принятую на сайте структуру каталогов #

Уточните следующие особенности структуры с учётом загрузчика проекта:

СайтЧто выяснить перед переводом
DocusaurusКакие исходные документы превращаются в файлы в i18n/<locale>/docusaurus-plugin-content-docs/current/ и для каких версий документации или строк темы используются отдельные исходники.
NextraЧто загружает установленная конфигурация: страницы для каждой локали, словари или другое дерево контента. Сопоставьте каждый набор исходных данных отдельно.
HugoКакие файлы в content/<locale>/ считаются переводами одного материала и как определяются ссылки между языковыми версиями.
AstroКакие коллекции контента для отдельных локалей и словари интерфейса используются для каждого маршрута.
VitePressКакой префикс каталога локали и какие настройки навигации используются для создания переведённых страниц.
MkDocsКакой плагин i18n и какую структуру документации по локалям использует установленный проект.

В примере с Docusaurus исходные документы находятся в docs/. Установите и привяжите CLI из корня проекта:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link

Сохраните ИД организации и движка локализации в .lingo/config.json. Так как пути к этим исходникам не содержат локаль, замените запись файла явным шаблоном выходного пути:

json
{
  "pattern": "docs/**/*.md",
  "sourceRoot": "docs",
  "targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}

Для docs/setup/install.md путь [path] превращается в setup/install.md, поэтому перевод на испанский сохраняется в i18n/es/docusaurus-plugin-content-docs/current/setup/install.md. Убедитесь, что установленный плагин и его версия используют этот каталог. Правила проверки шаблонов и разрешения конфликтов описаны в разделе Конфигурация.

Выбирайте для перевода поля, которые видят читатели #

Для Markdown выберите поля frontmatter, которые видят читатели, например заголовок и описание. Не меняйте метаданные, связанные с идентификацией и публикацией. Для MDX и Markdoc также определите свойства компонентов, видимые читателям, например заголовок выноски. Свойства, управляющие поведением, и имена компонентов относятся к схеме приложения.

Используйте подходящий обработчик: файлы семейства Markdown не всегда взаимозаменяемы. Чтобы документ Markdoc, сохранённый как .md, обрабатывался как Markdoc, явно укажите формат markdoc. Ограничения выбора и восстановления структуры описаны в разделах Markdown, MDX и Markdoc. Сохраняйте блоки кода с разделителями как примеры, которые можно выполнить для проверки. Переводите пояснения к ним, не меняя команды.

Запустите перевод недостающих файлов:

sh
lingo push --backfill-missing --wait

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

Соблюдайте требования к структурированным каталогам #

Переводите строковые значения JSON и обычного YAML. Защитите ИД, адреса конечных точек и другие неязыковые данные с помощью настроек ключей обработчика. Для обычного YAML явно задайте format: "yaml" в конфигурации источника текущего CLI: одного определения формата по расширению недостаточно, чтобы отправить ненастроенный источник YAML. Используйте yaml-root-key, если локаль — корневой ключ, и yaml-openapi, если структура представляет собой документ OpenAPI. Для TypeScript и PHP используйте только поддерживаемые формы каталогов. Перевод файла не означает, что произвольный исходный код можно безопасно выполнить.

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

Обычные файлы .txt, например описания для магазинов приложений, переводятся построчно с сохранением строк исходника. Добавьте .txt в шаблон файлов, как в metadata/en/*.txt, или задайте "format": "txt": общий шаблон вроде docs/en/**/* не включает такие файлы. См. Обычный текст. CSV-таблица с отдельным столбцом для каждой локали переводится в том же файле: добавьте .csv в шаблон или задайте "format": "csv", как описано в разделе CSV. В текущей версии CLI среди настраиваемых форматов нет отдельных CSV-файлов для каждой локали, WebVTT и Java .properties. Справочник форматов CLI v0 предназначен для тех, у кого установлены старые версии CLI с этими рабочими процессами. Описанные в нём команды и конфигурация зависят от версии. Используйте справочник по миграции, чтобы выбрать поддерживаемый путь перехода и не потерять эти ресурсы без предупреждения.

Проверяйте субтитры вместе с медиа #

Для SRT переведите текст реплик и сверьте их номера и временные метки с исходником. Воспроизведите типичные сцены с переведёнными субтитрами. В самом проигрывателе проверьте объём текста для чтения, переносы строк, контекст речи и теги форматирования. Сохранённые временные метки не гарантируют, что переведённую реплику можно прочитать за отведённое время. Требования к файлу описаны в разделе SubRip. Не заменяйте SRT на WebVTT лишь потому, что оба формата используются для субтитров.

Масштабируйте проверенный процесс публикации #

Храните вместе конфигурацию, исходники, принятые переводы и Lockfile CLI. Изменив абзац, используйте lingo push --wait для обычной обработки изменений, затем сравните этот абзац и неизменённый раздел в переводе. Храните предыдущий исходник в паре с его переводом: после изменения структуры документа может быть неясно, какие фрагменты использовать повторно. Для позиционного шаблона действуют другие правила планирования в заданной области. Перед масштабным повторным переводом используйте рабочий процесс предварительной оценки. Рассматривайте оценки как информацию для планирования, а не как ценовое предложение.

Если локальные исправления перевода нужно защитить от расхождений, отправляйте без --wait и проверяйте lingo pull --dry-run перед получением результата. При прямой записи результата в режиме ожидания такой проверки нет. Следуйте руководству Как сохранить проверенные переводы.

Когда одна группа будет успешно собираться, выберите GitHub App или рецепты CI. Сохраните в этом цикле сборку сайта, проверку схемы, ссылок и контента: lingo check не подтверждает полноту документа. После каждого обновления должны оставаться читаемая страница на целевом языке и версия исходника, которую команда сможет использовать для следующего изменения.