Merge pull request #24 from diplodoc-platform/vacancy

Localization
diplodoc-platform · Mar 22, 2024 · 8a4cb22 · 8a4cb22
2 parents 5a9e7c4 + d0ad002
commit 8a4cb22
Show file tree

Hide file tree

Showing 5 changed files with 158 additions and 31 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+/xliff
diff --git 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
@@ -1,4 +1,5 @@
 default:
+  PROGRAM: yfm
   algorithms: |
     - Массив - и его отличие от списков
     - Связный список - и его реализации на js

diff --git a/ru/tools/docs/presets.yaml b/ru/tools/docs/presets.yaml
@@ -0,0 +1,13 @@
+default:
+  required: '<b style="color:red" title="Обязательный">*</b>'
+  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
diff --git 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<br/>{{fmt.iam-token}}<br/>{{fmt.api-key}} |
+  Токен авторизации. Может быть передан несколькими способами:
+  \
+  {{fmt.iam-token}} как параметр командной строки
+  \
+    `{{PROGRAM}} translate --auth <token>`
+  \
+  Путь до файла, в котором хранится {{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}}
+```