diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..0b740a2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/xliff
\ No newline at end of file
diff --git a/.yfm b/.yfm
index f020e3d..7c85037 100644
--- a/.yfm
+++ b/.yfm
@@ -5,6 +5,9 @@ resources:
style:
- _assets/style/custom.css
+translate:
+ folder: b1gpieerntm5sa95psrk
+
docs-viewer:
project-name: diplodoc
langs: ['en','ru']
diff --git a/ru/presets.yaml b/ru/presets.yaml
index 159be9b..024d5b7 100644
--- a/ru/presets.yaml
+++ b/ru/presets.yaml
@@ -1,4 +1,5 @@
default:
+ PROGRAM: yfm
algorithms: |
- Массив - и его отличие от списков
- Связный список - и его реализации на js
diff --git a/ru/tools/docs/presets.yaml b/ru/tools/docs/presets.yaml
new file mode 100644
index 0000000..00815df
--- /dev/null
+++ b/ru/tools/docs/presets.yaml
@@ -0,0 +1,13 @@
+default:
+ required: '*'
+ fmt:
+ glob: '[Glob](https://en.wikipedia.org/wiki/Glob_(programming))'
+ locale: '[Locale](https://en.wikipedia.org/wiki/ISO_639-1)'
+ iam-token: '[IAM‑токен](https://cloud.yandex.ru/ru/docs/translate/api-ref/authentication)'
+ api-key: '[API‑ключ](https://cloud.yandex.ru/ru/docs/iam/operations/api-key/create)'
+ translate:
+ google-support: false
+ glossary-support: false
+ source: ru-RU
+ source-lang: ru
+ target: en-US
\ No newline at end of file
diff --git a/ru/tools/docs/translate.md b/ru/tools/docs/translate.md
index 8d86c62..e1cac5d 100644
--- a/ru/tools/docs/translate.md
+++ b/ru/tools/docs/translate.md
@@ -1,43 +1,152 @@
-# Перевод
+---
+meta:
+ tags: ['translate', 'xliff', 'cat', 'i18n', 'l10n', 'localization', 'internationalization']
+---
+# Локализация
-`yfm translate` переводит вашу документацию используя [Yandex Translator](https://cloud.yandex.ru/docs/translate/).
+Для перевода документации на разные языки используется команда `{{PROGRAM}} translate`, которая обеспечивает быстрые [автоматические переводы](#auto).
-## Настройка
+Подкоманды `extract` и `compose` этой команды позволяют работать с системами [машинного перевода](#cat) (Computer Assisted Translation, или CAT), обмениваясь с ними `*.xliff` файлами.
-- получите OAUTH-токен как описано в [документации yandex.cloud](https://cloud.yandex.ru/docs/iam/concepts/authorization/oauth-token);
+Поддерживается перевод как `*.md` файлов так и `*.json` (в том числе `*.yaml`) файлов по [описанным схемам](#json-schemas).
-- положите его в `.ya_oauth_token` файл внутри домашней директории или укажите с помощью `YANDEX_OAUTH_TOKEN` переменной окружения;
+## Автоматический перевод {#auto}
-- получите идентификатор каталога, на который у вашего аккаунта есть роль editor или выше, как описано в [документации yandex.cloud](https://cloud.yandex.ru/docs/resource-manager/operations/folder/get-id);
-
-- в поле `yandexCloudTranslateFolderId` внутри `.yfm` файла конфигурации укажите значение идентификатора из предыдущего пункта;
-
-- добавьте поле `yandexCloudTranslateGlossaryPairs` внутри `.yfm` файла конфигурации если вам требуется использование glossary-словаря:
-
-```
-# glossary example
-
-yandexCloudTranslateGlossaryPairs:
- - { sourceText: InstreamAdBreakPositionType, translatedText: InstreamAdBreakPositionType }
+```bash
+{{PROGRAM}} translate --source {{translate.source}} --target {{translate.target}}
```
-_В результате выполнения **InstreamAdBreakPositionType** останется без изменения в тексте._
+Автоматический перевод может быть выполнен с использованием таких сервисов, как [Yandex Translate](https://cloud.yandex.ru/docs/translate/){% if translate.google-support == true %} или [Cloud Translate](https://cloud.google.com/translate/docs){% endif %}.
+
+Эти системы имеют определенные [ограничения](https://cloud.yandex.ru/ru/docs/translate/concepts/limits) по объему документов, которые могут быть переведены, а также по качеству перевода. Однако они значительно выигрывают с точки зрения скорости.
+
+С целью уменьшения объема текста, подлежащего переводу, документ разбивается на более короткие сегменты, такие как предложения или заголовки. Повторяющиеся сегменты затем удаляются.
+
+Так же для уменьшения объема переводов поддерживаются `include` и `exclude` фильтры.
+
+Параметр запуска `--dry-run` может быть использован для определения объема текста, готового к переводу.
+
+Если лимиты превышены, команда завершится с ошибкой `TRANSLATE_LIMIT_EXCEED`.
+
+### Использование
+
+* Перевести проект в текущей директории с `{{translate.source-lang}}` на `{{translate.target-lang}}`:
+
+ ```
+ {{PROGRAM}} translate --source {{translate.source-lang}} --target {{translate.target-lang}}
+ ```
+
+* Не переводить скрытые файлы в проекте:
+
+ ```
+ {{PROGRAM}} translate --exclude {{translate.source-lang}}/**/_*.* --source {{translate.source-lang}} --target {{translate.target-lang}}
+ ```
+
+### Параметры вызова
+
+##### Основные
+
+#|
+|| Параметр | Формат | Описание ||
+|| --source {{required}}| {{fmt.locale}} |
+Код языка оригинального документа в формате ISO 639-1
+\
+`{{PROGRAM}} translate --source {{translate.source}}`
+||
+|| --target {{required}}| {{fmt.locale}} |
+Код языка переведенного документа в формате ISO 639-1
+\
+`{{PROGRAM}} translate --target {{translate.target}}`
+||
+|| --input | Path |
+Путь до **корня** переводимого проекта или конкретного файла в проекте. Если не указан используется директория запуска команды.
+\
+Директорию языка в пути указывать не надо - она добавляется автоматически.
+\
+`{{PROGRAM}} translate -i ./docs`
+\
+`{{PROGRAM}} translate -i ./docs/index.md`
+\
+Так же в качестве пути можно указать [файл фильтр](#filter).
+\
+`{{PROGRAM}} translate -i translate.list`
+||
+|| --output | Path |
+Путь до **корня** проекта, в который нужно сохранить перевод. Если не указан используется `input` директория.
+||
+|| --include | {{fmt.glob}} |
+Набор правил для фильтрации отправляемых на перевод файлов. По умолчанию `{lang}/**/*.@(md\|yaml\|json)`.
+\
+Может быть передан несколько раз.
+\
+Игнорируется, если используется [файл фильтр](#filter).
+\
+`{{PROGRAM}} translate --include {{translate.source-lang}}/**/*.md`
+||
+|| --exclude | {{fmt.glob}} |
+Набор правил запрещающих отправлять файлы на перевод. Применяется после `include`.
+\
+Может быть передан несколько раз.
+\
+`{{PROGRAM}} translate --exclude {{translate.source-lang}}/_no-translate/**/*.md`
+||
+|#
+
+##### Система переводов
+
+{% list tabs %}
+
+- Yandex Translation
+
+ #|
+ || Параметр | Формат | Описание ||
+ || --auth {{required}} | Path
{{fmt.iam-token}}
{{fmt.api-key}} |
+ Токен авторизации. Может быть передан несколькими способами:
+ \
+ {{fmt.iam-token}} как параметр командной строки
+ \
+ `{{PROGRAM}} translate --auth `
+ \
+ Путь до файла, в котором хранится {{fmt.iam-token}}
+ \
+ `{{PROGRAM}} translate --auth path/to/.auth`
+ \
+ Путь до файла, в котором хранится {{fmt.api-key}} сервисного аккаунта.
+ \
+ `{{PROGRAM}} translate --auth path/to/.api-key`
+
+ ||
+ || --folder {{required}} | Id |
+ [Идентификатор каталога](https://cloud.yandex.ru/ru/docs/resource-manager/operations/folder/get-id), на который у вашего аккаунта есть роль `ai.translate.user` или выше.
+ ||
+ {% if glossary-support == true %}
+ || --glossary | Path |
+ TODO
+ ||
+ {% endif %}
+ |#
+
+{% endlist %}
+
+### Файл фильтр
+
+Если необходимо ограничить переводимые тексты фиксированным набором файлов, механизм гибких фильтров `include/exclude` может не подойти.
+В таком случае можно сформировать файл с расширением `*.list`. Например `translate.list`.
-Теперь вы можете использовать `yfm` для перевода вашей документации.
-
-## Опции
-
-| Название опции | Обязательная или нет | Значение | Описание |
-| ----------------- | -------------------- | ---------------- | ---------------------------------------------------------------------------- |
-| --input | да | путь | путь до входной документации |
-| --output | да | путь | путь до выходной документации |
-| --source-language | да | код языка | код языка в [формате ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) |
-| --target-language | да | код языка | код языка в [формате ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) |
+```
+# Файл поддерживает комментарии и пустые строки
-## Использование
+# Пути до файлов должны быть сформированы относительно самого файла 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 input_folder --output output_folder --source-language ru --target-language en
-```
-_В результате выполнения ваша русская документация из **input_folder** будет переведена на английский и расположена в **output_folder**._
+Пример вызова команды с файлом фильтром
+
+```bash
+{{PROGRAM}} translate --input ./translate.list --source {{translate.source-lang}} --target {{translate.target-lang}}
+```
\ No newline at end of file