Перевод документации#

GetDocs позволяет выполнять перевод документации, опубликованной в формате HTML, с одного языка на другой с помощью AI-сервиса. Запустить данный сервис перевода можно следующим образом:

  • использовать как инструмент на локальной машине,

  • запустить workflow translate-doc.

Инструмент перевода не требует установки. Исполняемый файл переводчика поставляется в составе дистрибутива. Обратитесь к системному администратору для получения инструмента для запуска на локальной машине в соответствии с ее операционной системой.

На вход данный сервис перевода получает ссылку или HTML-контент сайта с опубликованной документацией и набор параметров для точного определения контента, подлежащего переводу. В результате своей работы сервис генерирует Markdown, HTML и XLIFF-файлы с переведенными текстами. Созданные MD-файлы повторяют разметку исходного сайта и готовы к дальнейшей сборке с помощью workflow build-doc.

Сервис предусматривает как первоначальный перевод документации, так и его обновление в соответствии с пользовательскими правками.

Подготовка#

  1. Создайте новый или или откройте ранее созданный репозиторий, в котором необходимо разместить перевод документов. Подготовьте структуру репозитория в соответствии с разделом Первоначальная подготовка репозитория документации или убедитесь, что текущая структура соответствует описанной.

  2. Создайте файл l10n.yaml в репозитории на одном уровне с файлом doc-config.ini и заполните в нем значения переменных. Обязательные параметры выделены жирным шрифтом:

    Параметр

    Описание

    Пример

    docs

    Список документов для перевода

    -

    name

    Уникальное имя документа для перевода. В данном контексте документ - отдельная папка в репозитории, которую создаст workflow. Данная папка будет содержать сгенерированный index.md файл содержания и включенные в него файлы с переведенным контентом

    opensearch-apiref

    source_url

    URL опубликованной документации на оригинальном языке. Укажите значение, если необходимо загрузить файлы в репозиторий. Если ссылка ведет на группу страниц, а не конкретную статью, в конце ссылки добавьте символ /. Если файлы уже загружены, разместите их в папке, указанной в параметре source_location, и не указывайте текущий параметр

    https://opensearch.org/docs/2.17/api-reference/

    source_location

    Имя директории с HTML-файлами оригинальной документации. В эту директорию будут загружены HTML-файлы оригинальной документации, если указано значение source_url

    out

    target_location

    Имя директории, в которую будут загружены файлы переведенной документации

    documents/l10n

    source_language

    Теги языка оригинальной документации с указанием региона

    en-us

    target_language

    Теги языка переведенной документации с указанием региона. Допустимо указание нескольких языков. При указании языка оригинала произойдет конвертация исходных HTML-файлов в Markdown

    ru-ru

    content_selector

    CSS-селектор области отображения текста, подлежащего переводу

    div.main-content

    navlink_selector

    CSS-селектор для определения списка статей, подлежащих переводу. Селектор должен определять конкретные ссылки, но не область, содержащую их (область навигации, table of content)

    a.nav-list-link

    exclude_selector

    Список CSS-селекторов области отображения текста, контент которых не должен попадать в переведенную документацию

    a.top-link

    notrans_selector

    Список CSS-селекторов области отображения текста, который должен оставаться на языке оригинала и не должен переводиться (например, ссылки и блоки кода)

    a[href^="#"]

    context_window

    Указывает, сколько абзацев отправляется в одном запросе к GigaChat

    4

    context_window_increase

    Если ответ от GigaChat неудовлетворительный (содержит неполный перевод или есть лишние абзацы), установите значение true, чтобы дополнительно увеличить количество обрабатываемых в запросе абзацев на 1 выше и ниже текущей области. Укажите false, чтобы разбить текущую область на две

    true

    converter

    Список конвертеров для переводов

    converter.target

    Формат выходных файлов переведенной документации

    md

    converter.scripts

    Файлы со скриптами пост-обработки переведенной документации

    scripts/create_toc.py

    converter.actions

    Встроенные скрипты для пост-обработки переведенных MD-файлов

    scripts/create_toc.py

    converter.disclaimer

    Блок примечания, который добавляется на каждую сгенерированную страницу с переводом

    ":::{note}\nЭта страница переведена нейросетью GigaChat.\n:::"

    converter.reader

    Исходный формат с указанием фильтров. Подробное описание доступно в официальной документации

    html

    converter.writer

    Выходной формат с указанием фильтров. Подробное описание доступно в официальной документации

    converter.wrap

    Указывает, необходим ли автоматический перенос строк. Подробное описание доступно в официальной документации

    converter.sandbox

    Управляет доступом Pandoc в Интернет. Подробное описание доступно в официальной документации

    * true
    * false

  3. В файле .env скорректируйте при необходимости значения переменных или задайте их при запуске исполняемого файла переводчика в командной строке:

    Переменная среды

    Параметр

    Описание

    Пример

    L10N_PANDOC

    -

    Путь до инструмента Pandoc

    Не изменяйте стандартное значение параметра

    L10N_RAINBOW

    -

    Команда вызова инструмента Rainbow

    Не изменяйте стандартное значение параметра

    L10N_GIT_URL

    --git-url

    SSH-ссылка репозитория, в который будет загружен перевод документации

    L10N_GIT_BRANCH

    --git-branch

    Ветка в репозитории, в которую будет загружен перевод документации

    L10N_GIT_DIR

    --git-dir

    Локальная папка, в которую будет склонирован репозиторий

    L10N_GIT_EMAIL

    --git-email

    Адрес электронной почты, который используется для коммита перевода

    l10n@example.ru

    L10N_GIT_MESSAGE

    --git-message

    Сообщение коммита перевода

    Update translations

    L10N_GIT_SYNC

    --git-sync

    Указывает, необходимо ли делать push коммита с переводом

    * yes
    * no

    L10N_CONFIG_PATH

    --config-path
    или
    -f

    Путь до файла l10n.yaml в репозитории

    L10N_CONFIG_NAMES

    --config-names

    Список документов для перевода (значения docs.name из файла l10n.yaml)

    L10N_CONFIG_LANGS

    --config-langs

    Список языков перевода

    CONTEXT_WINDOW

    -

    Указывает, сколько абзацев отправляется в одном запросе к GigaChat

    8

    CONTEXT_WINDOW_INCREASE

    -

    * true
    * false

    GIGACHAT_URL

    -

    Адрес, по которому принимаются запросы GigaChat

    GIGACHAT_CLIENT_CREDS

    -

    Учетные данные для клиента GigaChat

    https://gigachat.devices.sberbank.ru/api/v1/chat/completions

    GIGACHAT_MODEL

    -

    Используемая модель GigaChat

    GigaChat-Max

    GIGACHAT_PROMPT

    -

    Запрос к GigaChat

    GIGACHAT_TEMPERATURE

    -

    0

    MD_CONVERTER_DISCLAIMER

    -

    Блок примечания, который добавляется на каждую сгенерированную страницу с переводом

    ":::{note}\nЭта страница переведена нейросетью GigaChat.\n:::"

    MD_CONVERTER_READER

    -

    Исходный формат с указанием фильтров. Подробное описание доступно в официальной документации

    html

    MD_CONVERTER_WRITER

    -

    Выходной формат с указанием фильтров. Подробное описание доступно в официальной документации

    MD_CONVERTER_WRAP

    -

    Указывает, необходим ли автоматический перенос строк. Подробное описание доступно в официальной документации

    MD_CONVERTER_SANDBOX

    -

    Управляет доступом Pandoc в Интернет. Подробное описание доступно в официальной документации

    * true
    * false

    MD_CONVERTER_ACTIONS

    -

    Скрипты пост-обработки MD-файлов перевода

    Изменение стандартного значения допустимо только в тестовых целях

Запуск переводчика#

Доступные команды#

Команда

Описание

config
Вывод файла конфигурации

Данная команда позволяет просмотреть полный список заданных пользователем и стандартных параметров. Перед запуском перевода выполните эту команду и убедитесь, что все необходимые параметры заданы корректно.

download
Загрузка сайта

Данная команда позволяет локально загрузить HTML-контент сайта, указанного в параметре source_url.

translate
Перевод

Включает в себя загрузку сайта, перевод текста, генерацию файлов переводов и их коммит в репозиторий, если включена опция L10N_GIT_SYNC.

generate
Генерация Markdown-файлов из XLIFF-файлов

Выполняется для повторной генерации Markdown-файлов после внесения правок в XLIFF-файлы.

На локальной машине#

Инструмент перевода запускается из командной строки/терминала. Для выполнения определенной команды используется следующий синтаксис:

l10n <command>

Внимание

Если не задана переменная L10N_CONFIG_PATH, необходимо передавать значение при выполнении команд.

В Argo Workflows#

  1. Запустите workflow, указав необходимые параметры:

    Параметр

    Описание

    Пример

    command

    * config
    * download
    * translate
    * generate

    ssh_repo_url

    SSH-ссылка на репозиторий документации

    ssh://git@my-domain:7998/docdev/a-paradigm.git

    repo_branch

    Ветка репозитория документации (если не указана, то используется ветка по умолчанию)

    * master
    * release/1.2.3

    config_path

    Путь до конфигурационного файла перевода l10n.yaml

    my-folder/l10n.yaml

  2. Когда workflow выполнится (т.е. когда корневой узел графа translate-doc станет зеленым), перейдите в репозиторий и убедитесь, что контент репозитория изменился в соответствии с выбранной командой.
    Если была выбрана команда config, для просмотра файла конфигурации нажмите на узел translate-doc и кнопку LOGS в открывшемся меню.

Структура репозитория с переводом#

my-repo-name/
├── out/                                // каталог с файлами оригинальной документации
│   └── en-us/
│       ├── translation-name1/          // файлы перевода указанного блока документации (соответствует docs.name из l10n.yaml)
│       │   ├── article1.html           // оригинальный HTML-файл с контентом статьи article1
│       │   ├── article2.html
│       │   └── ...
│       ├── translation-name2/
│       │   └── ...
│       └── ...
├── l10n/                               // каталог со всеми файлами переведенной документации
│   ├── en-us/                          // комплект файлов перевода на указанный язык
│   │   ├── translation-name1/          // файлы перевода указанного блока документации (соответствует docs.name из l10n.yaml)
│   │   │   ├── article1.html           // HTML-файл с переведенными текстами статьи article1
│   │   │   ├── article1.html.xlf       // XLF-файл с редактируемыми текстами перевода статьи article1
│   │   │   ├── article1.md             // Markdown-файл с переведенной документацией статьи article1
│   │   │   ├── article2.html
│   │   │   ├── article2.html.xlf
│   │   │   ├── article2.md
│   │   │   ├── index.md                // файл содержания. Также может содержать вводный текст
│   │   │   └── ...
│   │   ├── translation-name1.tar.bz2   // Технический файл, не удаляйте и не изменяйте его
│   │   ├── translation-name2/
│   │   │   └── ...
│   │   └── translation-name2.tar.bz2
│   ├── ru-ru/
│   │   ├── translation-name1/
│   │   ├── translation-name1.tar.bz2
│   │   ├── translation-name2/
│   │   └── translation-name2.tar.bz2
│   └── ...
├── l10n.yaml
└── doc-config.ini

Обработка результатов перевода#

Исправление текстов перевода#

При необходимости изменить переведенные тексты в сгенерированных файлах редактируйте только XLIFF-файлы (.xlf). Правки, внесенные напрямую в HTML и Markdown-файлы, будут утеряны при повторном запуске workflow перевода.

Для работы с XLIFF-файлами можно использовать специализированные CAT-инструменты (например, OmegaT или MateCat) или текстовый редактор.

Сгенерированный XLIFF-файл для перевода английской документации на русский язык имеет следующую структуру:

<?xml version="1.0" encoding="utf-8"?>
<xliff version="1.2"
    xmlns="urn:oasis:names:tc:xliff:document:1.2"
    xmlns:okp="okapi-framework:xliff-extensions">
    <file original="applications.html" source-language="en-US" target-language="ru-RU" datatype="html">
        <body>
            <trans-unit id="tu2" resname="connecting-from-an-application-id" restype="x-h1">
                <source xml:lang="en-US">Connecting from an application</source>
                <target xml:lang="ru-RU">Подключение из приложения</target>
            </trans-unit>
            <trans-unit id="tu3" restype="x-paragraph">
                <source xml:lang="en-US">Applications are supposed to work with the services in the same Kubernetes cluster:</source>
                <target xml:lang="ru-RU">Приложения должны работать со службами в одном кластере Kubernetes:</target>
            </trans-unit>
            <!-- ... -->
        </body>
    </file>
</xliff>

Подробная информация о спецификации формата описана в официальной документации.

Обратите внимание, что исправлять можно только переведенный текст, оригинальный должен оставаться неизменным.

После внесения правок запустите следующую команду для повторной генерации Markdown-файлов:

l10n generate

Исправление ошибок разметки#

Запустите workflow build-doc. При наличии ошибок и предупреждений устраните их в соответствующих XLF-файлах и повторно запустите генерацию Markdown-файлов: l10n generate.

Пример заполнения l10n.yaml#

docs:
  - name: opensearch-apiref
    source_url: https://opensearch.org/docs/2.17/api-reference/
    source_location: .out/documents
    target_location: .out/l10n
    source_language: en-us
    target_language:
      - en-us
      - ru-ru
    content_selector: div.main-content
    navlink_selector: a.nav-list-link
    exclude_selector:
      - label.copy-curl-label
      - a.top-link
      - hr
    context_window_increase: true

  - name: patroni-3.2.1
    source_url: https://patroni.readthedocs.io/en/rel_3_2/
    source_location: .out/documents
    target_location: .out/l10n
    source_language: en-us
    target_language:
      - en-us
      - ru-ru
    content_selector: div[itemprop=articleBody]
    navlink_selector: a.reference.internal
    exclude_selector:
      - a.headerlink

Пример .env#

L10N_PANDOC=@/pandoc
L10N_RAINBOW=java -Dfile.encoding=utf-8 -cp "@/lib/*" net.sf.okapi.applications.rainbow.Main

L10N_GIT_URL=
L10N_GIT_BRANCH=
L10N_GIT_DIR=
L10N_GIT_EMAIL=l10n@example.ru
L10N_GIT_MESSAGE=Update translations
L10N_GIT_SYNC=yes

L10N_CONFIG_PATH=
L10N_CONFIG_NAMES=
L10N_CONFIG_LANGS=

CONTEXT_WINDOW=8
CONTEXT_WINDOW_INCREASE=false

GIGACHAT_URL=https://gigachat.devices.sberbank.ru/api/v1/chat/completions
GIGACHAT_AUTH_URL=https://ngw.devices.sberbank.ru:9443/api/v2/oauth
GIGACHAT_CLIENT_CREDS=
GIGACHAT_MODEL=GigaChat-Max
GIGACHAT_PROMPT=Ты - профессиональный переводчик. Переведи текст с английского на русский язык, учитывая следующее: форматирование переведенного текста должно быть такое же как в оригинальном тексте, количество строк в переведенном тексте должно быть такое же как в оригинальном тексте, количество открывающих и закрывающих тегов в переведенном тексте должно быть такое же как в оригинальном тексте. Если слово или слова в оригинальном тексте обрамлены тегами, то сохрани эти теги вокруг перевода этого слова или слов. Если в оригинальном тексте есть фрагменты, которые похожи на код, то оставь эти фрагменты в переведенном тексте без изменения. Если в оригинальном тексте есть слова, которые слеплены вместе, то оставь эти слова в переведенном тексте без изменения. Убедись, что количество строк в переведенном тексте совпадает с количеством строк в оригинальном тексте.
GIGACHAT_TEMPERATURE=0

MD_CONVERTER_DISCLAIMER=":::{note}\nЭта страница переведена нейросетью GigaChat.\n:::"
MD_CONVERTER_READER=html
MD_CONVERTER_WRITER=commonmark_x-gfm_auto_identifiers
MD_CONVERTER_WRAP=none
MD_CONVERTER_ACTIONS=encrypt_elements shift_header_levels normalize_blocks normalize_inlines normalize_links remove_classes_from_tags add_disclaimer create_toc decrypt_elements