Provided by: po4a_0.41-1_all bug

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