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

Что делает

tyndale translate-docs переводит исходную документацию с языка по умолчанию на все локали, указанные в tyndale.config.json.

Он предназначен для сайтов документации, а не для строк интерфейса приложения:

• Читает Markdown- и MDX-документацию из вашей исходной директории docs
• Записывает переведённые файлы в соответствии с соглашениями вашего docs-фреймворка
• Пропускает файлы, которые уже актуальны
• Проверяет сгенерированную документацию и автоматически повторяет попытку для невалидных результатов перед сообщением об ошибке

Используйте ту же настройку AI provider, что и для tyndale translate.

Поддерживаемые фреймворки

translate-docs в настоящее время поддерживает:

• Starlight
• Docusaurus
• VitePress
• MkDocs
• Nextra

Быстрый старт

npx tyndale translate-docs setup
npx tyndale translate-docs

translate-docs setup определяет поддерживаемый docs-фреймворк в текущем проекте и записывает блок docs в tyndale.config.json.

Затем translate-docs использует эту конфигурацию, чтобы найти исходные документы на английском и записать переведённые документы в правильное место для вашего фреймворка.

Ожидаемая конфигурация

Сохраните вашу обычную конфигурацию Tyndale, затем добавьте блок docs:

{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "docs": {
    "framework": "starlight",
    "contentDir": "src/content/docs"
  }
}

docs.framework должен быть одним из:

• starlight
• docusaurus
• vitepress
• mkdocs
• nextra

docs.contentDir указывает на директорию исходной документации на языке по умолчанию.

Примечания:

• defaultLocale не должен присутствовать в locales
• translate-docs автоматически использует расширения файлов, специфичные для фреймворка
• --content-dir переопределяет настроенную директорию docs для текущего запуска

Как работает определение в setup

npx tyndale translate-docs setup сканирует текущий проект на наличие поддерживаемых фреймворков.

Определение основано на сигналах, специфичных для фреймворка, таких как:

• установленные зависимости пакетов
• известные конфигурационные файлы фреймворка

Текущие значения по умолчанию:

• Starlight → src/content/docs
• Docusaurus → docs
• VitePress → docs
• MkDocs → docs
• Nextra → pages

Для MkDocs достаточно файла mkdocs.yml или mkdocs.yaml для определения с высокой уверенностью.

Если setup находит несколько кандидатов, он выбирает первое совпадение с высокой уверенностью. Затем он записывает выбранный фреймворк и директорию контента в tyndale.config.json.

Если пропустить setup, translate-docs всё равно может автоматически определить фреймворк в одном узком случае: когда найден ровно один фреймворк с высокой уверенностью. Иначе используется src/content/docs, если вы не передали --content-dir.

Инкрементальное поведение

translate-docs хранит файл состояния инкрементальной обработки в корне проекта:

.tyndale-docs-state.json

Для каждой локали и исходного файла Tyndale сохраняет хеш текущего исходного документа. При следующем запуске он повторно переводит документ только если:

• отсутствует целевой переведённый файл
• изменился исходный английский файл
• вы передали --force

Это означает, что при обычном запуске обрабатываются только отсутствующие или изменённые документы.

Чтобы перевести всё заново:

npx tyndale translate-docs --force

Куда записываются переведённые файлы

Tyndale записывает переведённые документы в соответствии с выбранным фреймворком.

Starlight

Исходные документы остаются в src/content/docs, а переведённые документы помещаются в папки локалей внутри этой директории:

src/content/docs/getting-started.mdx
src/content/docs/es/getting-started.mdx
src/content/docs/fr/getting-started.mdx

VitePress and MkDocs

Они используют одно и то же соглашение «папка на локаль» внутри директории docs:

docs/guide.md
docs/es/guide.md
docs/fr/guide.md

Docusaurus

Переводы для Docusaurus записываются в его структуру i18n docs:

docs/intro.mdx
i18n/es/docusaurus-plugin-content-docs/current/intro.mdx
i18n/fr/docusaurus-plugin-content-docs/current/intro.mdx

Nextra

Nextra записывает переведённые файлы рядом с исходным файлом, используя суффикс локали:

pages/docs/getting-started.mdx
pages/docs/getting-started.es.mdx
pages/docs/getting-started.fr.mdx

Пример для Starlight

Этот репозиторий использует Starlight, поэтому типичная конфигурация выглядит так:

{
  "defaultLocale": "en",
  "locales": ["de", "es", "fr", "it", "ja", "ko", "pt", "ru", "zh"],
  "docs": {
    "framework": "starlight",
    "contentDir": "src/content/docs"
  }
}

Затем выполните:

npx tyndale translate-docs

Tyndale читает английскую документацию из src/content/docs и записывает переведённые документы в папки локалей, например src/content/docs/es/ и src/content/docs/fr/.

Опции CLI

npx tyndale translate-docs --content-dir docs --concurrency 4

Текущие опции:

• --content-dir <path> — переопределяет исходную директорию docs
• --concurrency <n> — управляет количеством параллельных сессий перевода
• --force — повторно переводит всю документацию

Что проверяется

После каждого перевода Tyndale проверяет сгенерированный документ перед сохранением. В общих чертах он убеждается, что результат по-прежнему выглядит как валидный файл документации:

• frontmatter всё ещё присутствует и пригоден к использованию
• обязательные метаданные, такие как title, всё ещё существуют
• исходные строки import сохранены
• модель не обернула весь файл в code fences

Если сгенерированный файл не проходит проверку, Tyndale просит модель исправить его и автоматически повторяет попытку. Файлы, которые всё равно не проходят проверку, указываются в конце запуска.