Перейти к основному содержимому

Руководство по интернационализации

Это руководство описывает локализационный фреймворк в builder-docs.

Русская локаль была первой полной реализацией, но теперь это уже не отдельный разовый проект. Следующие локали должны использовать тот же каркас:

  • общий реестр локалей
  • собственные для локали файлы glossary и policy
  • безопасный bootstrap без перезаписи вычитанного контента
  • редакционный QA по волнам
  • маршрутизация, SEO и discovery-артефакты с учётом локали
  • локализованные FastNear-оверлеи без изменения сгенерированного английского источника

Цели​

Этот фреймворк нужен, чтобы следующие локали были в основном задачей контента, а не инфраструктуры.

Базовые правила такие:

  • английский остаётся локалью по умолчанию на /
  • локализованные docs публикуются по /<locale>/...
  • канонические технические идентификаторы не переводятся
    • slug
    • пути эндпоинтов
    • ключи payload
    • имена свойств схем
    • operation ID
  • локализация сгенерированного контента остаётся оверлеем, а не правкой vendored-данных на месте

Основные файлы​

Реестр локалей​

Поддерживаемые локали находятся в src/data/localeRegistry.json.

Этот реестр является общим источником истины для:

  • конфигурации локалей Docusaurus
  • locale-aware route helpers
  • bootstrap и audit-скриптов
  • клиентских метаданных для скрытых разделов

Глоссарий локали​

У каждой недефолтной локали есть i18n/<locale>/glossary.yml.

Глоссарий задаёт терминологический контракт и для людей, и для скриптов. Благодаря этому решения о переводе не расползаются по JS-массивам и prose-документам.

Текущая схема:

  • preserve Термины, которые должны оставаться в канонической форме, например RPC, API, JSON-RPC, GET, POST, FastNear, mainnet.
  • translate Предпочтительные точные и словарные замены для повторяющихся UI- и docs-фраз.
  • transliterate Предпочтительные транслитерации для технического жаргона, если это лучше, чем оставлять латиницу.
  • notes Человеческие примечания с редакционным смыслом, которые не нужны скриптам напрямую.

Policy-файл локали​

У каждой недефолтной локали есть и i18n/<locale>/translation-policy.yml.

Этот файл описывает редакционный объём и правила процесса:

  • waves.wave1 Обязательные для ship docs и page model IDs. Это редакционная планка, которую проверяет CI.
  • waves.wave2 Более широкий публичный охват для следующего прохода.
  • hiddenSections Префиксы маршрутов и путей docs, которые намеренно остаются вне редакционной планки, пока раздел не станет публичным.
  • bootstrap Локальные route labels и JSON overrides, которые использует scaffold-поток.

Для русской локали первым таким скрытым разделом является /transaction-flow.

Общие команды​

Теперь фреймворк использует generic-команды вместо русско-специфичных скриптов.

yarn bootstrap:i18n --locale <code>
yarn bootstrap:i18n:reseed --locale <code>
yarn audit:i18n --locale <code> --wave <1|2|all>
yarn audit:i18n:all

Что они делают:

  • bootstrap:i18n Безопасно обновляет scaffold и добавляет отсутствующие файлы и ключи, не перезаписывая вычитанный контент.
  • bootstrap:i18n:reseed Явно разрушительный режим для случая, когда локаль нужно полностью пересоздать из bootstrap-эвристик.
  • audit:i18n Glossary-aware редакционный QA для одной локали и выбранной волны.
  • audit:i18n:all CI-ориентированная проверка wave1 для всех недефолтных локалей.

Русские совместимые алиасы всё ещё поддерживаются:

yarn bootstrap:i18n:ru
yarn bootstrap:i18n:ru:reseed
yarn audit:i18n:ru

Но каноническим интерфейсом теперь считаются generic-команды.

Как работает bootstrap​

scripts/bootstrap-i18n.js по умолчанию ведёт себя безопасно.

Для локали вроде ru он:

  • запускает write-translations --locale ru
  • создаёт отсутствующие docs в i18n/ru/docusaurus-plugin-content-docs/current
  • сохраняет уже вычитанные локальные docs
  • добавляет отсутствующие runtime-ключи в locale JSON catalogs
  • обновляет src/data/fastnearTranslations.<locale>.json, не выбрасывая уже вычитанные оверлеи
  • применяет локальные route labels и JSON overrides из translation-policy.yml

То есть свежесть scaffold и ручная редактура больше не конфликтуют.

Как работает audit​

scripts/audit-i18n.js — это лёгкий редакционный барьер качества.

Он читает:

  • glossary локали для списка допустимых literal-терминов
  • translation policy для границ волн и исключений скрытых разделов
  • docs локали в i18n/<locale>/...
  • runtime translation catalogs локали
  • FastNear overlay catalog локали

Проверка ищет подозрительные английские остатки, но уважает допустимые literal-термины:

  • названия протоколов
  • HTTP verbs
  • продуктовые имена
  • code identifiers
  • канонические фрагменты путей

Это практический QA, а не попытка отполировать весь длинный хвост в первый же день.

Политика волн​

Каждая локаль должна проходить через одну и ту же редакционную модель.

Wave 1​

Wave 1 — это shipping bar.

Сюда входят:

  • главная страница и ключевые decision pages
  • основные входные точки для auth, API, RPC и transactions
  • самые заметные generated operation wrappers и overlay entries
  • живые runtime UI strings на этих страницах

Только Wave 1 проверяется в CI.

Wave 2​

Wave 2 — это расширение публичной поверхности.

Сюда входят:

  • дополнительные leaf docs
  • overview-страницы из длинного хвоста
  • дополнительные generated overlay entries
  • менее приоритетный, но всё ещё публичный runtime copy

Wave 2 важен, но специально остаётся неблокирующим.

Long tail​

Long-tail работа — это дальнейшая полировка:

  • maintainer docs
  • редкие leaf pages
  • редко видимые theme strings
  • малопосещаемые generated pages

Эта работа должна продолжаться, но не должна блокировать здоровый выпуск локали.

Скрытые разделы​

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

Источник истины — translation-policy.yml.hiddenSections.

Эти префиксы влияют на две вещи:

  • исключаются из обязательной wave1-готовности
  • на страницах этих разделов показывается заметный баннер, который объясняет, что перевод и редакторская полировка намеренно отложены до публикации раздела

Сейчас по этому правилу живёт /transaction-flow.

Runtime, маршрутизация и discovery​

Фреймворк покрывает не только prose, но и остальные поверхности, которые будущие локали должны наследовать автоматически.

Важные файлы:

  • docusaurus.config.js
  • src/utils/localizedRoutes.js
  • src/utils/fastnearLocalization.js
  • scripts/generate-ai-surfaces.js
  • plugins/finalizeLocalizedStaticAssets.cjs

Вместе они обеспечивают:

  • корректную работу locale dropdown и locale-aware routing
  • сохранение активной локали для внутренних ссылок
  • локализацию FastNear overlay без изменения source page models
  • выпуск локализованных Markdown mirrors, llms.txt и site graph из правильного корня локали
  • локализованные URL и inLanguage в structured data и SEO

Лёгкий CI-барьер​

Locale-quality gate намеренно сделан небольшим.

Обязательный workflow запускает:

yarn audit:i18n:all
yarn build
node scripts/audit-indexing-surface.js

Этого достаточно, чтобы защитить:

  • качество wave1
  • корректность сборки
  • корректность discovery и indexing

Playwright, relevance scoring и более тяжёлые редакционные проверки сюда специально не включены.

Как добавить новую локаль​

Используйте такой чеклист:

  1. Добавьте локаль в src/data/localeRegistry.json.
  2. Создайте i18n/<locale>/glossary.yml.
  3. Создайте i18n/<locale>/translation-policy.yml.
  4. Запустите yarn bootstrap:i18n --locale <code>.
  5. Вычитайте i18n/<locale>/code.json и дерево docs.
  6. Добавьте src/data/fastnearTranslations.<locale>.json для generated FastNear overlay.
  7. Запустите yarn audit:i18n --locale <code> --wave 1.
  8. Запустите yarn build и node scripts/audit-indexing-surface.js.
  9. Добавьте браузерные smoke-checks только там, где локаль вносит новое runtime-поведение.

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