Машинный перевод
Эта страница была автоматически переведена ИИ и может содержать ошибки. Если что-то неясно, обращайтесь к английскому источнику.
Интернационализация¶
Документация рассматривает английский и упрощенный китайский как проверенные канонические источники. Все остальные включенные локали являются производными, созданными автоматически. Реестр языков, маршрутизация источников, конфигурация модели и ограничения API находятся в i18n/config.toml.
1. Охват языков и маршрутизация источников¶
Реестр намеренно включает сфокусированный набор из 12 локалей сайта. Он охватывает все шесть официальных языков ООН: арабский, китайский, английский, французский, русский и испанский. Дополнительно он включает японский, корейский и традиционный китайский для Восточной Азии, а также немецкий, итальянский и португальский для Европы. Английский и упрощенный китайский являются каноническими, поэтому 10 локалей переведены машинным способом.
Японский, корейский и традиционный китайский используют упрощенный китайский в качестве источника. Все остальные созданные локали используют английский. Выбор источника явно задан для каждой локали; переводчик никогда не угадывает по названию локали или символам документа.
Добавление локали требует соответствующих записей в i18n/config.toml и списке языков MkDocs i18n. Аудит документации отклоняет несогласованные реестры.
2. Контракт канонических документов¶
Каждая страница MkDocs имеет файл на английском и файл .zh-CN.md. Запрос на включение изменений, отправка в main или запуск контроля качества вручную, изменяющий одну каноническую версию, должен включать ее аналог в проверяемом диапазоне коммитов. Рабочий процесс контроля качества проверяет:
- канонические пары и связь измененных пар;
- соответствие уровней заголовков и блоков кода;
- локальные ссылки и ссылки на источники;
- инвентаризацию тестовых данных и тестов;
- строгую сборку каждой настроенной локали.
Канонический текст может быть написан вручную или с помощью ИИ, но он должен быть зафиксирован и проверен как обычный исходный код. API перевода никогда не вызывается из рабочего процесса запроса на включение изменений.
3. Нумерация заголовков и стабильность фрагментов¶
Исходный код Markdown хранит описательный текст заголовков без номеров структуры. Во время каждой сборки MkDocs scripts/mkdocs_heading_numbers.py добавляет номера страниц к заголовкам H2–H6. Страницы руководства пользователя используют строчные буквы для H2 (a., b.) и буквенно-цифровые потомки (a.1, a.1.1); другие страницы сохраняют десятичную нумерацию страниц. Отдельно левая навигация руководства пользователя использует иерархические десятичные номера, такие как 1.1. Заголовки страниц H1 и разделы навигации верхнего уровня остаются без номеров. Сгенерированные номера являются метаданными представления: перемещение раздела изменяет его видимый номер, не изменяя его идентификатор фрагмента.
Хук сборки делает каждый идентификатор заголовка явным перед добавлением видимого номера. i18n/legacy-heading-anchors.json сохраняет псевдонимы для фрагментов, которые были опубликованы до удаления сохраненных номеров структуры. Не редактируйте эту сгенерированную карту совместимости без необходимости и не добавляйте ручные номера структуры обратно в канонический или сгенерированный Markdown; аудит документации отклоняет их.
4. Контракт сгенерированных документов¶
Сгенерированные страницы используют режим суффиксов MkDocs, например index.fr.md или guide/configuration.ja.md. Каждая страница содержит детерминированные метаданные, записывающие:
- каноническую исходную локаль и путь;
- дайджест SHA-256 исходного файла;
- используемую модель и версию промпта;
- что страница является машинным переводом.
i18n/manifest.json дополнительно записывает дайджесты вывода и отпечатки входных данных перевода. Страница становится устаревшей, когда изменяются ее исходный код, глоссарий, промпт, модель или сгенерированный вывод. Переводчик запрашивает только устаревшие единицы, если только не запрошена полная перестройка.
Переведенные заголовки сохраняют свои естественные локализованные слагы и получают скрытые псевдонимы для канонических исходных слагов. Поскольку цели ссылок Markdown в остальном защищены от изменений модели, эти псевдонимы сохраняют ссылки на фрагменты на той же странице и между страницами действительными для каждой локали. Псевдонимы можно обновить офлайн без дополнительного вызова API перевода.
Сгенерированные файлы нельзя редактировать вручную. Рабочий процесс перевода основной ветки регенерирует их и фиксирует каждую завершенную локаль как один коммит в ветке, содержащей только сгенерированные файлы, основанной на точном проверенном SHA. Последующий запуск может проверить и повторно использовать эту ветку, поэтому прерывание приводит к потере только той локали, которая еще обрабатывается. main остается неизменным, пока рабочий процесс не выполнит требуемый аудит сгенерированных языков, полный набор тестов и строгую сборку всех локалей. Затем он проверяет, что main не продвинулся, продвигает проверенную контрольную точку одним быстрым перемоткой вперед и развертывает тот же проверенный артефакт сайта.
5. Защищенный Markdown и контракт промпта¶
Перед запросом API переводчик заменяет метаданные, блоки кода, встроенный код, цели ссылок, HTML-теги и голые URL-адреса неизменяемыми заполнителями. Ответ отклоняется, если какой-либо заполнитель отсутствует, дублирован, выдуман или перемещен за пределы восстанавливаемого контракта вывода.
Промпт также требует идентичных уровней заголовков и языков блоков кода. Реализация независимо проверяет эти свойства после восстановления защищенного содержимого. Вывод перевода должен быть объектом JSON; текст вокруг JSON, пустое содержимое, аномальные причины завершения или несовместимые схемы считаются ошибками.
Промпты для Markdown и навигационного каталога имеют версии в i18n/prompts/. i18n/glossary.json содержит стабильную терминологию продукта и команд.
6. Конфигурация модели и учетные данные¶
Модель по умолчанию настроена как deepseek-v4-flash. Реализация не ветвится по этому имени. Будущее изменение модели потребует только обновления i18n/config.toml, передачи --model или установки переменной рабочего процесса DEEPSEEK_TRANSLATION_MODEL. Используемая модель записывается на каждой сгенерированной странице и в записи манифеста.
GitHub Actions считывает учетные данные API только из секрета репозитория с именем DEEKSEEK_API_KEY. Они внедряются только на этапе генерации, когда офлайн-план сообщает об ожидающих выполнения единицах, использующих API. Они никогда не доступны ненадежному коду из запросов на включение изменений или этапам планирования, очистки и проверки без API. Значения аутентификации никогда не записываются в журналы, сгенерированные файлы, артефакты или манифест.
7. Уведомление на странице и языковые предпочтения¶
Страницы, созданные машинным способом, получают локализованное предупреждение во время рендеринга. Предупреждение идентифицирует страницу как перевод с помощью ИИ, ссылается на авторитетный источник на английском или упрощенном китайском и ссылается на предварительно заполненную проблему перевода. Оно не является частью переведенного Markdown и не создает запись в оглавлении.
При первом посещении корневой страницы сайт сравнивает navigator.languages с настроенными языковыми альтернативами. Совместимая локаль выбирается, если доступна. Ручной выбор языка сохраняется локально и имеет приоритет при последующих посещениях.
8. Команды для сопровождающих¶
Показать количество ожидающих перевода единиц без выполнения сетевых вызовов:
uv run python scripts/translate_docs.py --plan
Проверить, что каждая сгенерированная страница и каталог актуальны:
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
Обновить стабильные псевдонимы исходных заголовков без вызовов API:
uv run python scripts/translate_docs.py --refresh-heading-anchors
Принудительно выполнить полную регенерацию с явной моделью:
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash