Интернационализация простой текстовой разметки (i18n)

xrjzpblczowgylzxmvefrjjt4og

Go to English version

Несколько лет назад коллега опубликовал статью о создании презентации при помощи Asciidoctor. С тех пор мы пользуемся только этим подходом.

Недавно возникла проблема перевести презентации на несколько языков и обеспечить синхронизацию переводов по мере доработки оригинала. Решение оказалось настолько простым и отработанным, что я решил описать его в этой статье.

Предлагаемое решение ничего не знает о синтаксисе. Это означает, что не так важно, используется Asciidoc, другой формат простой текстовой разметки или даже смешанный формат (например, включающий мои любимые Plantuml или любые другие диаграммы). Серьезные ограничения данного подхода — (1) переводчик не должен ломать используемую разметку и (2) невозможно напрямую использовать машинный перевод.

Решение использует Translation Toolkit и стандартные инструменты GNU Gettext.

Для демонстрации подхода у данной статьи есть английская и русская версия. В её репозитории настроена простая автоматизация, которая синхронизирует перевод, создает печатную версию статьи (pdf, docx, odt), а также создает файл в формате Markdown для публикации на Хабре.

В предыдущей статье о тестировании документации я только упомянул стандартные текстовые линтеры, т.к. старался сфокусироваться в целом на подходах к тестированию, а не конкретных инструментах. Тем не менее существующие линтеры могут очень и очень многое. Поэтому эта статья проверялась при помощи vale.

Gettext предполагает, что ключевые строки для перевода являются оригинальными сообщениями.

Gettext использует файлы расширением .po (PO — Portable Object) для хранения как оригинальных, так и переведенных сообщений. Большое количество редакторов позволяет редактировать такие файлы как в однопользовательской, так и в многопользовательской среде.

Основная идея Translation Toolkit заключается в использовании блоков смежных строк в качестве констант для перевода.

Рассмотрим пример:

.Зима -- это
* снег
* мороз
* Рождество
* Новый год

В примере показано три блока смежных строк, поэтому Translation Toolkit извлечёт три константы для перевода и поместит их в файл с расширением .pot (шаблон .po).

Вставляя или убирая переносы строк в данном примере вы можете получить любое количество констант в диапазоне от 1 до 5. Количество констант зависит от удобства для переводчика.

Используя файл .pot в качестве шаблона, Gettext создает (обновляет) файлы .po для всех требуемых языков. Переводчики работают именно с этими файлами. Далее Translation Toolkit берет (1) файл .po с переводом, (2) оригинальный файл и создает переведенный файл.

Процесс перевода состоит из следующих шагов.


  • Исходные шаги для получения первого перевода на один или несколько языков.


  • Обновление перевода после модификации исходного текста.


На следующих диаграммах предполагается, что исходный файл —  i18n-adoc.adoc, а перевод должен быть помещен в файл i18n-adoc-ru.adoc.


Исходные шаги

Исходные шаги

Существует много редакторов для перевода файлов .po. На следующем снимке экрана показан интерфейс Gtranslator. Я предпочитаю https://poedit.net/ [Poedit], хотя то, как он заменяет гравис на апостроф при использовании машинного перевода, раздражает.

Перевод с использованием Gtranslator


Обновление перевода

Обновление перевода


  1. В нашей документации мы часто повторно используем константы интернационализации, чтобы имена элементов интерфейса в документации совпадали с именами этих же элементов в приложении. Мы генерируем эти константы автоматически в следующем формате:

    :main-menu-documents: Документы
    :main-menu-documents-my: Мои
    ...

    Мы включаем этот файл в документ Asciidoc (include i17n-{lang}.adoc[]). Теперь нет необходимости использовать атрибуты. Просто переведите include i17n-en.adoc[] в include i17n-ru.adoc[].


  2. Когда gettext обновляет файлы .po, он использует нечеткий поиск. Если вы немного измените исходный текст, перевод не пропадет. Он будет просто помечен как возможно неверный (flaky).


  3. Актуальность файла с переводом проверить очень легко при помощи утилиты Gettext — msgfmt.

    msgfmt --statistics i18n-adoc-ru.po

    Команда показывает количество переведенных строк, количество строк, которые нуждаются в проверке, и количество непереведенных строк.



  • Translation Toolkit и Gettext обеспечивают эффективную интернационализацию документации.


  • Простая текстовая разметка — не такая уж и простая. Использование всех возможностей простой текстовой разметки выставляет определенный уровень требований к специалисту по документации. Попробуйте представить переводчику файлы в формате .po. Многие ли из них будут готовы сделать перевод? Или попросят предоставить текст в более традиционном формате, например, в Microsoft Word.


  • Контроль качества: 58 переведенных сообщений, 0 ошибок, 0 предупреждений и 0 предложений в 1 файле.


© Habrahabr.ru