Provided by: po4a_0.52-1_all 
NAZWA
po4a - aktualizowanie w jednym przebiegu zarówno plików PO, jak i przetłumaczonych dokumentów
SKŁADNIA
po4a [opcje] plik_konfiguracyjny
OPIS
Celem projektu po4a ("PO for anything") jest ułatwienie tłumaczeń (oraz, co ciekawsze, zarządzania
tłumaczeniami) przy użyciu narzędzi gettext w tych obszarach, gdzie nie były używane, jak na przykład w
obszarze dokumentacji.
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.
Spis treści
Dokument jest zorganizowany następująco:
OPIS
WPROWADZENIE
SKŁADNIA PLIKU KONFIGURACYJNEGO
Określanie języków szablonów
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
Tryb rozdzielony
OPCJE
PRZYKŁAD
MANKAMENTY
ZOBACZ TAKŻE
AUTORZY
PRAWA AUTORSKIE I LICENCJA
WPROWADZENIE
Program po4a odpowiada za aktualizowanie zarówno plików PO (żeby zsynchronizować z oryginalnymi
dokumentami), jak i tłumaczonych dokumentów (żeby zsynchronizować je z plikami PO). Głównym celem jest
uproszczenie użycia po4a, tak żeby nie trzeba było pamiętać opcji linii poleceń.
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.
SKŁADNIA PLIKU KONFIGURACYJNEGO
Argument (obowiązkowy) jest ścieżką do pliku konfiguracyjnego, który zostanie użyty. Jego składnia jest
prosta i zbliżona do składni plików konfiguracyjnych używanych przez projekty intl-tools.
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 ;) ).
Określanie języków szablonów
Uwaga: Zaleca się używanie [po_directory] zamiast [po4a_langs] i [po4a_paths]. Proszę przeczytać akapit
Automatyczne wykrywanie ścieżek i języków poniżej.
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.
Podawanie ścieżek plików wejściowych tłumaczenia
Uwaga: Zaleca się używanie [po_directory] zamiast [po4a_langs] i [po4a_paths]. Proszę przeczytać akapit
Automatyczne wykrywanie ścieżek i języków poniżej.
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
Automatyczne wykrywanie ścieżek i języków
Można użyć jeszcze innego polecenia dookreślenia nazwy katalogu zawierającego pliki PO i POT. Kiedy jest
używane, to po4a wykryje plik POT jako jedyny plik *.pot w podanym katalogu. po4a użyje także listy
plików *.po do określenia listy języków (przez usunięcie rozszerzenia pliku). Języki te będą użyte w
podstawieniach zmiennej $lang w dalszej części pliku konfiguracyjnego.
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/
Określanie dokumentów do przetłumaczenia
Oczywiście należy podać, które dokumenty są tłumaczone, jaki jest ich format i gdzie umieścić
tłumaczenia. Może to być zrobione za pomocą takich linii:
[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:
? Włącza plik ścieżka_do_załącznika, jeśli taki plik istnieje. W przeciwnym wypadku nic nie robi.
@ ścieżka_do_załącznika nie jest zwykłym załącznikiem, ale plikiem zawierającym listę załączników, po
jednym w każdej linii. Każdy załącznik może być poprzedzony modyfikatorem.
! Plik ścieżka_do_załącznika jest całkowicie ignorowany - nie jest ładowany i nie będzie, nawet jeśli
pojawia się w późniejszych specyfikacjach załączników.
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
Określanie opcji modułów
po4a akceptuje opcje, które będą przekazane do modułu. Te opcje są specyficzne dla modułu i mogą być
określone w przełączniku -o.
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:"..."
Podawanie aliasów
Jeśli zachodzi potrzeba podania tej samej opcji w wielu plikach, można rozważyć zdefiniowania aliasu
modułu. Można to zrobić tak:
[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.
Tryb rozdzielony
Tryb rozdzielony jest używany, jeżeli w linii [po4a_paths] używana jest zmienna $master.
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
OPCJE
-k, --keep
Minimalny procentowy próg tłumaczeń pozwalający zachować (tj. zapisać) plik wynikowy (domyślnie: 80).
Czyli, domyślnie, aby pliki zostały zapisane, muszą być przetłumaczone co najmniej w 80%.
-h, --help
Pokazuje krótki komunikat pomocy.
-M, --master-charset
Kodowanie znaków plików zawierających dokumenty do przetłumaczenia. Proszę zauważyć, że wszystkie
pliki muszą mieć to samo kodowanie znaków.
-L, --localized-charset
Kodowanie znaków plików zawierających dokumenty do przetłumaczenia. Proszę zauważyć, że wszystkie
pliki muszą mieć to samo kodowanie znaków.
-A, --addendum-charset
Kodowanie znaków załącznika. Proszę zauważyć, że wszystkie załączniki powinny mieć to samo kodowanie
znaków.
-V, --version
Wyświetla wersję skryptu i kończy działanie.
-v, --verbose
Zwiększa gadatliwość programu.
-q, --quiet
Zmniejsza gadatliwość programu.
-d, --debug
Wypisuje informacje przydatne do debugowania.
-o, --option
Dodatkowe opcje przekazywane modułowi formatu. Każda opcja powinna być w formacie "nazwa=wartość".
Więcej informacji o dostępnych opcjach i ich znaczeniu można znaleźć w dokumentacji każdego modułu.
-f, --force
Zawsze generuje pliki POT i PO, nawet jeżeli po4a uważa to za niepotrzebne.
Domyślne zachowanie (jeśli nie podano --force) jest następujące:
Jeżeli plik POT już istnieje i jest starszy niż plik z oryginalnym dokumentem lub plik
konfiguracyjny, to jest ponownie generowany. Plik POT jest zapisywany do pliku tymczasowego, a
po4a sprawdza, czy rzeczywiście jest potrzeba jego zmieniania.
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.
--stamp
Nakazuje programowi po4a tworzenie plików ze znacznikiem czasowym, jeżeli tłumaczenie nie zostanie
wygenerowane z powodu nieprzekroczenia zdefiniowanego progu. Pliki znaczników mają nazwę taką jak
oczekiwany przetłumaczony dokument z dodanym rozszerzeniem .po4a-stamp.
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.
--no-translations
Nie generuje przetłumaczonych dokumentów, aktualizuje tylko pliki POT i PO.
--no-update
Do not change the POT and PO files, only the translation may be updated.
--rm-translations
Usuwa przetłumaczone pliki (wymusza --no-translations).
--no-backups
Od wersji 0.41 ta flaga nic nie robi i może zostać usunięta w kolejnych wersjach.
--rm-backups
Od wersji 0.41 ta flaga nic nie robi i może zostać usunięta w kolejnych wersjach.
--translate-only plik_przetłumaczony
Tłumaczy tylko podany plik. Może być to użyteczne do przyspieszenia przetwarzania, gdy plik
konfiguracyjny zawiera odwołania do wielu plików. Proszę zauważyć, że ta opcja nie aktualizuje plików
PO i POT. Można tej opcji użyć wiele razy.
--variable zmienna=wartość
Definiuje zmienną, która będzie rozwinięta w pliku konfiguracyjnym po4a. Każde użycie $(zmienna)
zostanie zastąpione przez wartość. Tę opcję można podać wielokrotnie.
--srcdir KATALOG_ŹRÓDŁOWY
Określa katalog bazowy dla wszystkich dokumentów wejściowych podanych w pliku konfiguracyjnym po4a.
--destdir KATALOG_DOCELOWY
Określa katalog bazowy dla wszystkich dokumentów wyjściowych podanych w pliku konfiguracyjnym po4a.
OPTIONS WHICH MODIFY POT HEADER
--porefs type[,wrap|nowrap]
Specify the reference format. Argument type can be one of never to not produce any reference, file to
only specify the file without the line number, counter to replace line number by an increasing
counter, and full to include complete references (default: full).
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.
--msgid-bugs-address adres@e-mail
Ustawia adres, pod który należy zgłaszać błędy w polach msgid. Domyślnie, utworzone pliki POT nie
zawierają nagłówków Report-Msgid-Bugs-To.
--copyright-holder string
Ustawia właściciela praw autorskich w nagłówku POT. Domyślną wartością jest "Free Software
Foundation, Inc."
--package-name nazwa
Ustawia nazwę pakietu w nagłówku POT. Domyślną wartością jest "PACKAGE".
--package-version wersja
Ustawia wersję pakietu w nagłówku pliku POT. Domyślną wartością jest "VERSION".
OPTIONS TO MODIFY PO FILES
--msgmerge-opt options
Extra options for msgmerge(1).
Uwaga: $lang zostanie zastąpione nazwą bieżącego języka.
--no-previous
Opcja usuwa --previous z opcji przekazywanych programowi msgmerge. Pozwala to na używanie wersji
wcześniejszych niż 0.16 pakietu gettext.
--previous
Opcja dodaje --previous do opcji przekazywanych programowi msgmerge. Wymaga wersji 0.16 lub
późniejszej pakietu gettext i jest domyślnie włączona.
PRZYKŁAD
Załóżmy, że opiekujemy się programem o nazwie foo, który zawiera stronę podręcznika ekranowego man/foo.1
napisaną tylko w języku angielskim, i chcemy dodać tłumaczenia. Pierwszą rzeczą, którą musimy zrobić,
jest utworzenie pliku POT, niezbędnego do wysłania go do tłumaczy, używając w tym celu
po4a-gettextize(1).
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
MANKAMENTY
• Duplikuje część kodu innych programów po4a-*.
Łata (patch) mile widziana ;)
ZOBACZ TAKŻE
po4a-build(1), po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1),
po4a-build.conf(5), po4a(7)
AUTORZY
Denis Barbier <barbier@linuxfr.org>
Nicolas François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
TŁUMACZENIE
Robert Luberda <robert@debian.org>
PRAWA AUTORSKIE I LICENCJA
Copyright 2002-2012 by SPI, inc.
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub modyfikować zgodnie z warunkami
licencji GPL (patrz plik COPYING).
Narzędzia po4a 2017-08-26 PO4A(1p)