Как локализовать статический контент
Сопоставьте переведённые документы и каталоги с файлами, которые загружает сайт или рендерер, затем проверьте структуру, ссылки и итоговый результат.
Дерево исходных файлов сайта уже связывает статьи с маршрутами, метаданными, навигацией и рендерером. Добавьте переведённые файлы туда, откуда система сможет их загрузить. Первый полезный результат — полноценная страница на целевом языке по нужному маршруту, с рабочими ссылками и теми же примерами кода, что и в исходнике.
Составьте список файлов по системам, которые их используют #
Отделите объёмные документы от структурированных каталогов и специализированных ресурсов. Для 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 из корня проекта:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo linkСохраните ИД организации и движка локализации в .lingo/config.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. Сохраняйте блоки кода с разделителями как примеры, которые можно выполнить для проверки. Переводите пояснения к ним, не меняя команды.
Запустите перевод недостающих файлов:
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 не подтверждает полноту документа. После каждого обновления должны оставаться читаемая страница на целевом языке и версия исходника, которую команда сможет использовать для следующего изменения.