Интернационализация простой текстовой разметки (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 файле.

Читайте так же:

  • Социальное SEO: что это такое и «с чем его едят»Социальное SEO: что это такое и «с чем его едят» Автор: Питер Джоубс (Peter Jobes). Что такое социальное SEO и как оно может помочь вашему бизнесу? Термин звучит довольно сложно. Но на деле это может оказаться удобным и простым способом помочь вашему бизнесу. По сути, этот подход означает. Что ссылки и взаимодействия в соцсетях играют […]
  • Приглашаем на digital-конференцию Admitad Expert 2021Приглашаем на digital-конференцию Admitad Expert 2021 Пресс-релиз 17 сентября в Loft Hall в Москве пройдет конференция Admitad Expert – ежегодное событие для представителей digital-рынка о современных подходах к онлайн-маркетингу. Чем удивит вас Expert в 2021 году и почему нужно приобретать билеты уже сейчас? Мир постоянно меняется, и […]
  • [Перевод] Основы внутреннего устройства JavaScript[Перевод] Основы внутреннего устройства JavaScript С ростом популярности JavaScript команды разработчиков начали использовать его поддержку на многих уровнях своего стека — во фронтенде, бэкенде, гибридных приложениях, встраиваемых устройствах и многом другом. В этой статье мы хотим более глубоко рассмотреть JavaScript и то, как он […]
  • Крупнейшие российские интернет-платформы и СМИ подпишут меморандум о фактчекингеКрупнейшие российские интернет-платформы и СМИ подпишут меморандум о фактчекинге Крупнейшие российские интернет-платформы и СМИ подписали меморандум о фактчекинге. Одно из предложений, которое будет обсуждаться с подписантами соглашения, – маркировка фейкового контента пользователей, утверждают два источника среди подписантов соглашения. Подписать документ планируют […]