Provided by: po4a_0.55-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  jest użyteczny, jeżeli jest wiele plików do przetłumaczenia, różne formaty
       tych plików lub istnieje potrzeba przekazywania różnych opcji dla różnych dokumentów oraz
       chce się uniknąć wywoływania po4a-gettextize(1), po4a-updatepo(1) i po4a-translate(1) w
       złożonych Makefile'ach.

Spis treści

       Dokument jest zorganizowany następująco:

   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

WPROWADZENIE

       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.

       Normal case without specifying pot_in:

        <- source files ->|<--------- build results --------------->

        addendum ----------------------------------+
                                                   |
        master document --+---------------------+  |
                          V                     +--+--> translations
        old PO files -----+--> updated PO files +
             ^                      |
             |                      V
             +<.....................+
           (the updated PO files are manually
            copied to the source of the next
            release while manually updating
            the translation contents)

       Special case with specifying pot_in:

        <- source files ->|<--------- build results ----------------->

        master document --+--------------------------+
                          :                          |
        external          :    filtered              |
        filtering ========X..> master                |
        program                document              |
                               |                     |
                               V                     +--> translations
        old PO files ----------+--> updated PO files +
             ^                           |
             |                           V
             +<..........................+
           (the updated PO files are manually
            copied to the source of the next
            release while manually updating
            the translation contents)

       The dataflow cannot be reversed in this tool, and changes in translations are overwritten
       by the content of the PO files. As a matter of fact, this tool cannot be used to convert
       existing translations to the po4a system. For that task, please refer to
       po4a-gettextize(1).

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

       You can also use $master to refer to the document filename. In this case, po4a will use a
       split mode: one POT and one PO (for each language) will be created for each document
       specified in the po4a configuration file.  See the Split mode section.

        [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
        [type: docbook] doc/script.xml fr:doc/fr/script.xml \
                    de:doc/de/script.xml \
                    pot_in:doc/script.filtered.xml

       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>] <master_doc> (<lang>:<localized_doc>)* \
                         (pot_in:<filtered_master_doc>)? \
                         (add_<lang>:<modifier>*<addendum_path>)*

       If pot_in is specified, filtered_master_doc is used to create POT file instead of
       master_doc.  This feature allows user to create flexible ways to avoid contents which
       shouldn't be included in the PO files.  Tools such as C preprocessor (cpp) or XSL
       Transformation utility (e.g., xsltproc) can be used to create the external filtering
       program and call it before invoking po4a.

       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.

       If you need a specific option for one of the documents you want to translate, you can also
       specify it in the configuration file. Options are introduced by the opt keyword. The
       argument of the opt keyword must be quoted with double quotes if it contains a space (e.g.
       if you specify multiple options, or an option with an argument).  You can also specify
       options that will only apply to a specific language by using the opt_lang keyword.

       Tu jest przykład:
        [type:man] t-05-config/test02_man.1 $lang:tmp/test02_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.

       This module alias can then be used like a regular module:

        [type:test] t-05-config/test02_man.1 $lang:tmp/test02_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.

       If there are name conflicts because several files have the same filename, the name of the
       master file can be specified by adding a "master:file="name option:

        [po4a_langs] de fr ja
        [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
        [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
        [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

OPCJE

       -k, --keep
           Minimal threshold for translation percentage to keep (i.e. write) the resulting file
           (default: 80). I.e. by default, files have to be translated at least at 80% to get
           written.

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

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

       -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:

               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.

       --no-update
           Do not change the POT and PO files, only the translation may be updated.

       --keep-translations
           Keeps the existing translation files even if the translation doesn't meet the
           threshold specified by --keep.  This option does not create new translation files with
           few content, but it will save existing translations which decay because of changes to
           the master files.

           WARNING: This flag changes the po4a behavior in a rather drastic way: your translated
           files will not get updated at all until the translation improves. Only use this flag
           if you prefer shipping an outdated translated documentation rather than only shipping
           an accurate untranslated documentation.

       --rm-translations
           Usuwa przetłumaczone pliki (wymusza --no-translations).

       --no-backups
           Od wersji 0.41 ta flaga nic nie robi i może zostać usunięta w kolejnych wersjach.

       --rm-backups
           Od wersji 0.41 ta flaga nic nie robi i może zostać usunięta w kolejnych wersjach.

       --translate-only plik_przetłumaczony
           Tłumaczy tylko podany plik. Może być to użyteczne do przyspieszenia przetwarzania, gdy
           plik konfiguracyjny zawiera odwołania do wielu plików. Proszę zauważyć, że ta opcja
           nie aktualizuje plików PO i POT. Można tej opcji użyć wiele razy.

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

       --srcdir KATALOG_ŹRÓDŁOWY
           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.

   OPTIONS WHICH MODIFY POT HEADER
       --porefs type[,wrap|nowrap]
           Specify the reference format. Argument type can be one of never to not produce any
           reference, file to only specify the file without the line number, counter to replace
           line number by an increasing counter, and full to include complete references
           (default: full).

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

           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

       Once this is set up you don't need to touch the Makefile when a new translation arrives,
       i.e. if the French team sends you fr.po and fr.add then you simply drop them respectively
       in man/po4a/po/ and man/po4a/add_fr/ and the next time the program is built the French
       translation is automatically build as well in 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

MANKAMENTY

       ·   Duplikuje część kodu innych programów po4a-*.

       Łata (patch) mile widziana ;)

ZOBACZ TAKŻE

       po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7)

AUTORZY

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

TŁUMACZENIE

        Robert Luberda <robert@debian.org>

PRAWA AUTORSKIE I LICENCJA

       Copyright 2002-2012 by SPI, inc.

       Program jest wolnym oprogramowaniem; można go redystrybuować i/lub modyfikować zgodnie z
       warunkami licencji GPL (patrz plik COPYING).