Provided by:
po4a_0.38-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" 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
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
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 po. 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
Można także użyć zmiennej $master, aby odwołać się do nazwy bazowej
dokumentu. W takim przypadku po4a użyje trybu rozdzielonego: dla
każdego dokumentu podanego w pliku konfiguracji po4a zostanie utworzony
jeden plik POT i jeden plik PO (dla każdego języka). Patrz sekcja Tryb
rozdzielony.
[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.
[katalog_po] 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_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 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>:<załącznik>*
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_l<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.
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.
-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:
-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.
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.
--rm-translations
Usuwa przetłumaczone pliki (wymusza --no-translations).
--no-backups
Nie generuje plików zapasowych .po~.
--rm-backups
Usuwa kopie zapasowe .po~ (wymusza --no-backups).
--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.
--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".
--msgmerge-opt options
Dodatkowe opcje przekazywane programowi msgmerge.
Note: $lang will be extended to the current language.
--no-previous
This option removes '--previous' from the options passed to
msgmerge. This permits to support versions of gettext earlier than
0.16.
--previous
This option adds '--previous' to the options passed to msgmerge.
It requires gettext 0.16 or later, and is activated by default.
--srcdir KATALOG_RDOWY
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.
MANKAMENTY
o Duplikuje część kodu innych programów po4a-*.
Łata (patch) mile widziana ;)
ZOBACZ TAKŻE
po4a(7), po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
po4a-normalize(1).
AUTORZY
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
PRAWA AUTORSKIE I LICENCJA
Copyright 2002, 2003, 2004 by SPI, inc.
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).