Linux Certif

Toute la documentation sur la certification Linux LPI

po4a.1p

NAZWA

po4a - aktualizowanie w jednym przebiegu zarówno plików po, jak i przetłumaczonych dokumentów

SKŁADNIA

po4a [options] <config_file>

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
 
 

Autodetection of the paths and languages

Another command can be used to specify the name of a directory where the PO and POT files are located. When it is used, po4a will detect the POT file as the only ``*.pot'' file from the specified directory. Po4a will also use the list of ``*.po'' files to define the list of languages (by stripping out the extension). These languages will be used for the substitution of the $lang variable in the rest of the configuration file.

This command should not be used together with the po4a_langs or po4a_paths commands.

  [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_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 string

Set the package name for the POT header. The default is ``PACKAGE''.

--package-version string

Set the package version for the POT header. The default is ``VERSION''.

--msgmerge-opt options

Dodatkowe opcje przekazywane programowi msgmerge.

--previous

Opcja dodaje ``--previous'' do opcji przekazywanych programowi msgmerge. Wymaga wersji 0.16 lub późniejszej pakietu gettext.

MANKAMENTY

*

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)
 
 

TŁUMACZENIE

  Robert Luberda <robert@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).