Программа po4a очень полезна если вы хотите избежать вызова po4a-gettextize(1), po4a-updatepo(1), и po4a-translate(1) в достаточно сложных файлах сборки (Makefiles) когда слишком много файлов для перевода, много различных форматов или необходимо определить разные параметры для разных документов.
Определение путей к входным файлам переводчика
Автоопределение путей и языков
Определение документов для преревода
Определение параметров для модулей
Определение ссылок (aliases)
Она также позволяет вам объединять несколько документов различных форматов в один POT файл, так что вы можете создать один файл для каждого проекта.
Такое поведение может быть повторено другими инструментами пакета po4a (например с помощью Makefiles), но создавать одни и те же сложные Makefiles для каждого проекта, использующего po4a, сложнее и утомительнее.
Работу с данными можно описать следующим образом. Любые изменения главного документа влияет на PO файлы, и все изменения PO файлов (ручные или вызванные предыдущими шагами) будут влиять на переведенный документ.
главный документ --> PO файлы --> переводы
Поток данных нельзя обратить с помощью данного инструмента, поэтому все изменения в переводах перезаписывается содержимым PO файлов. Данный инструмент нельзя использовать для преобразования существующего перевода в систему po4a. Для прешения этих задач смотрите po4a-gettextize(1).
Комментарии в этом файле помечаются символом '#'. Помеченный таким образом текст, до конца строки, является комментарием. Строка может быть продолжена с помощью перехода на новую строку. Все не пустые строки должны начинаться с команды [], следующей за ее аргументами. (звучит сложно, но на самом деле довольно просто, я надеюсь ;)
Эта дополнительная команда может упростить весь файл настройки и сделать его более масштабируемым. Вам необходимо указать список языков на которые вы хотите перевести документы. Это довольно просто:
[po4a_langs] fr de
Это позволит вам расширить $lang на все определенные языки в оставшейся части файла настройки.
Сначала вам необходимо определить где находятся входные файлы переводчика (например, файлы, используемые переводчиками при выполнении работы). Это можно сделать с помощью следующей команды:
[po4a_paths] doc/l10n/project.doc.pot \
fr:doc/l10n/fr.po de:doc/l10n/de.po
Вызывается команда [po4a_paths]. Первым аргументов которой является путь к используемому POT файлу. Следующие аргументы носят говорящие сами за себя названия:
<lang>:<path to the PO file for this lang>
Если вы определили шаблон языков, вы можете переписать строку выше следующим образом:
[po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
You can also use $master to refer to the document filename. In this case, po4a will use a split mode: one POT and one PO (for each language) will be created for each document specified in the po4a configuration file. See the Split mode section.
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
Эта команда не должна использоваться вместе с командами [po4a_langs] или [po4a_paths].
При использовании этой команды, вы должны создать пустой POT файл при первом вызове po4a чтобы указать имя POT файла.
[po_directory] po4a/po/
[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
de:doc/de/mein_kram.sgml
[type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
add_fr:doc/l10n/script.fr.add
Это должно быть понятно само по себе. Заметим, что во втором случае doc/l10n/script.fr.add является дополнением, предназначенным для добавления к французской версии этого документа. Пожалуйста, прочитайте po4a(7) чтобы узнать подробней о дополнениях.
Более детально, формат имеет вид:
[type: <format>] <master_doc> (<lang>:<localized_doc>)* \
(add_<lang>:<modifier>*<addendum_path>)*
Если модификатор отсутствует, addendum_path является путем к дополнению. Модификаторами являются
Если вы определили шаблон языков, вы можете переписать строку выше следующим образом:
[type: pod] script $lang:doc/$lang/script.1 \
add_fr:doc/l10n/script.fr.add
Если бы все языки имели дополнения с подобными путями, можно было бы написать что-то вроде:
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
Если вам необходимы определенные настройки для одного документа, который вы хотите переводить, то их можно определить в файле настроек. Настройки определяются с помощью opt ключевого слова. Аргумент opt ключевого слова должен быть заключен в двойные кавычки, если содержит пробелы (например, если определены несколько параметров или параметр в аргументом). Вы можете также задать параметры, которые будут применяться только к определенному языку с помощью ключевого слова opt_lang.
Ниже приведен пример:
[type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt:``-k 75'' opt_it:``-L UTF-8'' opt_fr:-v
Аргументы могут содержать пробелы если вы используете одинарные или двойные кавычки:
[po4a_alias:man] man opt:``-o \''mdoc=NAME,SEE ALSO\`` -k 20''
Если вы хотите использовать одни и те же параметры для нескольких документов, можете использовать псевдоним (см. раздел Specifying aliases ниже по тексту).
Вы также можете установить параметры для всех документов, указанных в
файле настроек:
[options] opt:``...'' opt_fr:``...''
[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
Таки образом определяется псевдоним модуля с именем test, основанный на модуле man, с ключем -k 21 для всех языков и с ключем -o debug=splitargs только для перевода на Испанский.
Данный псевдоним модуля можно затем использовать как обычный модуль:
[type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v
Обратите внимание, что вы можете указать дополнительные параметры для каждого файла.
При использовании раздельного режима используются временный большой POT и временный большие PO файлы. Это позволяет распределить переводы во все PO файлы.
Если два PO файла имеют различные переводы для одной и той же строки, po4a будет помечать данные строчки как неточно переведенные и потребует подтвердить переводы во всех PO файлах, содержащих данную строку. Затем, когда переводчик обновит перевод и снимет пометку неточно переведенный с одного PO файла, перевод данной строки будет обновлен в каждом PO файле автоматически.
If there are name conflicts because several files have the same filename, the name of the master file can be specified by adding a "master:file="name option:
[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 master:file=foo-gui [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui
По умолчанию ведет (когда параметр --force не установлен) себя следующим образом:
Кроме того, перевод обновляется (regenerated) только если его главный документ, PO файл, один из его дополнений или файл настроек были недавно обновлены. Чтобы избежать попыток обновления переводов, которые не преодолели порогового значения (см. --keep), можно создать файл с расширением .po4a-stamp (см. --stamp).
Если главный документ включает файлы, вам необходимо использовать флаг --force, потому что время изменения включенных файлов не принимается во внимание.
PO файлы всегда обновляются из POT файлов с помощью msgmerge -U.
Примечание: Параметр только активирует создание файлов .po4a-stamp. Файлы отпечатков используются всегда если они существуют, и удаляются с помощью --rm-translations или когда файл полностью переведен.
Argument can be followed by a comma and either wrap or nowrap keyword. References are written by default on a single line. The wrap option wraps references on several lines, to mimic gettext tools (xgettext and msgmerge). This option will become the default in a future release, because it is more sensible. The nowrap option is available so that users who want to keep the old behavior can do so.
Примечание: $lang будет распространен на текущий язык.
So for our case we would call
cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
You would then send this file to the appropriate language lists or offer it for download somewhere on your website.
Now let's assume you received three translations before your next release: de.po (including an addendum de.add), sv.po and pt.po. Since you don't want to change your Makefile(s) whenever a new translation arrives you can use po4a with an appropriate configuration file in your Makefile. Let's call it po4a.cfg. In our example it would look like the following:
[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"
In this example we assume that your generated man pages (and all PO and addenda files) should be stored in man/translated/$lang/ (respectively in man/po4a/po/ and man/po4a/add_$lang/) below the current directory. In our example the man/po4a/po/ directory would include de.po, pt.po and sv.po, and the man/po4a/add_de/ directory would include de.add.
Note the use of the modifier ? as only the German translation (de.po) is accompanied by an addendum.
To actually build the translated man pages you would then (once!) add the following line in the build target of the appropriate Makefile:
po4a po4a.cfg
Once this is set up you don't need to touch the Makefile when a new translation arrives, i.e. if the French team sends you fr.po and fr.add then you simply drop them respectively in man/po4a/po/ and man/po4a/add_fr/ and the next time the programm is build the French translation is automatically build as well in man/translated/fr/.
Note that you still need an appropriate target to install localized manual pages with English ones.
Finally if you do not store generated files into your version control system,
you will need a line in your clean target as well:
-rm -rf man/translated
Заплатки (patch) приветствуются ;)
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
This program is free software; you may redistribute it and/or modify it under the terms of GPL (see the COPYING file).