FOnline Engine
Current master GitHub
Документация Docs/ru/contributing/documentation/translation.md

Процесс перевода документации

В документации FOnline английский язык служит каноническим источником, а русский перевод является полным зеркалом документа. Это руководство определяет метаданные перевода, глоссарий, проверку актуальности, политику ссылок и переход к production-режиму.

Текущее состояние миграции

Переход на локализованную структуру завершён. Каноническая документация для людей находится в парных маршрутах Docs/en/... и Docs/ru/..., а прежние плоские пути сохранены как долговечные Markdown-указатели. Пары README для репозитория и подсистем используют явное сопоставление, приведённое ниже. У каждой публичной страницы для людей есть:

  • один стабильный идентификатор документа;
  • один запланированный путь назначения Docs/en/...;
  • один производный зеркальный путь Docs/ru/... либо явная пара README;
  • один хэш канонического английского содержимого в сгенерированной модели состояния переводов.

Все 197 обязательных русских соответствий присутствуют, а localization.enforcement имеет значение complete. Каждая страница должна оставаться полной, соответствовать текущему хэшу, сохранять код и иметь правильную пару. Authoritative-инвентарём является сгенерированный отчёт; добавление новой обязательной английской страницы без русского соответствия немедленно проваливает проверку.

Текущий машинный отчёт: translation-status.json.

Результат 197/197 доказывает физический паритет страниц. Русские генерируемые страницы также могут содержать обращённый к читателю текст из машинных моделей, а не из Markdown-шаблона. Для этого семантического слоя существуют отдельные каталог и gate, описанные ниже; физический паритет нельзя представлять как полный семантический перевод сгенерированного содержимого.

Соглашение о каталогах

Используйте каталоги локалей в нижнем регистре, как принято на сайтах документации:

Docs/
|-- en/
|   |-- index.md
|   |-- tutorials/
|   |-- how-to/
|   |-- reference/
|   |-- explanation/
|   |-- troubleshooting/
|   `-- contributing/
`-- ru/
    `-- <the same relative paths>

Точки входа репозитория и подсистем вместо этого используют явные пары:

README.md
README.ru.md
BuildTools/README.md
BuildTools/README.ru.md

Языковые версии связываются стабильными идентификаторами документов. Переведённые названия и заголовки никогда не определяют идентичность.

Перевод одного документа

  1. Найдите запись в Docs/generated/translation-status.json.
  2. Прочитайте владеющие исходники и каноническую английскую страницу; не переводите устаревшее поведение.
  3. Используйте Docs/translation-glossary.json для общей терминологии.
  4. Создайте страницу точно по пути russian_path.

  5. Разместите однострочный комментарий с метаданными около начала файла:

    <!-- docs-translation: {"document_id":"getting-started","locale":"ru","source_path":"Docs/en/tutorials/getting-started.md","source_sha256":"<current hash>"} -->
  6. Переведите прозу, заголовки, подписи таблиц, альтернативный текст и обращённые к читателю предупреждения.
  7. Без изменений сохраняйте идентификаторы, пути к файлам, команды, код, теги метаданных, значения перечислений и fenced code blocks.
  8. Ссылайтесь на русское соответствие. Gate полного паритета отклоняет отсутствующую страницу вместо production fallback на английский маршрут.
  9. Запустите snippet gate для канонических английских fences, затем генератор локализации и фокусные тесты.

Вспомогательный инструмент может вывести точный хэш через сгенерированную модель состояния. Не вычисляйте и не редактируйте хэши независимо во втором формате.

Актуальность и паритет

BuildTools/docs_localization.py нормализует окончания строк и вычисляет SHA-256 по полному каноническому английскому исходнику. Для каждой существующей русской страницы он требует:

  • точный идентификатор документа;
  • локаль ru;
  • точный путь к каноническому исходнику;
  • текущий хэш нормализованного исходника;
  • идентичную упорядоченную последовательность fenced code blocks;
  • сохраняющие язык ссылки везде, где существует русская страница назначения.

Запуск:

python BuildTools/docs_localization.py --write
python BuildTools/tests/test_docs_localization.py
python BuildTools/docs_localization.py --check --enforce-complete

Manifest также включает этот production gate по умолчанию; явный флаг делает намерение локального и CI-запуска очевидным:

python BuildTools/docs_localization.py --check --enforce-complete

Изменение английской страницы немедленно делает русский хэш недействительным. Обновите обе версии в одном изменении либо оставьте ветку падающей; не обновляйте хэш без повторной проверки перевода.

Текст из генерируемых моделей

Docs/description-translations.ru.json служит проверяемым русским overlay для обращённого к читателю текста из генерируемых контрактных моделей. Каждая запись использует стабильный локатор внутри домена, производный от владеющего id, name или другого уникального ключа исходника, и нормализованный хэш точного английского значения. Позиции массивов запрещены как идентификаторы. Поэтому перестановка записей исходника сохраняет привязку переводов, а изменение английского текста немедленно делает владеющую запись устаревшей.

BuildTools/docs_description_translations.py инвентаризирует 19 генерируемых моделей, отклоняет повторяющиеся, неизвестные, устаревшие, меняющие тип или inline-code записи и создаёт description-translation-status.json. Генераторы накладывают overlay на глубокую копию модели: канонический JSON и английский Markdown не меняются, а русский Markdown получает переведённые описания до локализации фиксированных подписей и заголовков.

Каталог использует режим complete: все 4 811 обращённых к читателю значений во всех 19 генерируемых доменах, включая native API, имеют актуальные проверенные записи. CI и локальная проверка отклоняют отсутствующие, неизвестные, устаревшие, меняющие тип, форму списка или inline-code записи. Если генератор начинает выводить новое обращённое к читателю значение, добавьте проверенный перевод в том же изменении; неполный каталог не считается допустимым промежуточным состоянием.

Translation memory по точному source позволяет не дублировать проверенную прозу, когда один generated contract проецирует другой. Отсутствующий locator может переиспользовать перевод каталога из того же домена только при совпадении нормализованного SHA-256 и полного исходного значения. Все donors этого source обязаны иметь одинаковый перевод; иначе locator остаётся missing и режим complete завершается ошибкой. Status record указывает donor в поле translation_source_locator. Сгенерированные значения enum *Property используют этот путь, чтобы разделять проверенный перевод owning property без второй копии для сопровождения.

Запуск:

python BuildTools/docs_description_translations.py --write --enforce-complete
python BuildTools/tests/test_docs_description_translations.py
python BuildTools/docs_description_translations.py --check --enforce-complete

В переводимом значении точно сохраняйте стабильные ID, сигнатуры, пути, значения перечислений, команды и inline code. Используйте preserve_source: true только тогда, когда всё видимое читателю значение намеренно не зависит от языка, например WebGL 2; это поле не может оправдать непереведённую прозу.

Политика глоссария

Каждая запись глоссария использует одну политику:

  • preserve — сохранить английское или продуктовое написание;
  • translate — использовать проверенный русский термин в прозе;
  • contextual — переводить прозу, но сохранять точные идентификаторы, пути, имена целей или устоявшееся техническое написание.

Добавляйте термины, когда два правдоподобных перевода способны изменить смысл, владение, стабильность или заявления о поддержке. Глоссарий не является словарём каждого общеупотребительного слова.

Идентификаторы API остаются без перевода. Обращённые к читателю описания API используют описанный выше каталог генерируемых описаний; стабильные идентификаторы и сигнатуры остаются побайтно идентичными.

Политика ссылок

Внутри русской страницы:

  • ссылайтесь на русское соответствие, если оно существует;
  • сохраняйте ту же семантику якоря;
  • используйте каноническую английскую страницу только как явно временный fallback;
  • никогда не формируйте пути локалей из переведённых названий;
  • сохраняйте внешние source-ссылки закреплёнными либо плавающими согласно политике владеющей английской страницы.

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

Поиск разделён по локалям. Английские страницы загружают assets/docs-search.json, русские — assets/docs-search.ru.json. У каждого индекса одинаковый fail-closed лимит размера; он содержит только доступные в этой локали документы и должен возвращать URL с сохранением языка. Благодаря этому полный будущий русский перевод ограничивается независимо от английского корпуса.

Контрольный список ревью

  • Поведение всё ещё соответствует текущим исходникам и тестам Engine.
  • Не пропущены ни одно требование, предупреждение, ограничение, шаг восстановления, строка таблицы или альтернативный текст.
  • Команды и fenced code не изменены и проходят тот же snippet harness, что и английская версия; заявленные семантические результаты по-прежнему проходят владеющий compile/bake/smoke-тест.
  • Идентификаторы, пути, настройки, теги и расширения не изменены.
  • Терминология соответствует глоссарию.
  • Ссылки сохраняют язык там, где существуют соответствия.
  • Хэш английского исходника совпадает.
  • Носитель русского языка подтвердил смысл и тон.
  • Поиск находит страницу по русской лексике задачи и техническим идентификаторам.
  • На мобильном экране сохраняется читаемость макета, таблиц, блоков кода и длинных идентификаторов.
  • Browser profile zoom-200 сохраняет читаемость русской страницы при CSS viewport 640 x 512 и device scale factor 2, а сохраняемый screenshot 1280 x 1024 просмотрен визуально.

Машинные проверки защищают структуру и актуальность; они не способны подтвердить качество перевода.

Перенос канонических путей

Переносите страницы проверенными группами:

  1. создайте каноническую страницу Docs/en/...;
  2. создайте и проверьте парную страницу Docs/ru/...;
  3. сохраните старый Markdown-путь как долговечный указатель;
  4. обновите путь исходника в manifest, сохранив стабильный идентификатор;
  5. перегенерируйте маршруты, навигацию, поиск, состояние локализации и AI-артефакты;
  6. проверьте отрендеренный артефакт _site и маршруты обоих языков;
  7. проверьте старые ссылки и якоря;
  8. сливайте изменение только при зелёном паритете переводов.

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

Два связанных вводных руководства являются такой контрольной группой. Их канонические английские и русские маршруты, старые маршруты-указатели и якоря, локаль во front matter, переключение языка и русский поиск остаются обязательными regression fixtures для каждой следующей группы.

Переход в production

Для двуязычного запуска необходимы:

  1. полное русское покрытие каждой актуальной публичной страницы для людей с translation: required;
  2. проверенные глоссарий и полный каталог генерируемых описаний;
  3. README.ru.md и парные README подсистем и примеров;
  4. режим полной проверки в manifest и CI;
  5. двуязычные навигация и поиск, а также сохраняющие язык ссылки;
  6. ревью носителем языка, автоматический русский 200-percent reflow profile и representative assistive-technology review;
  7. проверка отрендеренного артефакта GitHub Pages;
  8. удаление временного разрешения translation-pending.

После запуска обновления Engine и embedding-проектов должны учитывать влияние на перевод в том же аудите документации. Существующий перевод никогда не должен оставаться зелёным относительно старого хэша исходника.

Введите запрос.