Program po4a jest użyteczny, jeżeli jest wiele plików do przetłumaczenia, różne formaty tych plików lub istnieje potrzeba przekazywania różnych opcji dla różnych dokumentów oraz chce się uniknąć wywoływania po4a-gettextize(1), po4a-updatepo(1) i po4a-translate(1) w złożonych Makefile'ach.
Podawanie ścieżek plików wejściowych tłumaczenia
Automatyczne wykrywanie ścieżek i języków
Określanie dokumentów do przetłumaczenia
Określanie opcji modułów
Podawanie aliasów
Pozwala także mieszać dokumenty mające różne formaty w tym samym pliku POT, tak że można mieć tylko jeden taki plik w projekcie.
Inne narzędzia pakietu po4a mogą naśladować to zachowanie (na przykład w Makefile'ach), jednak jest to raczej trudne do wykonania, przerabianie zaś tych samych skomplikowanych plików Makefile dla każdego projektu używającego po4a może być męczące.
Przepływ danych może być podsumowany następująco. Jakakolwiek zmiana w głównym dokumencie będzie przeniesiona do plików PO, a wszystkie zmiany w plikach PO (albo ręczne, albo spowodowane przez poprzedni krok) będą przeniesione do przetłumaczonych dokumentów.
główny dokument --> pliki PO --> tłumaczenia
Przepływ danych w tym narzędziu nie może zostać odwrócony, więc zmiany w tłumaczeniach są zawsze nadpisane przez zawartość plików PO. Tak więc nie można go użyć do skonwertowania istniejących tłumaczeń do systemu po4a. Proszę przeczytać po4a-gettextize(1), aby dowiedzieć się, jak wykonać to zadanie.
Komentarze w plikach są oznaczane przez znak ``#''. Komentują wszystko, aż do napotkania końca linii. Linie mogą być kontynuowane przez wycytowanie końca linii znakiem ``\''. Wszystkie niepuste linie muszą zaczynać się poleceniem [], po którym następują jego argumenty. (Wygląda to na trudne, ale mam nadzieję, że jest raczej łatwe ;) ).
Jest to nieobowiązkowe polecenie, które może uprościć cały plik konfiguracyjny i uczynić go bardziej skalowalnym. Należy określić listę języków, na które dokumenty zostaną przetłumaczone. Jest to bardzo proste:
[po4a_langs] fr de
Umożliwi to rozszerzenie $lang do wszystkich języków podanych w pozostałej części pliku konfiguracyjnego.
Najpierw należy określić, gdzie znajdują się pliki wejściowe tłumacza (tj. pliki używane przez tłumaczy w czasie ich pracy). Może być to wpisane w takiej linii:
[po4a_paths] doc/l10n/project.doc.pot \
fr:doc/l10n/fr.po de:doc/l10n/de.po
Poleceniem tym jest [po4a_paths]. Pierwszym argumentem jest ścieżka używanego pliku POT. Wszystkie kolejne argumenty mają następującą samotłumaczącą się formę:
<język>:<ścieżka do pliku PO dla tego języka>
Jeśli zdefiniowano szablony języków, można zapisać powyższe linie w ten sposób:
[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
Polecenie to nie powinno być używane razem z poleceniami [po4a_langs] lub [po4a_paths].
Przed pierwszym użyciem tego polecenia, należy utworzyć pusty plik POT, tak aby po4a mógł poznać jego nazwę.
[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
Powinno być to zrozumiałe bez dodatkowych wyjaśnień. Proszę zauważyć, że w drugim wypadku doc/l10n/script.fr.add jest załącznikiem do francuskiej wersji tego dokumentu. Dalsze szczegóły na temat załączników można znaleźć w po4a(7).
Bardziej formalnie, format jest następujący:
[type: <format>] <główny_doc> (<język>:<przetłumaczony_doc>)* \
(add_<język>:<modyfikator>*<ścieżka_do_załącznika>*)
Jeżeli nie podano żadnych modyfikatorów ścieżka_do_załącznika jest ścieżką do pliku załącznika. Modyfikatory są następujące:
Jeśli zdefiniowano szablony języków, można zapisać powyższe linie w ten sposób:
[type: pod] script $lang:doc/$lang/script.1 \
add_fr:doc/l10n/script.fr.add
Jeśli wszystkie języki mają załączniki o podobnych ścieżkach, można napisać coś takiego:
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
Jeśli jest potrzeba użycia określonej opcji tylko dla jednego dokumentu, który ma być przetłumaczony, to można to także podać w pliku konfiguracyjnym. Opcje są wprowadzane słowem kluczowym opt. Jeżeli argument słowa kluczowego opt zawiera spacje (np. gdy się podaje wiele opcji lub opcję z argumentem), to musi być ujęty w cudzysłowy. Można także podać opcje, które będą stosowane tylko do określonego języka, używając słowa kluczowego opt_język.
Tu jest przykład:
[type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt:``-k 75'' opt_it:``-L UTF-8'' opt_fr:-v
Argumenty mogą zawierać spacje, jeżeli zostaną otoczone pojedynczymi cudzysłowami
lub cytowanymi (tj. poprzedzonymi znakiem \) podwójnymi cudzysłowami:
[po4a_alias:man] man opt:``-o \''mdoc=NAME,SEE ALSO\`` -k 20''
Aby podać te same opcje dla wielu dokumentów, można użyć aliasów (patrz poniżej, sekcja Podawanie aliasów).
Można określić także zbiór opcji dla wszystkich dokumentów określonych
w pliku konfiguracyjnym:
[options] opt:``...'' opt_fr:``...''
[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
Powyższe definiuje alias modułu nazwany test, oparty na module man z opcją -k 21 stosowaną do wszystkich języków i z opcją -o debug-splitargs zastosowaną do tłumaczenia na język hiszpański.
Alias modułu może być użyty jako zwykły moduł:
[type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v
Proszę zauważyć, że można podać dodatkowe opcje osobno dla każdego pliku.
W trybie rozdzielonym używane są tymczasowy duży plik POT i tymczasowy duży PO. Pozwala to na współdzielenie tłumaczeń pomiędzy wszystkimi plikami PO.
Jeżeli dwa pliki PO mają różne tłumaczenia tego samego komunikatu, po4a zaznaczy ten komunikat jako niepewny i umieści oba tłumaczenia we wszystkich plikach PO, które zawierają ten komunikat. Następnie, jeżeli tłumacz zaktualizuje tłumaczenie i usunie znacznik niepewności (``fuzzy''), to tłumaczenie tego komunikatu zostanie automatycznie zaktualizowane w każdym pliku 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
Domyślne zachowanie (jeśli nie podano --force) jest następujące:
Ponadto tłumaczenie zostanie ponownie wygenerowane, jeżeli oryginalny dokument, plik PO, jeden z załączników lub plik konfiguracyjny są od niego nowsze. Aby uniknąć prób ponownego generowania tłumaczeń, które są poniżej zdefiniowanego progu (patrz --keep), można utworzyć plik z rozszerzeniem .po4a-stamp (patrz --stamp).
Jeśli jakieś pliki są włączane (include) do oryginalnego dokumentu, należy użyć flagi --force, ponieważ czasy modyfikacji włączanych plików nie są brane pod uwagę.
Pliki PO są zawsze ponownie generowane na podstawie plików POT za pomocą msgmerge -U.
Uwaga: Ta opcja aktywuje tworzenie plików .po4a-stamp. Pliki znaczników, jeżeli tylko istnieją, to są zawsze używane. Pliki te są usuwane za pomocą --rm-translations, albo gdy plik zostanie w końcu przetłumaczony.
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.
Uwaga: $lang zostanie zastąpione nazwą bieżącego języka.
W naszym przypadku wywołalibyśmy:
cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
Następnie wygenerowany plik należałoby wysłać na odpowiednią listę dystrybucyjną dotyczącą tłumaczeń lub umieścić na stronach www do pobrania.
Następnie załóżmy, że otrzymaliśmy trzy tłumaczenia: de.po (wraz z załącznikiem de.add), sv.po oraz pt.po. Ponieważ nie chcemy zmieniać plików Makefile za każdym razem, gdy dodawane jest nowe tłumaczenie, możemy w Makefile'u użyć po4a z odpowiednim plikiem konfiguracyjnym - nazwijmy go po4a.cfg. W naszym przypadku wyglądałby on tak:
[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"
W tym przykładzie założyliśmy, że wygenerowane strony podręcznika ekranowego (wraz z wszystkimi plikami PO i załącznikami) będą przechowywane w katalogu man/translated/$lang/ (odpowiednio man/po4a/po/ i man/po4a/add_$lang/) poniżej katalogu bieżącego. Tak więc katalog man/po4a/po/ zawierałby pliki de.po, pt.po i sv.po, a katalog man/po4a/add_de/ zawierałby de.add.
Proszę zwrócić uwagę na użycie modyfikatora ?. Jest potrzebny, ponieważ załącznik występuje tylko dla tłumaczenia na język niemiecki (de.po).
Aby zbudować przetłumaczone strony podręcznika, należy (jednokrotnie!) dodać następującą linię w celu build odpowiedniego pliku Makefile:
po4a po4a.cfg
Dzięki takiej konfiguracji, nie będzie trzeba zmieniać Makefile'a, gdy przybędzie nowe tłumaczenie. Jeżeli na przykład zespół francuski przyśle pliki fr.po i fr.add, to jedyne co trzeba zrobić, to umieścić jest w katalogach man/po4a/po/ i man/po4a/add_fr/ - podczas następnego budowania programu, tłumaczenia na język francuski zbudują się automatycznie i zostaną umieszczone w man/translated/fr/.
Proszę zauważyć, że wciąż będzie potrzebny odpowiedni cel w makefile'u instalujący przetłumaczone strony podręcznika razem z ich angielską wersją.
W końcu, jeżeli wygenerowane pliki nie są przechowywane w systemie
kontroli wersji, to należy dodać odpowiednie linie w celu clean, np.:
-rm -rf man/translated
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
Robert Luberda <robert@debian.org>
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).