Интернационализация простой текстовой разметки (i18n)
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], хотя то, как он заменяет гравис на апостроф при использовании машинного перевода, раздражает.
Обновление перевода
В нашей документации мы часто повторно используем константы интернационализации, чтобы имена элементов интерфейса в документации совпадали с именами этих же элементов в приложении. Мы генерируем эти константы автоматически в следующем формате:
:main-menu-documents: Документы :main-menu-documents-my: Мои ...Мы включаем этот файл в документ Asciidoc (
include i17n-{lang}.adoc[]). Теперь нет необходимости использовать атрибуты. Просто переведитеinclude i17n-en.adoc[]вinclude i17n-ru.adoc[].Когда
gettextобновляет файлы.po, он использует нечеткий поиск. Если вы немного измените исходный текст, перевод не пропадет. Он будет просто помечен как возможно неверный (flaky).Актуальность файла с переводом проверить очень легко при помощи утилиты Gettext —
msgfmt.msgfmt --statistics i18n-adoc-ru.poКоманда показывает количество переведенных строк, количество строк, которые нуждаются в проверке, и количество непереведенных строк.
Translation Toolkit и Gettext обеспечивают эффективную интернационализацию документации.
Простая текстовая разметка — не такая уж и простая. Использование всех возможностей простой текстовой разметки выставляет определенный уровень требований к специалисту по документации. Попробуйте представить переводчику файлы в формате
.po. Многие ли из них будут готовы сделать перевод? Или попросят предоставить текст в более традиционном формате, например, в Microsoft Word.Контроль качества: 58 переведенных сообщений, 0 ошибок, 0 предупреждений и 0 предложений в 1 файле.
