Наглядный обзор¶

   мастер-документ -----+--------->-------->--------+
 (создание документа)   |                           |
                        V     (выполнение po4a)     >--+--> переводы
                        |                           |  |
 существующие PO-файлы ->-> обновлённые PO-файлы ->-+  |
        ^                            |                 |
        |                            V                 |
        +----------<---------<-------+                 ^
                 (ручной перевод)                      |
                                                       |
 дополнение -->----------------------------------------+

Мастер-документы создаются авторами, пишущими документацию. Любые изменения po4a автоматически отображает в PO-файлах, которые затем обновляются переводчиками. Все изменения в PO-файлах (как сделанные po4a, так и вручную) автоматически отображаются в переведённых документах. Вы можете сымитировать это поведение с помощью сценариев po4a-updatepo(1) и po4a-translate(1), вызывая их из make-файлов, но это монотонное и докучливое занятие (см. po4a(7)). Настоятельно рекомендуется, вместо этого использовать программу po4a.

Параметры, изменяющие заголовок POT-файла¶

--porefs тип

Задаёт формат сносок в комментариях PO-файла. Аргумент l<тип> может быть одним из: never — не выводить никаких сносок, noline — не выводить номера строк (точнее, все номера строк будут заменены на 1), counter — заменяет номера строк инкрементным счётчиком и full — включает полноценные сноски (по умолчанию: full).

--wrap-po no|newlines|число (по умолчанию: 76)

Задаёт, как должны переносится строки в PO-файле. С помощью этого параметра можно выбрать или чтобы в файлах были удобно расставлены переносы строк, хотя это и может привести к конфликтам в git, или чтобы файлы больше подходили для автоматической обработки, хотя это и снизит удобство чтения оных людьми.

Исторически, gettext переносил строки в PO-файлах на 77-м столбце по косметическим соображениям. Этот параметр задаёт поведение po4a. Если в нём указано число, po4a будет переносить строки в PO-файле после данного столбца и после символов перевода строки в содержимом. Если указано newlines, то po4a будет разделять msgid и msgstr на строки только в местах перевода строк в самом их содержимом. Если же указано no, то po4a вообще не будет переносить строки в PO-файле. Строки комментариев со ссылками на местоположение строки в исходном документе всегда разбиваются на строки по усмотрению инструментов gettext, которые используются внутри po4a.

Замечание: этот параметр ни как не влияет на то, как будут расставлены переносы строк внутри самих msgid и msgstr, т.е. на то, как переносы строк будут добавляться к их содержимому.

--master-language

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

--msgid-bugs-address email@address

Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT-файлы не имеют поля Report-Msgid-Bugs-To.

--copyright-holder строка

Указать владельца авторских прав в заголовке POT файла. Значение по умолчанию: «Free Software Foundation, Inc.»

--package-name строка

Указать имя пакета в заголовке POT-файла. Значение по умолчанию: «PACKAGE».

--package-version строка

Указать версию пакета в заголовке POT-файла. Значение по умолчанию: «VERSION».

Параметры, изменяющие PO-файлы¶

--msgmerge-opt параметры

Дополнительные параметры для msgmerge(1).

Примечание: $lang будет заменён на текущий язык.

--no-previous

Данный параметр удаляет параметр --previous из настроек msgmerge. Это позволяет использовать версии gettext ниже 0.16.

--previous

Данный параметр добавляет --previous к параметрам, передаваемым msgmerge. Для жтого требуется gettext версии 0.16 или выше; он активирован по умолчанию.

Поиск POT и PO-файлов¶

Самое простое решение — явно задать путь к POT и PO-файлам следующим образом:

 [po4a_paths] man/po/project.pot ru:man/po/ru.po fr:man/po/fr.po

Это задаст пути к POT-файлу, а также к русскому и французскому PO-файлам.

Тоже самое может быть записано следующим образом, дабы уменьшить риск ошибок при копировании/вставке:

 [po4a_langs] fr ru
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

Вместо $lang будет автоматически подставлен, код языка из списка, что уменьшает риск ошибок, вызванных копированием/вставкой при добавлении нового языка.

Также можно ещё сильнее сократить эту же информацию, задав путь к каталогу с переводами следующим образом:

 [po_directory] man/po/

Указанный каталог должен содержать набор PO-файлов, каждый из которых имеет имя вида XX.po, где "XX" — это код языка перевода в соответствии с ISO 639-1. В каталоге также должен быть один единственный POT-файл, с расширением ".pot". Во время первого запуска этот файл может быть пустым, но он должен существовать (po4a не может сам угадать, какое имя файла ему вставить перед расширением).

Заметьте, что вы можете выбрать только одно: или "po_directory", или "po4a_paths". Первый вариант ("po_directory") более компактен, что снижает риск ошибок из-за копирования/вставки, но заставляет вас использовать предопределённые имена файлов и структуру проекта. Второй ("po4a_paths") — более явный, вероятно, более читаемый и рекомендованный в случае, если вы впервые используете po4a для своего проекта.

Централизованные или раздельные PO-файлы?

По умолчанию po4a создаёт один большой PO-файл для каждого языка, содержащий весь ваш перевод. С разрастанием вашего проекта размер этих файлов может стать проблемой. При использовании Weblate возможно задать приоритеты каждому сегменту перевода (т.е. msgid), чтобы важные строки переводились первыми, хотя некоторые команды всё же предпочитают разделять перевод на несколько файлов.

Чтобы использовать отдельный PO-файл для каждого мастер-файла, просто добавьте $master в имя своего PO-файла в директиве "[po4a_paths]":

 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

Если возникают конфликты из-за того, что у нескольких файлов одинаковые имена, то имя мастер-файла может быть задано добавлением параметра "master:file="имя:

 [po4a_langs] de fr ru
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

В раздельном режиме po4a создаёт временный сборник всех переводов во время обновления PO-файлов, чтобы объединить перевод одинаковых строк из различных PO-файлов. Если два PO-файла имеют различные переводы для одной и той же строки, po4a пометит данные переводы как неточные и добавит оба варианта в каждый PO-файл, содержащий эту строку. Затем, когда переводчик снимет пометку «неточно» хотя бы в одном PO-файле, перевод данной строки будет обновлён во всех PO-файлах автоматически.

Задание документов для перевода¶

Вы также должны перечислить список документов, которые следует переводить. Для каждого мастер-файла нужно указать, какой использовать парсер формата, местоположение, куда записывать переведённые документы, а также, по необходимости, некоторые дополнительные параметры, например:

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              ru:doc/ru/mein_kram.sgml
 [type: man] script fr:doc/fr/script.1 ru:doc/ru/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             ru:doc/ru/script.xml

Но, опять же, такие тяжеловесные конструкции сложно читать и изменять, например, когда нужно добавить новый язык. Намного проще будет реорганизовать всё это с помощью шаблонов с $lang:

 [type: sgml]    doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
 [type: man]     script.1          $lang:po/$lang/script.1
 [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

Задание параметров¶

Есть два вида параметров: параметры po4a, которые задают значения по умолчанию для параметров командной строки самого po4a, и параметры форматов, которые изменяют поведение парсера конкретного формата. Параметром po4a будет являться, например, если вы зададите в своём файле настроек, что значение по умолчанию параметра командной строки --keep будет 50% вместо 80%. Параметры форматов описаны на справочной странице каждого отдельного модуля парсера конкретного формата, например Locale::Po4a::Xml(3pm). Вы, например, можете передать nostrip парсеру XML, чтобы он не убирал пробелы у извлекаемых им строк.

Вы можете передать эти параметры для конкретного мастер-файла или даже для перевода файла на конкретный язык, используя "opt:" и "opt_XX:" для языка "XX". В примере ниже, параметр nostrip передаётся парсеру XML (для всех языков), а порог завершения перевода будет уменьшен до 0% только для французского (чтобы он никогда не отбрасывался).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

В любом случае, такие настройки должны находится в конце строки. Имена файлов должны идти вначале, затем дополнение, если есть (см. ниже), и только затем параметры. Группировка разных частей строки параметров не очень важна, ибо внутри себя po4a просто соединяет их все в одну строку. Следующие варианты абсолютно эквивалентны:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Заметьте, что параметры, специфичные для отдельных языков не используются во время создания POT-файла. Например, невозможно передать nostrip парсеру только для французского перевода, так как тот же самый POT-файл используется для обновления всех языков. Так что специфичными для языка могут быть только те параметры, которые используются во время создания перевода, как параметр "--keep".

Настройка псевдонимов (aliases)

Наилучшим способом передать одинаковые параметры различным файлам будет определить псевдоним (alias) типа, как это показано ниже. В примере "--keep 0" передаётся всех документов на итальянский с помощью типа "test", который является расширением типа "man":

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Вы также можете расширить существующий тип, использовав то же самое имя для псевдонима. Это не будет считаться ошибкой рекурсивного определения:

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Глобальные параметры по умолчанию

Вы также можете использовать строки с директивой "[options]", чтобы определить параметры, которые должны использоваться для всех файлов, независимо от их типа.

  [options] --keep 20 --option nostrip

Как и параметры командной строки, параметры передаваемые в файле настроек можно сокращать:

  [options] -k 20 -o nostrip

Приоритет параметров

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

• Директивы "[options]" задают значения по умолчанию, которые могут быть переопределены любым другим источником.
• Затем идут псевдонимы типов.При этом настройки, специфичные для конкретных языков переопределяют те что применяются ко всем языкам.
• Настройки, специфичные для конкретного мастер-файла переопределяют и настройки по умолчанию и те что заданы в псевдонимах типов. В данном случае настройки, специфичные для языков, также переопределяют общие.
• Наконец, параметры, переданные в командной строке переопределяют любые параметры из файла настройки.

Пример

Пример, показывающий, как следует экранировать пробелы и кавычки:

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

Дополнение (addendum): добавление дополнительного содержимого в перевод¶

Если вы хотите добавить дополнительный раздел в перевод, например отдать дань уважения переводчику, тогда вам нужно указать дополнение, при определении мастер-документа. Подробности о синтаксисе файлов-дополнений можно получить на справочной странице po4a(7).

 [type: pod] script fr:doc/fr/script.1 \
             add_fr:doc/l10n/script.fr.add

Вы также можете использовать шаблоны языков:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_$lang:doc/l10n/script.$lang.add

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

Модификаторы объявления дополнений

Модификаторы дополнений могут делать файл настройки проще, когда не все языки имеют дополнение или когда список дополнений меняется от языка к языку. Модификатор — это один символ, стоящий перед именем файла.

?

Использовать файл путь_к_дополнению, если этот файл существует, в противном случае — ничего не делать.

@

путь_к_дополнению является не обычным дополнением, а файлом содержащим список дополнений, по одному в каждой строке. Каждое такое дополнение также могут предварять свои модификаторы.

!

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

Например, чтобы включить дополнение для любого языка, для которого оно существует можно сделать следующее (если дополнение не существует, то сообщение об ошибке не будет выдано):

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:?doc/l10n/script.$lang.add

Следующий пример задаёт список дополнений для каждого языка:

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:@doc/l10n/script.$lang.add

Фильтрация переведённых строк¶

Иногда, вам хочется скрыть некоторые строки от переводчиков. Для этого вы можете задать параметр "pot_in" в определении мастер-файла, дабы указать имя файла, из которого следует извлекать строки для создания POT-файла для перевода вместо настоящего мастер-файла. Например:

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

С такими настройками строки для перевода будут извлекаться из book-filtered.xml (который должен быть создан до вызова po4a), а переведённые документы будут собираться на основе book.xml. В результате, все строки, которые есть только в book.xml, но не в book-filtered.xml не будут включены в PO-файлы, что предотвратит возможность того, что переводчики переведут что-то, что не должно быть переведено. Таким образом, эти строки останутся без изменений во время создания переведённых документов. Это, конечно, снижает фактический уровень готовности перевода, так что вам придётся снизить значение параметра "--keep", дабы документ всё равно создавался.

ПРИМЕР ФАЙЛА НАСТРОЕК¶

TODO: Этот раздел действительно полезен?

Предположим, что вы сопровождаете программу foo, у которой есть man-страница man/foo.1, которая изначально поддерживается только на английском. Теперь вы как upstream или downstream сопровождающий хотите создать и поддерживать перевод. Сначала вам надо создать POT-файл, который вы позже отправите переводчикам, с помощью po4a-gettextize(1).

Так что в нашем случае мы бы выполнили

 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

Затем вы, вероятно, отправите этот файл в соответствующие группы перевода или предложите его для скачивания на своём web-сайте.

Теперь, предположим, вы получили три перевода перед выпуском новой версии вашего пакета: de.po (включая файл дополнений de.add), sv.po и pt.po. Поскольку вы не хотите менять свой Makefile всякий раз, когда вым присылают новый перевод, вы можете воспользоваться po4a с соответствующим файлом конфигурации. Давайте назовём его po4a.cfg. В нашем примере он будет иметь следующий вид:

 [po_directory] man/po4a/po/
 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
            add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"

В этом примере мы предположим, что ваши генерируемые переведённые man-страницы (а также все PO-файлы и файлы дополнений) должны хранится в man/translated/$lang/ (и соответственно в man/po4a/po/ и man/po4a/add_$lang/). В нашем примере каталог man/po4a/po/ будет содержать: de.po, pt.po и sv.po, а каталог man/po4a/add_de/ будет содержать de.add.

Отметим, использование модификатора ? т.к. только с немецким переводом (de.po)вам прислали файл дополнений.

Чтобы фактически собрать переводы man-страниц, вам осталось бы (только один раз!) добавить следующую строку к цели build соответствующего Makefile-а:

        po4a po4a.cfg

Как только это сделано, вам более не нужно менять Makefile, когда готовы новые переводы, то есть если французская команда присылает вам fr.po и fr.add, то вы просто кладёте их соответственно в man/po4a/po/ и man/po4a/add_fr/ и во время следующей сборки французский перевод автоматически создаётся в man/translated/fr/.

Заметьте, что вам по-прежнему нужна подходящая цель, чтобы устанавливать локализованные man-страницы вместе с Английскими.

В заключении, если вы не храните сгенерированные файлы в вашей системе контроля версий, вам также понадобится строка в вашей цели clean:
-rm -rf man/translated