---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://3y3.dev/en/tools/docs/translate.md
  - https://3y3.dev/ru/tools/docs/translate.md
  - href: ru/tools/docs/translate.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
keywords:
  - translate
  - xliff
  - cat
  - i18n
  - l10n
  - localization
  - internationalization
updatedAt: '2026-07-17T08:23:20.000Z'
---
> **Documentation Index:** Fetch the complete configuration index at https://3y3.dev/ru/llms.txt

# Локализация

Для перевода документации на разные языки используется команда `yfm translate`, которая обеспечивает быстрые [автоматические переводы](#auto).

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

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

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

#|
|| Параметр             | Path
|| `--schema {{optional}}` | 
Путь до одного или нескольких файлов, содержащих кастомные схемы для перевода.
\
`yfm translate extract --schema ./some/path/to/file.yaml ./some/path/toAnother/file.yaml`
|#

## Автоматический перевод {#auto}

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

Автоматический перевод может быть выполнен с использованием таких сервисов, как [Yandex Translate](https://cloud.yandex.ru/docs/translate/).

У этих систем есть [ограничения](https://cloud.yandex.ru/ru/docs/translate/concepts/limits) по объему переводимых документов и качеству перевода. Однако они отличаются высокой скоростью работы.

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

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

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

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

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

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

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

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

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

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

#### Основные

#|
|| Параметр             | Формат    | Описание ||
|| `--source`<b style="color:red" title="Обязательный">*</b>| [Locale](https://en.wikipedia.org/wiki/ISO_639-1) |
Код языка оригинального документа в формате ISO 639-1
\
`yfm translate --source ru-RU`
||
|| `--target`<b style="color:red" title="Обязательный">*</b>| [Locale](https://en.wikipedia.org/wiki/ISO_639-1) |
Код языка переведенного документа в формате ISO 639-1
\
`yfm translate --target en-US`
||
|| `--input`              | Path      |
Путь до **корня** переводимого проекта или конкретного файла в проекте. Если не указан, используется директория запуска команды.
\
Директорию языка в пути указывать не надо — она добавляется автоматически.
\
`yfm translate -i ./docs`
\
`yfm translate -i ./docs/index.md`
\
Также в качестве пути можно указать [файл фильтр](#filter).
\
`yfm translate -i translate.list` 
||
|| `--output`             | Path      |
Путь до **корня** проекта, в который нужно сохранить перевод. Если не указан, используется `input` директория.
||
|| `--include`            | [Glob](https://en.wikipedia.org/wiki/Glob_(programming)) |
Набор правил для фильтрации отправляемых на перевод файлов. По умолчанию `{lang}/**/*.@(md\|yaml\|json)`.
\
Может быть передан несколько раз.
\
Игнорируется, если используется [файл фильтр](#filter).
\
`yfm translate --include ru/**/*.md`
||
|| `--exclude`            | [Glob](https://en.wikipedia.org/wiki/Glob_(programming)) |
Набор правил, запрещающих отправлять файлы на перевод. Применяется после `include`.
\
Может быть передан несколько раз.
\
`yfm translate --exclude ru/_no-translate/**/*.md`
||
|#

#### Система переводов

{% list tabs %}

- Yandex Translation

  #|
  || Параметр             | Формат         | Описание ||
  ||

  `--auth`<b style="color:red" title="Обязательный">*</b> 
  
  |
  
  Path
  [IAM‑токен](https://cloud.yandex.ru/ru/docs/translate/api-ref/authentication)
  [API‑ключ](https://cloud.yandex.ru/ru/docs/iam/operations/api-key/create)

  |
  Токен авторизации. Может быть передан несколькими способами:
  \
  [IAM‑токен](https://cloud.yandex.ru/ru/docs/translate/api-ref/authentication) как параметр командной строки
  \
    `yfm translate --auth <token>`
  \
  Путь до файла, в котором хранится [IAM‑токен](https://cloud.yandex.ru/ru/docs/translate/api-ref/authentication)
  \
  `yfm translate --auth path/to/.auth`
  \
  Путь до файла, в котором хранится [API‑ключ](https://cloud.yandex.ru/ru/docs/iam/operations/api-key/create) сервисного аккаунта.
  \
  `yfm translate --auth path/to/.api-key`

  ||
  ||
  
  `--folder`<b style="color:red" title="Обязательный">*</b> 
  
  |
  
  Id
  
  |
  [Идентификатор каталога](https://cloud.yandex.ru/ru/docs/resource-manager/operations/folder/get-id), для которого у вашего аккаунта есть роль `ai.translate.user` или выше.
  ||
  ||
  
  `--timeout` 
  
  |
  
  Число
  
  |

  Время ожидания перевода в миллисекундах, значение по умолчанию — 5000 (5 секунд).

  ||
  |#
  
{% endlist %}

### Фильтрация файлов {#file-filter}

Если необходимо ограничить переводимые тексты фиксированным набором файлов, механизм гибких фильтров `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
```

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

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

### Фильтрация контента страниц {#content-filter}

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

* `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
  :::
  ```