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¶

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

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].

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.

OPTIONS WHICH MODIFY POT HEADER¶

porefs type[,wrap|nowrap]

Specify the reference format. Argument type can be one of none to not produce any reference, noline to not specify the line number (more accurately all line numbers are replaced by 1), counter to replace line number by an increasing counter, and full to include complete references.

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

Dodatkowe opcje przekazywane programowi msgmerge.

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