From d569b4f42ebee7b39e81565f2323777fe66d376b Mon Sep 17 00:00:00 2001 From: 3y3 <3y3@ya.ru> Date: Thu, 22 Feb 2024 18:21:54 +0300 Subject: [PATCH 1/3] Setup translation --- .gitignore | 1 + .yfm | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 .gitignore 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..51f42a0 100644 --- a/.yfm +++ b/.yfm @@ -5,6 +5,9 @@ resources: style: - _assets/style/custom.css +translate: + folderId: b1gpieerntm5sa95psrk + docs-viewer: project-name: diplodoc langs: ['en','ru'] From 395a135e0b463df0d43a7a892a49fe81cdf726e4 Mon Sep 17 00:00:00 2001 From: 3y3 <3y3@ya.ru> Date: Mon, 26 Feb 2024 12:58:28 +0300 Subject: [PATCH 2/3] New Translation --- .yfm | 2 +- ru/presets.yaml | 1 + ru/tools/docs/presets.yaml | 13 ++++ ru/tools/docs/translate.md | 154 ++++++++++++++++++++++++++----------- 4 files changed, 126 insertions(+), 44 deletions(-) create mode 100644 ru/tools/docs/presets.yaml diff --git a/.yfm b/.yfm index 51f42a0..7c85037 100644 --- a/.yfm +++ b/.yfm @@ -6,7 +6,7 @@ resources: - _assets/style/custom.css translate: - folderId: b1gpieerntm5sa95psrk + folder: b1gpieerntm5sa95psrk docs-viewer: project-name: diplodoc 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..e2ff941 100644 --- a/ru/tools/docs/translate.md +++ b/ru/tools/docs/translate.md @@ -1,43 +1,111 @@ -# Перевод - -`yfm translate` переводит вашу документацию используя [Yandex Translator](https://cloud.yandex.ru/docs/translate/). - -## Настройка - -- получите OAUTH-токен как описано в [документации yandex.cloud](https://cloud.yandex.ru/docs/iam/concepts/authorization/oauth-token); - -- положите его в `.ya_oauth_token` файл внутри домашней директории или укажите с помощью `YANDEX_OAUTH_TOKEN` переменной окружения; - -- получите идентификатор каталога, на который у вашего аккаунта есть роль 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 } -``` - -_В результате выполнения **InstreamAdBreakPositionType** останется без изменения в тексте._ - -Теперь вы можете использовать `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) | - -## Использование - -``` -yfm translate --input input_folder --output output_folder --source-language ru --target-language en -``` - -_В результате выполнения ваша русская документация из **input_folder** будет переведена на английский и расположена в **output_folder**._ +--- +meta: + tags: ['translate', 'xliff', 'cat'] +--- +# Локализация + +Для перевода документации на разные языки используется команда `{{PROGRAM}} translate`, которая обеспечивает быстрые [автоматические переводы](#auto). + +Подкоманды `extract` и `compose` этой команды позволяют работать с системами [машинного перевода](#cat) (Computer Assisted Translation, или CAT), обмениваясь с ними `*.xliff` файлами. + +Поддерживается перевод как `*.md` файлов так и `*.json` (в том числе `*.yaml`) файлов по [описанным схемам](#json-schemas). + +## Автоматический перевод {#auto} + +Автоматический перевод может быть выполнен с использованием таких сервисов, как [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`. + +### Параметры вызова + +#### Основные + +#| +|| Параметр | Формат | Описание || +|| --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 %} From d0ad002f9004ef3193cb936b5daa37911fef5dec Mon Sep 17 00:00:00 2001 From: 3y3 <3y3@ya.ru> Date: Tue, 27 Feb 2024 18:03:19 +0300 Subject: [PATCH 3/3] wip --- ru/tools/docs/translate.md | 47 +++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/ru/tools/docs/translate.md b/ru/tools/docs/translate.md index e2ff941..e1cac5d 100644 --- a/ru/tools/docs/translate.md +++ b/ru/tools/docs/translate.md @@ -1,6 +1,6 @@ --- meta: - tags: ['translate', 'xliff', 'cat'] + tags: ['translate', 'xliff', 'cat', 'i18n', 'l10n', 'localization', 'internationalization'] --- # Локализация @@ -12,6 +12,10 @@ meta: ## Автоматический перевод {#auto} +```bash +{{PROGRAM}} translate --source {{translate.source}} --target {{translate.target}} +``` + Автоматический перевод может быть выполнен с использованием таких сервисов, как [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) по объему документов, которые могут быть переведены, а также по качеству перевода. Однако они значительно выигрывают с точки зрения скорости. @@ -24,9 +28,23 @@ meta: Если лимиты превышены, команда завершится с ошибкой `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}} + ``` + ### Параметры вызова -#### Основные +##### Основные #| || Параметр | Формат | Описание || @@ -74,7 +92,7 @@ meta: || |# -#### Система переводов +##### Система переводов {% list tabs %} @@ -109,3 +127,26 @@ meta: |# {% endlist %} + +### Файл фильтр + +Если необходимо ограничить переводимые тексты фиксированным набором файлов, механизм гибких фильтров `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 +{{PROGRAM}} translate --input ./translate.list --source {{translate.source-lang}} --target {{translate.target-lang}} +``` \ No newline at end of file