PO4A.1P(1)

НАЗВАНИЕ
po4a - обновление PO-файлов и переведённой документации за один проход

КРАТКОЕ СОДЕРЖАНИЕ
po4a [параметры] файл_настроек

ОПИСАНИЕ
po4a (PO for anything, PO для всего) упрощает поддержку переводов документации, используя обычные инструменты gettext. Основная идея po4a состоит в том, что оно отделяет перевод содержимого от структуры документа. Пошаговое вводное руководство по работе с данным проектом можно посмотреть на странице po4a(7).

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

Вначале PO-файлы содержат только не переведённые строки исходного документа. Этот формат файла позволяет переводить каждый абзац, извлечённый po4a по-отдельности. Если, уже после того как перевод был сделан, исходный документ изменяется, то po4a отмечает этот перевод в PO-файле как «неточный» ("fuzzy"), чтобы сообщить переводчику, что данный перевод необходимо пересмотреть. Также переводчик может добавить так называемый «аддендум» ("addendum") — дополнительная информация, например, об авторе перевода и о том, как и куда сообщать об ошибках в переводе.

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

Работа po4a асинхронная и подходит для open-source проектов. Технические писатели создают master-документ в одном месте. Переводчики просматривают и обновляют перевод PO-файлов. Мейнтейнеры при необходимости запускают po4a, для отражения именений из исходной документации в PO-файлах и для получения обновленных переводов документации путем вставки обновленных переводов в обновленную структуру документации.

По умолчанию переведённые документы создаются, когда переведено хотя бы 80% содержимого. Непереведённый текст на исходном языке сохраняется. Таким образом, если перевод не завершён, в созданной документации языки комбинируются. Вы можете изменить пороговое значение 80% при помощи описанного ниже параметра --keep. Следует учесть, что если отбрасывать перевод целиком до его завершения на 100%, это может демотивировать переводчиков, так как пользователи практически никогда не будут видеть их работу. С другой стороны, вы можете вызвать у конечных пользователей затруднения, предоставляя им «переводы», которые слишком далеки от завершения.

Хранение файлов переведенной документации в системе контроля версий, возможно, не лучшая идея, так как она автоматически генерируется. Наиболее ценными являются PO-файлы, которые содержат кропотливую работу выших соратников-переводчиков. Так, некоторые люди считают более простым взаимодействие с переводчиками посредством онлайнплатформ, таких как weblate, но это естественно необязательно.

  Быстрый старт
Предположим, что вы занимаетесь поддержкой программы foo, у который есть man-страница man/foo.1 на Английском (общий язык в большинстве СПО-проектах, хотя, вообще говоря, po4a можно использовать и для переводов с любого языка или на любой другой). Некоторое время назад кто-то сделал перевод на немецкий с именем man/foo.de.1, но затем перестал выходить на связь. Затем вы получаете сообщение об ошибке, в котором говорится, что ваша документация содержит недостоверную информацию. Это срочно нужно поправить, причём в документации на всех языках. Но проблема в том, что вы не знаете немецкого, так что вы можете исправить эту ошибку только в исходном документе, но не в переводе. Теперь другой участник хочет добавить японский перевод; язык, которым вы также овладели пока не в полной мере.

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

Чтобы преобразовать проект для использования po4a необходимо выполнить два шага: собственно настройте инфраструктуру po4a и конвертировать уже существующий немецкий перевод, чтобы не потерять уже проделанную работу. Последнее делается с помощью po4a-gettextize. Как описано в документации po4a-gettextize(1), этот процесс редко является полностью автоматическим, но как только это будет сделано, полученный файл de.po с немецким переводом, может быть с лёгкостью интегрирован в обычный рабочий процесс, основанный на po4a.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

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

 [po_directory] man/po4a/

 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

В нём указано, что все PO-файлы (содержащие работу переводчиков) находятся в каталоге man/po4a/, а также то, что у вас только один мастер-файл, man/foo.1. Если бы у вас их было несколько, то вам надо было бы добавить несколько строчек аналогичных второй. Каждая подобная строка также содержит, куда записывать переведённые файлы. В данном случае немецкий перевод man/foo.1 находится в man/translated/foo.de.1.

Последние, что нам понадобится для нашего po4a-проекта — это POT-файл, который является шаблоном для создания новых переводов на другие языки. Просто создайте пустой файл с расширением .pot в каталоге, указанном в po_directory, (например, man/po4a/foo.pot); po4a сам заполнит его содержимым.

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

  ├── man/
  │   ├── foo.1        <- исходная man-страница, на английском языке
  │   ├── po4a/
  │   │   ├── de.po    <- Немецкий перевод в PO-формате, полученный геттекстизацией
  │   │   └── foo.pot  <- POT-шаблон для будущих переводов (изначально пустой)
  │   └── translated/  <- Каталог, в котором будут создаваться переводы
  └── po4a.cfg         <- файл настроек

После того, как всё это будет готово, запустите po4a: он проведёт разбор вашего файла документации, обновит POT-шаблон, использует его для обновления PO-файлов с переводами, а затем использует их для обновления файлов с собственно переведённой документацией. Всё это за одну команду:

        po4a --verbose po4a.cfg

Это всё. po4a теперь полностью настроен. Как только вы исправите ошибку в man/foo.1, проблемный абзац в немецком переводе будет заменён исправленным текстом на английском. Смешение языков, конечно, не самое лучшее решение, но это единственный способ убрать ошибки из переводов на языки, которые вы даже не понимаете, а также это гарантирует, что информация, которую будет видеть конечный пользователь останется достоверной. Обновлять немецкий перевод через PO-файл также будут намного проще, так что языковая путаница, вероятно, продлиться недолго. Наконец, когда японская переводчица захочет добавить новый перевод, она должна будет скопировать foo.pot в ja.po и сделать перевод в нём. Когда она передаст вам этот файл, просто поместите его в man/po4a/po/. Затем, когда вы снова запустите po4a, переведённая страница будет создана в man/translated/foo.ja.1 (при условии, что достаточная часть объёма файла действительно переведена).

ПАРАМЕТРЫ

-k, --keep
    Минимальное пороговое значение, в процентах, для сохранения (например, для записи) результирующего файла (по умолчанию: 80). То есть, по умолчанию, для того чтобы файл был записан, необходимо перевести как минимум 80%.

-w, --width
    Количество символов в строке, после которых текст в результирующем файле переносится на новую строку, если формат это поддерживает (значение по умолчанию: 76). Если значение равно нулю или меньше нуля, строки переноситься не будут (полезно в случаях, когда разбиение на строки нарушает разметку).

-h, --help
    Отобразить короткую справку.

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

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

-A, --addendum-charset
    Кодировка аддендумов. Обратите внимание, что все аддендумы должны иметь одну и ту же кодировку.

-V, --version
    Отобразить версию и завершить работу сценария.

-v, --verbose
    Увеличить количество выводимой пояснительной информации.

-q, --quiet
    Уменьшить количество выводимой пояснительной информации.

-d, --debug
    Вывод отладочной информации.

-o, --option
    Дополнительные параметры, передаваемые модулю формата. См. описание возможных параметров и их значений в документации каждого конкретного модуля. Например, вы можете указать '-o tablecells' парсеру AsciiDoc, в то время как парсер text принимал бы '-o tabs=split'.

-f, --force
    Всегда создавать POT и PO-файлы, даже если po4a считает, что это не требуется.

    Поведение по умолчанию (когда параметр --force не установлен) следующее:

        Если POT-файл уже существует, он создаётся повторно, если мастер-документ или файл настроек был недавно изменён (и если не задан параметр --no-update). POT-файл также записывается во временный документ и po4a проверяет, что изменения действительно необходимы.

        Кроме того, перевод обновляется (regenerated) только если его мастер-документ, PO-файл, один из его аддендумов или файл настроек были обновлены после перевода. Дабы избежать повторяющихся бесплодных попыток обновления переводов, которые ещё не преодолели порогового значения (см. --keep), можно создать файл с расширением .po4a-stamp (см. --stamp).

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

    PO-файлы всегда обновляются из POT-файлов с помощью msgmerge -U.

--stamp
    Указывает po4a создать файлы-заглушки, если перевод не создаётся, поскольку он не преодолел порогового значения. Эти файлы будут называться также как и переведённый документ, с расширением .po4a-stamp.

    Примечание: Параметр активирует только создание .po4a-stamp файлов. Файлы-заглушки используются всегда если они существуют, и удаляются при выполнении --rm-translations или когда файл полностью переведён.

--no-translations
    Не регенерировать переведённые документы, только обновлять POT и PO-файлы.

--no-update
    Не менять POT и PO-файлы, только обновить переводы.

--keep-translations
    Не удалять файлы перевода даже если перевод не соответствует пороговому значению, заданному --keep. Этот параметр указывает po4a не создавать новые переведённые файлы с недостаточным количеством переведённого материала, а сохранять старые переводы, которые находятся в упадке из-за изменений в мастер-документах.

    ПРЕДУПРЕЖДЕНИЕ: этот флаг изменяет поведение po4a достаточно радикальным образом: ваши переведённые файлы не будут обновляться вообще, пока перевод не улучшится. Используйте этот ключ только если вам больше по нраву поставлять устаревшую, но переведённою документацию, нежели только точную, но непереведённую.

--rm-translations
    Удалить переведённые файлы (подразумевает --no-translations).

--no-backups
    Этот флаг ничего не делает начиная с 0.41 и может быть удалён в последующих версиях.

--rm-backups
    Этот флаг ничего не делает начиная с 0.41 и может быть удалён в последующих версиях.

--translate-only переводимый-файл
    Перевести только указанный файл. Это может быть полезно, чтобы ускорить обработку, когда файл настроек содержит значительное количество файлов. Заметим, что этот параметр не обновляет PO и POT-файлы. Этот параметр может быть указан несколько раз.

--variable переменная=значение
    Определяет переменную которая будет использоваться в файле настроек po4a. Каждое появление $(переменная) будет замещено на значение. Данный параметр можно использовать несколько раз.

--target-lang ЯЗЫК
    Обновлять PO-файлы и создавать переведённые документы только для указанного языка. Этот параметр может быть указан несколько раз.

--srcdir ИСХОДНЫЙ_КАТАЛОГ
    Задаёт базовый каталог для всех входных документов, указанных в файле настроек po4a.

    Если заданы оба параметра destdir и srcdir, то po4a будет искать входные файлы в следующих каталогах (в порядке перечисления): в destdir, в текущем каталоге и в srcdir. Выходные файлы будут записываться в destdir, если этот параметр задан, иначе — в текущий каталог.

--destdir КАТАЛОГ_НАЗНАЧЕНИЯ
    Задаёт базовый каталог для всех выходных документов, указанных в файле настроек po4a (см. описание --srcdir выше).

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

--porefs тип
    Задаёт формат сносок в комментариях PO-файла. Аргумент тип может быть одним из: never — не выводить никаких сносок, file — не выводить номера строк (точнее, все номера строк будут заменены на 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 или выше; данный параметр активирован по умолчанию.

ФАЙЛ НАСТРОЕК
po4a ожидает, что в качестве аргумента ему будет передан файл настроек. Этот файл должен содержать следующие данные:

•   Путь к PO-файлам и список языков, доступных в проекте;

•   Опционально, некоторые глобальные параметры и, так называемые, псевдонимы настроек (configuration aliases), которые можно использовать в качестве шаблонов для настройки отдельных мастер-файлов;

•   Список всех мастер-файлов, которые нужно переводить, и специфические параметры для оных.

Каждая строка файла должна содержать директиву, заключённую в квадратные скобки, и её параметры. Комментарии начинаются с символа «#» и продолжаются до конца строки. Конец строки может быть экранирован (с помощью обратного слеша "\"), в таком случае комментарий может быть растянут на несколько строк.

Несколько полноценных примеров представлены на этой страницы; дополнительные примеры можно найти в каталоге "t/cfg" дистрибутива с исходными кодами.

  Поиск 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

С такими настройками po4a будет создавать отдельные POT и PO-файлы, для каждого переводимого документа. Например, если в вашем проекте 3 документа и 5 языков, то будут созданы 3 POT-файла и 15 PO-файлов. Имена этих файлов будут получены на основе шаблона, заданном в "po4a_paths", с заменой $master на базовое имя переводимого файла. При возникновении конфликта имён, вы также можете задать имена POT-файлов с помощью параметра "pot=", как показано ниже.

Это также может быть использовано для того, чтобы сгруппировать несколько переводимых файлов в один POT-файл. Следующий пример создаёт только 2 POT-файла: l10n/po/foo.pot (со стоками из foo/gui.xml) и l10n/po/bar.pot (со стоками и из bar/gui.xml, и из bar/cli.xml).

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

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

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

 [type: sgml] "doc/my stuff.sgml"  "fr:doc/fr/mon truc.sgml"  de:doc/de/mein\ kram.sgml
 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/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", дабы документ всё равно создавался.

СМОТРИТЕ ТАКЖЕ
po4a-gettextize(1), po4a(7).

АВТОРЫ
 Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
 Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>
 Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
Copyright 2002-2023 by SPI, inc.

Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 58:
    Unterminated B<...> sequence