Рабочий процесс перевода документации

Команда локализации Fedora 2023-06-26

В этом документе описывается, как работает рабочий процесс локализации для веб-сайта документации Fedora.

Конвейер локализации

Описание

Процесс локализации документации работает в три шага:

  • Извлечение строк из английских исходников и создание файлов POT.

  • Переводчики переводят эти файлы POT и создают файлы PO.

  • Мы используем эти файлы PO для построения переведённых исходников и, наконец, для сборки переведённого веб-сайта.

Шаги 1 и 3 обрабатываются сценариями конвейера локализации. Шаг 2 происходит в Weblate.

Основные сценарии

Сценарии конвейера локализации размещены на Pagure в репозитории translation-scripts. Этот набор сценариев запускается ежедневно в 21:00 UTC в нашем кластере Openshift.

Основной сценарий build.py извлекает все строки из файлов adoc во всех компонентах, создаёт файлы POT, затем использует переведённые файлы PO для создания переведённых файлов adoc, которые будут использоваться для сборки конечного веб-сайта документации.

Переведённые файлы adoc хранятся в репозитории translated sources.

Схема организации локализации документации Fedora
Figure 1. Конвейер сборки локализации документации Fedora

Репозитории переводов

Обоснование дизайна

Содержимое документации разделено на компоненты (пространства с собственным меню навигации). + Каждый компонент может иметь несколько версий, а также несколько модулей.

Основная функция модулей — возможность хранить разные части компонентов в разных репозиториях git. Но они также могут храниться в одном репозитории. + Один репозиторий может даже содержать несколько компонентов. А перемещение компонентов или модулей между репозиториями не влияет на результат.

Это также справедливо для переводов: перемещение компонентов не должно менять содержимое для переводчиков. + Именно поэтому нам нужно организовывать файлы PO и POT не по репозиториям, а по компонентам, модулям и версиям.

Стандартная структура репозитория Antora
📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📁 attachments (5)
      📁 examples (6)
      📁 images (7)
      📁 pages (8)
      📁 partials (9)
      📄 nav.adoc (10)
    📂 named-module (11)
      📁 pages
      📄 nav.adoc
  📁 packages (12)
1 Имя репозитория не влияет на вывод документации и перевода. По умолчанию Antora предполагает, что источник содержимого документации находится в корне репозитория, если только start_path или start_paths не определён в плейбуке Fedora Doc. <.> Файл дескриптора версии компонента с именем antora.yml требуется в каждом корне источника содержимого. <.> Обязательный каталог с именем modules. Каталог modules должен содержать как минимум либо каталог модуля ROOT, либо каталог именованного модуля. <.> Необязательный каталог модуля ROOT. Каталог модуля должен содержать как минимум один каталог семейства. <.> Необязательный каталог семейства attachments. <.> Необязательный каталог семейства examples. <.> Необязательный каталог семейства images. <.> Необязательный каталог семейства pages. <.> Необязательный каталог семейства partials. <.> Необязательный файл навигации с именем nav.adoc. <.> Необязательный каталог именованного модуля. <.> Antora не будет обрабатывать файлы в этом каталоге, поскольку он находится вне каталога modules.

Описание структуры

Переводы хранятся в выделенных репозиториях в пространстве имён fedora-docs-l10n Pagure. + Каждый репозиторий использует следующую структуру:

Стандартная структура репозитория переводов
📒 component-module (1)
  📂 pot (2)
    📁 version (3)
      📄 page.pot
  📁 po (4)
    📂 language-code (5)
      📁 version
        📄 page.po
1 Имя репозитория — <component_name>-<module_name> или просто <component_name> для модуля ROOT. <.> Каталог pot содержит исходные файлы переводов, используемые для начала новых переводов. <.> Каталог версии называется по ключу version в antora.yml компонента. Если он не определён, он будет называться master. <.> Каталог po содержит переводы, поступающие напрямую из Weblate. <.> Каталог language-code называется с использованием кодов, определённых стандартами ISO 639-1, ISO 639-2 или ISO 639-3, когда это необходимо. (например: de, pt_BR или zh_Hans).
Переименование компонентов или модулей приводит к потере переводов для этого компонента и/или модуля.
Хотя содержимое этих репозиториев автоматически генерируется конвейером локализации и Weblate, каждый репозиторий сначала должен быть создан вручную.

Создание репозитория

  1. Войдите на https://pagure.io и в верхнем меню нажмите: Create  New project.

    • Имя проекта: <component_name>-<module_name> или <component_name>, если модуль ROOT.

    • Описание: перевод <documentation_repository_url>.

    • Пространство имён проекта: fedora-docs-l10n.

    • Выберите «Create README».

  2. В новом репозитории перейдите в Settings  Project Options: + В поле Web-hooks добавьте: https://translate.fedoraproject.org/hooks/pagure/, затем нажмите Update

  3. В Settings  Users & Groups: + Нажмите add group, выберите группу fedora-docs-l10n, выберите commit во втором списке, затем нажмите Add.

  4. В Settings  Hooks  Fedmsg: + Отметьте «Active», затем нажмите Update.

Проект Weblate

Проекты, связанные с документацией, имеют префикс fedora-docs-l10n.

Создание проекта

TBD

Want to help? Learn how to contribute to Fedora Docs ›