Localization

To translate documentation into different languages, the yfm translate command is used, which provides fast automatic translations.

In addition to translation via Yandex Translate, AI translation using large language models is supported (providers yandexgpt, openai, openrouter and anthropic).

The extract and compose subcommands of this command allow working with machine translation systems (Computer Assisted Translation, or CAT), exchanging *.xliff files with them.

Translation is supported for both *.md files and *.json (including *.yaml) files according to the described schemas.

Parameters for invoking the extract subcommand

Automatic translation

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

Automatic translation can be performed using services such as Yandex Translate.

This mode is enabled by default: without the --provider option the yandex value is used, so the option is omitted in the examples below.

These systems have limits on the volume of translated documents and translation quality. However, they are characterized by high processing speed.

To reduce the volume of text for translation, the document is split into shorter segments, such as sentences or headings. Repeated segments are then removed.

To further reduce the volume of translations, include and exclude filters are supported.

The --dry-run launch parameter can be used to determine the volume of text ready for translation.

If limits are exceeded, the command will terminate with the error TRANSLATE_LIMIT_EXCEED.

Usage

• Translate a project in the current directory from {{translate.source-lang}} to {{translate.target-lang}}:

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

• Do not translate hidden files in the project:

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

Call parameters

Main

Translation system

The set of additional options depends on the --provider value. Options for AI providers (yandexgpt, openai, openrouter, anthropic) are described in the AI translation article.

File filtering

If you need to limit the translated texts to a fixed set of files, the flexible include/exclude filter mechanism may not be suitable.
In this case, you can create a file with the *.list extension. For example, 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

Example of calling the command with a filter file

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

Filtering page content

To exclude parts of content from translation, the platform provides the following syntactic constructs.

• translate=no for code blocks:

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

• :no-translate for string fragments (works in yaml and md files):

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

• :::no-translate for content blocks:

  :::no–translate
  // весь этот блок не уйдёт на перевод
  Inconsistent indentation for list items at the same level:
    * One
  * Two
  * Three
  :::