Локализация

Статья создана
Обновлена 12 августа 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
:::
Предыдущая
Настройки сборки
Следующая
Одностраничная сборка