Локализация

Статья обновлена 1 сентября 2026 г.

Команда yfm translate переводит документацию проекта с одного языка на другие. Текст извлекается из разметки, переводится выбранным способом и собирается обратно в файлы - структура проекта, разметка и код при этом сохраняются.

О том, как устроен проект с несколькими языковыми версиями, читайте в статье Многоязычные проекты.

Способы перевода

Машинный перевод

Перевод через Yandex Translate - способ по умолчанию, работает без опции --provider. Самый быстрый вариант, но результат обычно требует вычитки. Подробности - в статье Машинный перевод.

AI-перевод

Перевод большими языковыми моделями: провайдеры yandexgpt, openai, openrouter и anthropic. Поддерживает глоссарии, промпты, кэш переводов и оценку качества второй моделью. Подробности - в статье AI-перевод.

Обмен XLIFF с CAT-системами

Если перевод выполняют люди в системе автоматизированного перевода (Computer Assisted Translation, или CAT), подкоманда extract выгружает текст проекта в *.xliff файлы, а compose собирает переведенные файлы обратно в документацию. Подробности - в статье Обмен XLIFF с CAT-системами.

Как устроен перевод

Каждый документ разбивается на сегменты - предложения, заголовки, ячейки таблиц. Разметка YFM, HTML-теги, код и Liquid-конструкции на перевод не отправляются: они остаются в «скелете» документа, и после перевода сегменты подставляются обратно на свои места. Повторяющиеся сегменты переводятся один раз.

Файлы каждого языка лежат в своей языковой папке: исходные - например, в ru/, результат перевода - в папке целевого языка, например en/. Указывать языковую папку в путях не нужно - она добавляется автоматически по значениям --source и --target.

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

По умолчанию на перевод попадают файлы {lang}/**/*.@(md|yaml|json):

*.md - текст YFM-разметки;
*.yaml и *.json - только поля, описанные в схеме перевода.

Схемы перевода YAML и JSON

Схема определяет, какие поля структурированного файла содержат переводимый текст. Встроенные схемы есть для:

оглавлений toc.yaml;
разводящих страниц index.yaml;
пресетов переменных presets.yaml;
страниц Page constructor.

Собственные схемы можно подключить опцией --schema подкоманды extract.

Общие параметры

Эти параметры работают во всех способах перевода. Специфичные параметры описаны в статьях про машинный перевод, AI-перевод и обмен XLIFF.

Параметр	Описание
`--source`, `-sl`	Язык оригинала в формате ISO 639-1: `ru` или `ru-RU`. Обязательный
`--target`, `-tl`	Язык перевода: `en` или `en-US`. Можно указать несколько раз - перевод выполнится на каждый язык
`--input`, `-i`	Путь до корня проекта или до конкретного файла в проекте. По умолчанию - директория запуска команды
`--output`, `-o`	Путь до корня проекта, в который нужно сохранить перевод. По умолчанию совпадает с `input`
`--files`	Пути к файлам для перевода (относительно `input`) или путь к файлу со списком. Можно повторять. Если параметр задан, `--include` и `--exclude` игнорируются
`--include`	Правило отбора файлов: путь, glob-шаблон или файл со списком. Можно повторять. Заданные правила заменяют правило по умолчанию; чтобы вернуть его, добавьте отдельное правило `--include ...`
`--exclude`	Правило исключения файлов: путь или glob-шаблон. Применяется после `--include`. Можно повторять
`--config`, `-c`	Путь к файлу конфигурации. По умолчанию - `.yfm` в корне проекта

Параметры перевода через провайдера

Работают при переводе через Yandex Translate и AI-провайдеров, но не в подкомандах extract и compose.

Параметр	Описание
`--provider`	Система перевода: `yandex` (по умолчанию), `yandexgpt`, `openai`, `openrouter` или `anthropic`
`--include-vcs-diff`	Добавляет к переводу файлы, измененные в рабочей копии git или arc. Директория `input` должна находиться внутри репозитория. Необязательное значение - реф, относительно которого считается diff (по умолчанию `HEAD`). Диапазоны в git-синтаксисе (`a..b`, `a...b`) работают для обеих систем. Неотслеживаемые файлы включаются всегда. Комбинируется с `--include`: переводятся файлы из обоих наборов. Если изменений нет, команда успешно завершается без перевода
`--vars`, `-v`	Переменные сборки в формате JSON. Команда `translate` игнорирует `presets.yaml` - переменные передаются только этой опцией
`--dry-run`	Не выполнять перевод, а только посчитать объем текста и количество запросов к провайдеру
`--copy-assets`	Скопировать непереводимые файлы (изображения и другие ассеты) из папки исходного языка в папки целевых языков, чтобы переведенная версия собиралась самостоятельно
`--timeout`	Время ожидания одного запроса к API перевода в миллисекундах. По умолчанию - `5000`

Фиксированный список файлов

Если нужно ограничить перевод заранее известным набором файлов, вместо glob-шаблонов удобнее файл со списком - например, translate.list. Он передается в параметр --files или --include:

yfm translate --files ./translate.list --source ru --target en

# Файл поддерживает комментарии и пустые строки

# Пути формируются относительно самого файла translate.list
./some/path/to/translated/file-1.md
./some/path/to/translated/file-2.md

# Пути не должны находиться выше, чем translate.list
# Пример неправильного пути:
../some/path/to/translated/file.md

Исключение контента из перевода

Части контента можно исключить из перевода прямо в разметке.

translate=no - для блоков кода:

```sql translate=no
SELECT * FROM posts WHERE id=123 LIMIT 1
```

`` - для строковых фрагментов (работает в md- и yaml-файлах):
```
Формат даты: ISO 8601 со смещением относительно UTC.
```

:::no-translate - для блоков контента:

Весь этот блок не уйдет на перевод.