Provided by:
po4a_0.41-1_all 
NAZWA
po4a - aktualizowanie w jednym przebiegu zarowno plikow PO, jak i
przetlumaczonych dokumentow
SK/LADNIA
po4a [opcje] plik_konfiguracyjny
OPIS
Celem projektu po4a ("PO for anything") jest ulatwienie tlumacze (oraz,
co ciekawsze, zarzdzania tlumaczeniami) przy uyciu narzdzi gettext w
tych obszarach, gdzie nie byly uywane, jak na przyklad w obszarze
dokumentacji.
Program po4a jest uyteczny, jeeli jest wiele plikow do
przetlumaczenia, rone formaty tych plikow lub istnieje potrzeba
przekazywania ronych opcji dla ronych dokumentow oraz chce si unikn
wywolywania po4a-gettextize(1), po4a-updatepo(1) i po4a-translate(1) w
zloonych Makefile'ach.
Spis treci
Dokument jest zorganizowany nastpujco:
OPIS
WPROWADZENIE
SK/LADNIA PLIKU KONFIGURACYJNEGO
Okrelanie jzyk'ow szablon'ow
Podawanie cieek plik'ow wejciowych t/lumaczenia
Automatyczne wykrywanie cieek i jzyk'ow
Okrelanie dokument'ow do przet/lumaczenia
Okrelanie opcji modu/l'ow
Podawanie alias'ow
Tryb rozdzielony
OPCJE
PRZYK/LAD
MANKAMENTY
ZOBACZ TAKE
AUTORZY
PRAWA AUTORSKIE I LICENCJA
WPROWADZENIE
Program po4a odpowiada za aktualizowanie zarowno plikow PO (eby
zsynchronizowa z oryginalnymi dokumentami), jak i tlumaczonych
dokumentow (eby zsynchronizowa je z plikami PO). Glownym celem jest
uproszczenie uycia po4a, tak eby nie trzeba bylo pamita opcji linii
polece.
Pozwala take miesza dokumenty majce rone formaty w tym samym pliku POT,
tak e mona mie tylko jeden taki plik w projekcie.
Inne narzdzia pakietu po4a mog naladowa to zachowanie (na przyklad w
Makefile'ach), jednak jest to raczej trudne do wykonania, przerabianie
za tych samych skomplikowanych plikow Makefile dla kadego projektu
uywajcego po4a moe by mczce.
Przeplyw danych moe by podsumowany nastpujco. Jakakolwiek zmiana w
glownym dokumencie bdzie przeniesiona do plikow PO, a wszystkie zmiany
w plikach PO (albo rczne, albo spowodowane przez poprzedni krok) bd
przeniesione do przetlumaczonych dokumentow.
glowny dokument --> pliki PO --> tlumaczenia
Przeplyw danych w tym narzdziu nie moe zosta odwrocony, wic zmiany w
tlumaczeniach s zawsze nadpisane przez zawarto plikow PO. Tak wic nie
mona go uy do skonwertowania istniejcych tlumacze do systemu po4a.
Prosz przeczyta po4a-gettextize(1), aby dowiedzie si, jak wykona to
zadanie.
SK/LADNIA PLIKU KONFIGURACYJNEGO
Argument (obowizkowy) jest ciek do pliku konfiguracyjnego, ktory
zostanie uyty. Jego skladnia jest prosta i zbliona do skladni plikow
konfiguracyjnych uywanych przez projekty intl-tools.
Komentarze w plikach s oznaczane przez znak "#". Komentuj wszystko, a
do napotkania koca linii. Linie mog by kontynuowane przez wycytowanie
koca linii znakiem "\". Wszystkie niepuste linie musz zaczyna si
poleceniem [], po ktorym nastpuj jego argumenty. (Wyglda to na trudne,
ale mam nadziej, e jest raczej latwe ;) ).
Okrelanie jzyk'ow szablon'ow
Uwaga: Zaleca si uywanie [po_directory] zamiast [po4a_langs] i
[po4a_paths]. Prosz przeczyta akapit Automatyczne wykrywanie cieek i
jzyk'ow poniej.
Jest to nieobowizkowe polecenie, ktore moe uproci caly plik
konfiguracyjny i uczyni go bardziej skalowalnym. Naley okreli list
jzykow, na ktore dokumenty zostan przetlumaczone. Jest to bardzo
proste:
[po4a_langs] fr de
Umoliwi to rozszerzenie $lang do wszystkich jzykow podanych w
pozostalej czci pliku konfiguracyjnego.
Podawanie cieek plik'ow wejciowych t/lumaczenia
Uwaga: Zaleca si uywanie [po_directory] zamiast [po4a_langs] i
[po4a_paths]. Prosz przeczyta akapit Automatyczne wykrywanie cieek i
jzyk'ow poniej.
Najpierw naley okreli, gdzie znajduj si pliki wejciowe tlumacza (tj.
pliki uywane przez tlumaczy w czasie ich pracy). Moe 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 cieka
uywanego pliku POT. Wszystkie kolejne argumenty maj nastpujc
samotlumaczc si form:
<jzyk>:<cieka do pliku PO dla tego jzyka>
Jeli zdefiniowano szablony jzykow, mona zapisa powysze linie w ten
sposob:
[po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
Mona take uy zmiennej $master, aby odwola si do nazwy bazowej
dokumentu. W takim przypadku po4a uyje trybu rozdzielonego: dla kadego
dokumentu podanego w pliku konfiguracji po4a zostanie utworzony jeden
plik POT i jeden plik PO (dla kadego jzyka). Patrz sekcja Tryb
rozdzielony.
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
Automatyczne wykrywanie cieek i jzyk'ow
Mona uy jeszcze innego polecenia dookrelenia nazwy katalogu
zawierajcego pliki PO i POT. Kiedy jest uywane, to po4a wykryje plik
POT jako jedyny plik *.pot w podanym katalogu. po4a uyje take listy
plikow *.po do okrelenia listy jzykow (przez usunicie rozszerzenia
pliku). Jzyki te bd uyte w podstawieniach zmiennej $lang w dalszej czci
pliku konfiguracyjnego.
Polecenie to nie powinno by uywane razem z poleceniami [po4a_langs] lub
[po4a_paths].
Przed pierwszym uyciem tego polecenia, naley utworzy pusty plik POT,
tak aby po4a mogl pozna jego nazw.
[po_directory] po4a/po/
Okrelanie dokument'ow do przet/lumaczenia
Oczywicie naley poda, ktore dokumenty s tlumaczone, jaki jest ich
format i gdzie umieci tlumaczenia. Moe to by zrobione za pomoc takich
linii:
[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
de:doc/de/mein_cram.sgml
[type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
add_fr:doc/l10n/script.fr.add
Powinno by to zrozumiale bez dodatkowych wyjanie. Prosz zauway, e w
drugim wypadku doc/l10n/script.fr.add jest zalcznikiem do francuskiej
wersji tego dokumentu. Dalsze szczegoly na temat zalcznikow mona znale
w po4a(7).
Bardziej formalnie, format jest nastpujcy:
[type: <format>] <glowny_doc> (<jzyk>:<przetlumaczony_doc>)* \
(add_<jzyk>:<modyfikator>*<cieka_do_zalcznika>*)
Jeeli nie podano adnych modyfikatorow cieka_do_za/lcznika jest ciek do
pliku zalcznika. Modyfikatory s nastpujce:
? Wlcza plik cieka_do_za/lcznika, jeli taki plik istnieje. W przeciwnym
wypadku nic nie robi.
@ cieka_do_za/lcznika nie jest zwyklym zalcznikiem, ale plikiem
zawierajcym list zalcznikow, po jednym w kadej linii. Kady zalcznik
moe by poprzedzony modyfikatorem.
! Plik cieka_do_za/lcznika jest calkowicie ignorowany - nie jest
ladowany i nie bdzie, nawet jeli pojawia si w poniejszych
specyfikacjach zalcznikow.
Jeli zdefiniowano szablony jzykow, mona zapisa powysze linie w ten
sposob:
[type: pod] script $lang:doc/$lang/script.1 \
add_fr:doc/l10n/script.fr.add
Jeli wszystkie jzyki maj zalczniki o podobnych ciekach, mona napisa co
takiego:
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
Okrelanie opcji modu/l'ow
po4a akceptuje opcje, ktore bd przekazane do modulu. Te opcje s
specyficzne dla modulu i mog by okrelone w przelczniku -o.
Jeli jest potrzeba uycia okrelonej opcji tylko dla jednego dokumentu,
ktory ma by przetlumaczony, to mona to take poda w pliku
konfiguracyjnym. Opcje s wprowadzane slowem kluczowym opt. Jeeli
argument slowa kluczowego opt zawiera spacje (np. gdy si podaje wiele
opcji lub opcj z argumentem), to musi by ujty w cudzyslowy. Mona take
poda opcje, ktore bd stosowane tylko do okrelonego jzyka, uywajc slowa
kluczowego opt_jzyk.
Tu jest przyklad:
[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, jeeli zostan otoczone pojedynczymi
cudzyslowami lub cytowanymi (tj. poprzedzonymi znakiem \) podwojnymi
cudzyslowami:
[po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"
Aby poda te same opcje dla wielu dokumentow, mona uy aliasow (patrz
poniej, sekcja Podawanie alias'ow).
Mona okreli take zbior opcji dla wszystkich dokumentow okrelonych
w pliku konfiguracyjnym:
[options] opt:"..." opt_fr:"..."
Podawanie alias'ow
Jeli zachodzi potrzeba podania tej samej opcji w wielu plikach, mona
rozway zdefiniowania aliasu modulu. Mona to zrobi tak:
[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
Powysze definiuje alias modulu nazwany test, oparty na module man z
opcj -k 21 stosowan do wszystkich jzykow i z opcj -o debug-splitargs
zastosowan do tlumaczenia na jzyk hiszpaski.
Alias modulu moe by uyty jako zwykly modul:
[type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v
Prosz zauway, e mona poda dodatkowe opcje osobno dla kadego pliku.
Tryb rozdzielony
Tryb rozdzielony jest uywany, jeeli w linii [po4a_paths] uywana jest
zmienna $master.
W trybie rozdzielonym uywane s tymczasowy duy plik POT i tymczasowy duy
PO. Pozwala to na wspoldzielenie tlumacze pomidzy wszystkimi plikami
PO.
Jeeli dwa pliki PO maj rone tlumaczenia tego samego komunikatu, po4a
zaznaczy ten komunikat jako niepewny i umieci oba tlumaczenia we
wszystkich plikach PO, ktore zawieraj ten komunikat. Nastpnie, jeeli
tlumacz zaktualizuje tlumaczenie i usunie znacznik niepewnoci
("fuzzy"), to tlumaczenie tego komunikatu zostanie automatycznie
zaktualizowane w kadym pliku PO.
OPCJE
-k, --keep
Minimalny procentowy prog tlumacze pozwalajcy zachowa (tj. zapisa)
plik wynikowy (domylnie: 80). Czyli, domylnie, aby pliki zostaly
zapisane, musz by przetlumaczone co najmniej w 80%.
-h, --help
Pokazuje krotki komunikat pomocy.
-M, --master-charset
Kodowanie znakow plikow zawierajcych dokumenty do przetlumaczenia.
Prosz zauway, e wszystkie pliki musz mie to samo kodowanie znakow.
-L, --localized-charset
Kodowanie znakow plikow zawierajcych dokumenty do przetlumaczenia.
Prosz zauway, e wszystkie pliki musz mie to samo kodowanie znakow.
-A, --addendum-charset
Kodowanie znakow zalcznika. Prosz zauway, e wszystkie zalczniki
powinny mie to samo kodowanie znakow.
-V, --version
Wywietla wersj skryptu i koczy dzialanie.
-v, --verbose
Zwiksza gadatliwo programu.
-q, --quiet
Zmniejsza gadatliwo programu.
-d, --debug
Wypisuje informacje przydatne do debugowania.
-o, --option
Dodatkowe opcje przekazywane modulowi formatu. Kada opcja powinna
by w formacie "nazwa=warto". Wicej informacji o dostpnych opcjach i
ich znaczeniu mona znale w dokumentacji kadego modulu.
-f, --force
Zawsze generuje pliki POT i PO, nawet jeeli po4a uwaa to za
niepotrzebne.
Domylne zachowanie (jeli nie podano --force) jest nastpujce:
Jeeli 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 rzeczywicie jest potrzeba jego zmieniania.
Ponadto tlumaczenie zostanie ponownie wygenerowane, jeeli
oryginalny dokument, plik PO, jeden z zalcznikow lub plik
konfiguracyjny s od niego nowsze. Aby unikn prob ponownego
generowania tlumacze, ktore s poniej zdefiniowanego progu
(patrz --keep), mona utworzy plik z rozszerzeniem .po4a-stamp
(patrz --stamp).
Jeli jakie pliki s wlczane (include) do oryginalnego dokumentu,
naley uy flagi --force, poniewa czasy modyfikacji wlczanych plikow
nie s brane pod uwag.
Pliki PO s zawsze ponownie generowane na podstawie plikow POT za
pomoc msgmerge -U.
--stamp
Nakazuje programowi po4a tworzenie plikow ze znacznikiem czasowym,
jeeli tlumaczenie nie zostanie wygenerowane z powodu
nieprzekroczenia zdefiniowanego progu. Pliki znacznikow maj nazw
tak jak oczekiwany przetlumaczony dokument z dodanym rozszerzeniem
.po4a-stamp.
Uwaga: Ta opcja aktywuje tworzenie plikow .po4a-stamp. Pliki
znacznikow, jeeli tylko istniej, to s zawsze uywane. Pliki te s
usuwane za pomoc --rm-translations, albo gdy plik zostanie w kocu
przetlumaczony.
--no-translations
Nie generuje przetlumaczonych dokumentow, aktualizuje tylko pliki
POT i PO.
--rm-translations
Usuwa przetlumaczone pliki (wymusza --no-translations).
--no-backups
Od wersji 0.41 ta flaga nic nie robi i moe zosta usunita w
kolejnych wersjach.
--rm-backups
Od wersji 0.41 ta flaga nic nie robi i moe zosta usunita w
kolejnych wersjach.
--translate-only plik_przet/lumaczony
Tlumaczy tylko podany plik. Moe by to uyteczne do przyspieszenia
przetwarzania, gdy plik konfiguracyjny zawiera wiele plikow Prosz
zauway, e ta opcja nie aktualizuje plikow PO i POT. Mone tej opcji
uy wiele razy.
--variable zmienna=warto
Definiuje zmienn, ktora bdzie rozwinita w pliku konfiguracyjnym
po4a. Kade uycie $(zmienna) zostanie zastpione przez warto. T opcj
mona poda wielokrotnie.
--msgid-bugs-address adres@e-mail
Ustawia adres, pod ktory naley zglasza bldy w polach msgid.
Domylnie, utworzone pliki POT nie zawieraj naglowkow Report-Msgid-
Bugs-To.
--copyright-holder string
Ustawia wlaciciela praw autorskich w naglowku POT. Domyln wartoci
jest "Free Software Foundation, Inc."
--package-name nazwa
Ustawia nazw pakietu w naglowku POT. Domyln wartoci jest "PACKAGE".
--package-version wersja
Ustawia wersj pakietu w naglowku pliku POT. Domyln wartoci jest
"VERSION".
--msgmerge-opt options
Dodatkowe opcje przekazywane programowi msgmerge.
Uwaga: $lang zostanie zastpione nazw biecego jzyka.
--no-previous
Opcja usuwa --previous z opcji przekazywanych programowi msgmerge.
Pozwala to na uywanie wersji wczeniejszych ni 0.16 pakietu gettext.
--previous
Opcja dodaje --previous do opcji przekazywanych programowi
msgmerge. Wymaga wersji 0.16 lub poniejszej pakietu gettext i jest
domylnie wlczona.
--srcdir KATALOG_R'OD/LOWY
Okrela katalog bazowy dla wszystkich dokumentow wejciowych podanych
w pliku konfiguracyjnym po4a.
--destdir KATALOG_DOCELOWY
Okrela katalog bazowy dla wszystkich dokumentow wyjciowych podanych
w pliku konfiguracyjnym po4a.
PRZYK/LAD
Zalomy, e opiekujemy si programem o nazwie foo, ktory zawiera stron
podrcznika ekranowego man/foo.1 napisan tylko w jzyku angielskim, i
chcemy doda tlumaczenia. Pierwsz rzecz, ktor musimy zrobi, jest
utworzenie pliku POT, niezbdnego do wyslania go do tlumaczy, uywajc w
tym celu po4a-gettextize(1).
W naszym przypadku wywolalibymy:
cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
Nastpnie wygenerowany plik nalealoby wysla na odpowiedni list
dystrybucyjn dotyczc tlumacze lub umieci na stronach www do pobrania.
Nastpnie zalomy, e otrzymalimy trzy tlumaczenia: de.po (wraz z
zalcznikiem de.add), sv.po oraz pt.po. Poniewa nie chcemy zmienia
plikow Makefile za kadym razem, gdy dodawane jest nowe tlumaczenie,
moemy w Makefile'u uy po4a z odpowiednim plikiem konfiguracyjnym -
nazwijmy go po4a.cfg. W naszym przypadku wygldalby 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 przykladzie zaloylimy, e wygenerowane strony podrcznika
ekranowego (wraz z wszystkimi plikami PO i zalcznikami) bd
przechowywane w katalogu man/translated/$lang/ (odpowiednio
man/po4a/po/ i man/po4a/add_$lang/). Tak wic katalog man/po4a/po/
zawieralby pliki de.po, pt.po i sv.po, a katalog man/po4a/add_de/ -
de.add.
Prosz zwroci uwag na uycie modyfikatora ?. Jest potrzebny, poniewa
zalcznik wystpuje tylko dla tlumaczenia na jzyk niemiecki (de.po).
Aby zbudowa przetlumaczone strony podrcznika, naley (jednokrotnie!)
doda nastpujc lini w celu build odpowiedniego pliku Makefile:
po4a po4a.cfg
Dziki takiej konfiguracji, nie bdzie trzeba zmienia Makefile'a, gdy
przybdzie nowe tlumaczenie. Jeeli na przyklad zespol francuski przyle
pliki fr.po i fr.add, to jedyne co trzeba zrobi, to umieci jest w
katalogach man/po4a/po/ i man/po4a/add_fr/ - podczas nastpnego
budowania programu, tlumaczenia na jzyk francuski zbuduj si
automatycznie i zostan umieszczone w man/translated/fr/.
Prosz zauway, e wci bdzie potrzebny odpowiedni cel w makefile'u
instalujcy przetlumaczone strony podrcznika razem z ich angielsk wersj.
W kocu, jeeli wygenerowane pliki nie s przechowywane w systemie
kontroli wersji, to naley doda odpowiednie linie w celu clean, np.:
-rm -rf man/translated
MANKAMENTY
o Duplikuje cz kodu innych programow po4a-*.
Lata (patch) mile widziana ;)
ZOBACZ TAKE
po4a(7), po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
po4a-normalize(1), po4a-build(1), po4a-build.conf(5).
AUTORZY
Denis Barbier <barbier@linuxfr.org>
Nicolas Francois <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
PRAWA AUTORSKIE I LICENCJA
Copyright 2002-2010 by SPI, inc.
Program jest wolnym oprogramowaniem; mona go redystrybuowa i/lub
modyfikowa zgodnie z warunkami licencji GPL (patrz plik COPYING).