Локализация

Статья создана
Обновлена 19 ноября 2025 г.

Для перевода документации на разные языки используется команда yfm translate, которая обеспечивает быстрые автоматические переводы.

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

Поддерживается перевод как *.md файлов, так и *.json (в том числе *.yaml) файлов по описанным схемам.

Параметры вызова подкоманды extract

Параметр

Path

Автоматический перевод

yfm translate --source ru-RU --target en-US

Автоматический перевод может быть выполнен с использованием таких сервисов, как Yandex Translate.

У этих систем есть ограничения по объему переводимых документов и качеству перевода. Однако они отличаются высокой скоростью работы.

Для уменьшения объема текста для перевода документ разбивается на более короткие сегменты, например, предложения или заголовки. Повторяющиеся сегменты затем удаляются.

Также для уменьшения объема переводов поддерживаются include и exclude фильтры.

Параметр запуска --dry-run может быть использован для определения объема текста, готового к переводу.

Если лимиты превышены, команда завершится с ошибкой TRANSLATE_LIMIT_EXCEED.

Использование

  • Перевести проект в текущей директории с ru на {{translate.target-lang}}:

    yfm translate --source ru --target {{translate.target-lang}}

  • Не переводить скрытые файлы в проекте:

    yfm translate --exclude ru/**/_*.* --source ru --target {{translate.target-lang}}

Параметры вызова

Основные

Параметр

Формат

Описание

--source*

Locale

Код языка оригинального документа в формате ISO 639-1

yfm translate --source ru-RU

--target*

Locale

Код языка переведенного документа в формате ISO 639-1

yfm translate --target en-US

--input

Path

Путь до корня переводимого проекта или конкретного файла в проекте. Если не указан, используется директория запуска команды.

Директорию языка в пути указывать не надо — она добавляется автоматически.

yfm translate -i ./docs

yfm translate -i ./docs/index.md

Также в качестве пути можно указать файл фильтр.

yfm translate -i translate.list

--output

Path

Путь до корня проекта, в который нужно сохранить перевод. Если не указан, используется input директория.

--include

Glob

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

Может быть передан несколько раз.

Игнорируется, если используется файл фильтр.

yfm translate --include ru/**/*.md

--exclude

Glob

Набор правил, запрещающих отправлять файлы на перевод. Применяется после include.

Может быть передан несколько раз.

yfm translate --exclude ru/_no-translate/**/*.md
Система переводов

Параметр

Формат

Описание

--auth*

Path
IAM‑токен
API‑ключ

Токен авторизации. Может быть передан несколькими способами:

IAM‑токен как параметр командной строки

yfm translate --auth <token>

Путь до файла, в котором хранится IAM‑токен

yfm translate --auth path/to/.auth

Путь до файла, в котором хранится API‑ключ сервисного аккаунта.

yfm translate --auth path/to/.api-key

--folder*

Id

Идентификатор каталога, для которого у вашего аккаунта есть роль ai.translate.user или выше.

Фильтрация файлов

Если необходимо ограничить переводимые тексты фиксированным набором файлов, механизм гибких фильтров include/exclude может не подойти.
В таком случае можно сформировать файл с расширением *.list. Например translate.list.

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

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

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

Пример вызова команды с файлом фильтром

yfm translate --input ./translate.list --source ru --target {{translate.target-lang}}

Фильтрация контента страниц

Для исключения частей контента из перевода на платформе предусмотрены следующие синтаксические конструкции.

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

    ```sql translate=no
// этот блок не уйдёт на перевод
SELECT * FROM posts WHERE id=123 LIMIT 1
```

  • :no-translate для строковых фрагментов (работает в yaml- и в md-файлах):

    Формат даты: :no—translate[ISO 8601] со смещением относительно :no—translate[UTC].

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

    :::no–translate
// весь этот блок не уйдёт на перевод
Inconsistent indentation for list items at the same level:
  * One
* Two
* Three
:::
Предыдущая
Настройки сборки
Следующая
Одностраничная сборка