Provided by: po4a_0.38-1_all bug

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