Provided by: po4a_0.41-1ubuntu1_all bug

NAZWA

       po4a - narzdzia do tlumacze dokumentacji i innych materialow

Wstp

       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.

Spis treci

       Dokument jest zorganizowany nastpujco:

       1. Dlaczego powinno si uywa po4a? Jakie s jego zalety?
           Ten rozdzial wprowadzenia wyjania motywy i filozofi projektu. Jeeli
           rozwaasz uycie po4a do Twoich tlumacze, powiniene najpierw
           przeczyta ten rozdzial.

       2. Jak uywa po4a?
           Rozdzial ten jest rodzajem podrcznika i probuje odpowiedzie na
           pytania uytkownikow, pozwalajc lepiej zrozumie caly proces.
           Odpowiada, jak wykona rone rzeczy w po4a, i sluy jako wprowadzenie
           do dokumentacji konkretnych narzdzi.

           JAK zacz nowe tlumaczenie?
           JAK zamieni tlumaczenie z powrotem do pliku dokumentacji?
           JAK zaktualizowa tlumaczenie programem po4a?
           JAK skonwertowa istniejce tlumaczenia do po4a?
           JAK doda dodatkowy tekst do tlumacze (np. nazwisko tlumacza)?
           JAK to wszystko zrobi, wywolujc tylko jeden program?
           JAK dostosowa po4a do wlasnych potrzeb?
       3. Jak to dziala?
           Ten rozdzial zawiera krotki opis wewntrznych mechanizmow po4a, tak
           e bdziesz mial wicej odwagi, aby pomoc nam w jego tworzeniu i
           udoskonalaniu. Moe take Ci pomoc w zrozumieniu, dlaczego nie dziala
           tak, jak by tego oczekiwal, oraz jak rozwiza napotkane problemy.

       4. FAQ
           Ten rozdzial zawiera odpowiedzi na czsto zadawane pytania. Tak
           naprawd, wikszo tych pyta moe by sformulowanych jako "Dlaczego po4a
           zostalo zaprojektowane tak, a nie inaczej?". Jeli wydaje Ci si, e
           po4a nie jest wlaciwym narzdziem do tlumaczenia dokumentacji,
           powiniene rozway przeczytanie tego rozdzialu. Jeli nie znajdziesz w
           nim odpowiedzi na swoje pytanie, prosimy si z nami skontaktowa
           poprzez list dyskusyjn <po4a-devel@lists.alioth.debian.org>.
           Uwielbiamy zna opinie uytkownikow.

       5. Specyficzne uwagi o modulach
           Ten rozdzial opisuje rzeczy specyficzne dla kadego modulu, z punktu
           widzenia zarowno tlumacza, jak i autora oryginalnego dokumentu.
           Czytajc ten rozdzial, dowiesz si, kiedy dany modul wykonuje
           tlumaczenia oraz jakich zasad powiniene przestrzega, piszc
           oryginalny dokument, aby uproci ycie tlumaczom.

           W zasadzie, ta sekcja nie jest czci tego dokumentu. Zamiast tego
           jest umieszczana w dokumentacji kadego modulu. Pomaga to w
           zapewnieniu aktualnoci tych informacji, trzymajc kod i dokumentacj
           razem.

Dlaczego uywa po4a? Do czego jest on przydatny?

       Podoba mi si idea wolnego oprogramowania, pozwalajcego kademu na dostp
       do programow i ich kodow rodlowych. Bdc jednak Francuzem, jestem
       wiadomy tego, e licencja programu nie jest jedynym ograniczeniem
       otwartoci oprogramowania: nieprzetlumaczone oprogramowanie jest
       bezuyteczne dla ludzi nieznajcych angielskiego, wic cigle czeka na nas
       duo pracy, eby udostpni je kadej takiej osobie.

       wiadomo tego problemu wrod osob zwizanych z oprogramowaniem open-source
       ostatnio znacznie wzrosla. Wygralimy, jako tlumacze, pierwsz bitw i
       przekonalimy wszystkich o znaczeniu tlumacze. Niestety, to byla ta
       latwiejsza cz. Teraz musimy wykona nasz prac i przetlumaczy wszystkie
       te rzeczy.

       Wlaciwie oprogramowanie typu open-source ma do przyzwoity poziom
       tlumacze, dziki wspanialemu pakietowi gettext, ktory ma moliwoci
       wyodrbniania z programu komunikatow do przetlumaczenia, przekazywania
       tlumaczom plikow w jednolitym formacie i uywania wynikow ich pracy do
       pokazywania uytkownikowi przetlumaczonych komunikatow w czasie
       dzialania programu.

       W przypadku dokumentacji sytuacja jest troch inna. Zbyt czsto si
       zdarza, e tlumaczony dokument nie jest dostatecznie widoczny (nie jest
       dystrybuowany jako cz programu), jest tylko czciowy lub nie jest
       aktualny. Ostatnia sytuacja jest najgorsz z moliwych. Przestarzale
       tlumaczenie, opisujce stare, ju nieistniejce zachowanie programu, moe
       by o wiele gorsze dla uytkownika ni brak tlumaczenia w ogole.

   Problem do rozwizania
       Tlumaczenie dokumentacji samo w sobie nie jest zbyt trudne. Teksty s
       duo dlusze ni komunikaty wywietlane przez program, wic ich tlumaczenie
       zajmuje troch wicej czasu, nie wymaga przy tym jednak adnych umiejtnoci
       technicznych. Trudniejsz czci pracy jest zarzdzanie tlumaczeniem.
       Wykrywanie czci, ktore si zmienily i powinny by zaktualizowane, jest
       bardzo trudne, podatne na bldy i wysoce nieprzyjemne.
       Najprawdopodobniej wyjania to, dlaczego tak wiele przetlumaczonej
       dokumentacji nie jest aktualne.

   Odpowiedzi po4a
       Tak wic, celem po4a jest uczynienie tlumacze dokumentacji /latwymi do
       zarzdzania. Ide jest wykorzystanie metodologii gettexta na tym nowym
       polu. Tak jak w programie gettext, teksty s wyodrbniane z ich
       oryginalnych miejsc, aby mogly w jednolitym formacie zosta
       zaprezentowane tlumaczowi. Klasyczne narzdzia gettexta pomog im
       uaktualni ich prac, kiedy pojawi si nowa wersja oryginalnego dokumentu.
       W przeciwiestwie za do klasycznego modelu gettext, tlumaczenia s
       wstawiane do struktury oryginalnego dokumentu, tak eby mogly by
       przetwarzane i dystrybuowane w dokladnie taki sam sposob, co wersja
       angielska.

       Dziki temu stalo si latwiejsze znalezienie do przetlumaczenia
       zmienionych czci dokumentu. Innym plusem jest to, e w wypadku
       zasadniczej reorganizacji struktury dokumentu, gdy rozdzialy s
       przesuwane, lczone lub dzielone, narzdzia wykonaj prawie cal brudn
       robot. Wyodrbnianie ze struktury dokumentu tekstow do przetlumaczenia
       pozwala tlumaczom nie przejmowa si zloonoci struktury dokumentu i
       zmniejsza szanse otrzymania dokumentu o niepoprawnej strukturze (cho
       zawsze jest to moliwe).

       W sekcji FAQ poniej opisano kompletn list plusow i minusow tego
       rozwizania.

   Obs/lugiwane formaty
       Obecnie rozwizanie to zaimplementowano z sukcesem dla kilku formatow
       tekstu:

       man

       Format starych, dobrych stron podrcznika ekranowego, uywanego przez
       wiele programow. Obsluga tego formatu w po4a jest mile widziana,
       poniewa ten format jest raczej trudny w uyciu i niezbyt przyjazny dla
       nowych uytkownikow. Modul Locale::Po4a::Man(3pm) obsluguje rownie
       format mdoc,uywany przez strony podrcznika systemu BSD (calkiem czsto
       wystpujcych rownie pod Linuksem).

       pod

       Jest to format dokumentacji Perla. W ten sposob jest udokumentowany sam
       jzyk i jego rozszerzenia, a take wikszo istniejcych skryptow Perla.
       Lczenie dokumentacji i kodu w jednym pliku, pomaga utrzymywa aktualno
       dokumentacji. Upraszcza to ycie programisty, ale niestety, nie
       tlumacza.

       sgml

       Nawet jeli jest obecnie wypierany przez XML, ten format jest wci raczej
       czsto uywany w dokumentach o dlugoci wikszej ni kilka ekranow. Pozwala
       tworzy kompletne ksiki. Aktualizowane tlumacze tak dlugich dokumentow
       moe by prawdziwym koszmarem. Program diff bardzo czsto okazuje si
       bezuyteczny, jeli zmieni si struktura oryginalnego tekstu. Na szczcie,
       z pomoc moe przyj po4a.

       Obecnie obslugiwane s tylko DTD DebianDoc i docbook, ale dodanie
       obslugi nowego typu jest bardzo proste. Jest nawet moliwe uycie po4a z
       nieznanym DTD SGML bez zmiany kodu - przez podanie wymaganych
       informacji w parametrach linii polece. Szczegoly mona znale w
       Locale::Po4a::Sgml(3pm).

       TeX / LaTeX

       Format LaTeX jest glownym formatem dokumentacji uywanym w publikacjach
       pisanych przez ludzi zwizanych ze wiatem wolnego oprogramowania. Modul
       Locale::Po4a::LaTeX(3pm) byl testowany na dokumentacji Pythona, ksice i
       kilku prezentacjach.

       texinfo

       Cala dokumentacja GNU jest pisana w tym formacie (i jest to nawet jedno
       z wymaga stawianych projektom , ktore chc sta si oficjalnymi projektami
       GNU). Wsparcie dla  Locale::Po4a::Texinfo(3pm) jest wci w fazie
       pocztkowej. Prosimy o zglaszanie bldow i przesylanie uwag dotyczcych
       brakujcych funkcjonalnoci.

       xml

       XML jest formatem bazowym wielu innych formatow dokumentacji.

       Obecnie po4a obsluguje DocBook DTD. Szczegoly mona znale w
       Locale::Po4a::Docbook(3pm).

       inne

       Po4a moe take obslugiwa kilka rzadszych lub bardziej specjalizowanych
       formatow, takich jak dokumentacja opcji kompilacji jder 2.4 lub
       diagramow wyprodukowanych przez narzdzie dia. Dodanie nowego formatu
       jest czsto bardzo proste, a glownym zadaniem jest napisanie parsera
       tego formatu. Wicej informacji o tym mona znale w
       Locale::Po4a::TransTractor(3pm).

   Formaty niewspierane
       Niestety, po4a cigle nie obsluguje kilku formatow dokumentacji.

       Istnieje cala masa innych formatow, ktore bymy chcieli obslugiwa w
       po4a, i nie s to tylko formaty dokumentacji. W zasadzie, naszym celem
       jest wypelnienie wszystkich dziur pozostawionych przez klasyczne
       narzdzia gettext. Obejmuje to opisy pakietow (deb i rpm), pytania
       skryptow instalacyjnych pakietow, logi zmian pakietow i wszystkie
       specjalizowane formaty uywane przez programy, jak na przyklad
       scenariusze gier lub pliki zasobow wine.

Jak uywa po4a?

       Rozdzial ten jest rodzajem podrcznika i probuje odpowiedzie na pytania
       uytkownikow, pozwalajc lepiej zrozumie caly proces. Odpowiada, jak
       wykona rone rzeczy w po4a, i sluy jako wprowadzenie do dokumentacji
       konkretnych narzdzi.

   Graficzne podsumowanie
       Nastpujcy schemat pokazuje pogldowo proces tlumaczenia dokumentacji z
       uyciem po4a. Nie powinno si przejmowa jego pozorn zloonoci, ktora wzila
       si std, e pokazalimy tutaj ca/ly proces. Po skonwertowaniu projektu do
       po4a, istotna bdzie tylko prawa cz schematu.

       Prosz zauway, e master.doc wystpuje tu jako przyklad pliku dokumentacji
       do przetlumaczenia, a t/lumaczenie.doc jest odpowiadajcym mu tekstem
       przetlumaczonym. Rozszerzeniem moe by  .pod, .xml lub .sgml, zalenie od
       formatu pliku. Kad cz rysunku omowimy szczegolowo w nastpnych sekcjach.

                                          master.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
       {tlumaczenie}    |            { aktualizacja master.doc }       :
            :           |                     |                        :
          XX.doc        |                     V                        V
       (nieobowizkowy) |                  master.doc ------->-------->+
            :           |                   (nowy)                     |
            V           V                     |                        |
         [po4a-gettextize]   doc.XX.po--->+   |                        |
                 |           (stary)      |   |                        |
                 |              ^         V   V                        |
                 |              |     [po4a-updatepo]                  |
                 V              |           |                          V
         tlumaczenie.pot        ^           V                          |
                 |              |         doc.XX.po                    |
                 |              |         (fuzzy)                      |
          { tlumaczenie }       |           |                          |
                 |              ^           V                          V
                 |              |     {rczna edycja}                  |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<---- doc.XX.po  zalcznik    master.doc
            (pocztkowy)                  (aktualny) (opcjonalny)  (aktualny)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                                  [po4a-translate]
                                                         |
                                                         V
                                                       XX.doc
                                                     (aktualny)

       Lewa cz pokazuje konwersj tlumaczenia nie uywajcego jeszcze po4a do
       tego systemu. Gora prawej czci pokazuje akcje autora oryginalu
       (aktualizowanie dokumentacji). rodek prawej czci obrazuje automatyczne
       akcje po4a. Nowy material jest wyodrbniany i porownywany z istniejcymi
       tlumaczeniami. Znajdowane s czci, ktore si nie zmienily, i dla nich
       uywane jest poprzednie tlumaczenie. Czci zmodyfikowane tylko w
       nieznacznym stopniu s take lczone z poprzednimi tlumaczeniami, ale
       dodawany jest specjalny znacznik, mowicy, e tlumaczenie musi by
       uaktualnione. Dol rysunku pokazuje sposob, w jaki jest budowany
       sformatowany dokument.

       Wlaciwie, jedyn rczn operacj, ktor musi wykona tlumacz jest cz
       oznaczona {rczna edycja}. Przykro nam, po4a tylko pomaga tlumaczy, ale
       niestety niczego za Ciebie nie przetlumaczy...

   JAK zacz nowe t/lumaczenie?
       Ta sekcja opisuje kroki niezbdne do rozpoczcia nowego tlumaczenia z
       uyciem po4a. Konwertowanie istniejcego projektu do tego systemu opisano
       w szczegolach w odpowiedniej sekcji.

       Aby zacz nowe tlumaczenie, uywajc po4a, naley wykona nastpujce kroki:

       - Wycign tekst do przetlumaczenia z oryginalnego dokumentu <master.doc>
         do nowego szablonu pliku <t/lumaczenie.pot> (w formacie programu
         gettext). Aby to zrobi, naley wywola program po4a-gettextize w
         nastpujcy sposob:

           $ po4a-gettextize -f <format> -m <master.doc> -p <tlumaczenie.pot>

         <format> jest oczywicie formatem uywanym w dokumencie master.doc. Jak
         mona oczekiwa, plikiem wyjciowym jest t/lumaczenie.pot. Wicej
         szczegolow o dostpnych opcjach mona znale w po4a-gettextize(1).

       - Przetlumaczy to, co jest do przetlumaczenia. W tym celu naley zmieni
         nazw pliku POT na przyklad na doc.XX.po (gdzie XX jest kodem ISO639
         jzyka, na ktory si tlumaczy, np. fr dla jzyka francuskiego) i edytowa
         powstaly plik. Zazwyczaj dobrym pomyslem jest nienazywanie tego pliku
         XX.po, aby unikn pomylenia z tlumaczeniem komunikatow programu, ale
         wybor naley do Ciebie. Prosz nie zapomina o uaktualnieniu naglowkow
         pliku PO; s one bardzo wane.

         Do tlumaczenia mona wykorzysta tryb PO Emacsa, program Lokalize
         (oparty na KDE) lub Gtranslator (oparty na GNOME) lub jakikolwiek
         inny program, w zalenoci od upodoba tlumacza. Mona nawet uy dobrego
         starego edytora vi, mimo e nie ma on specjalnego trybu ulatwiajcego
         tlumaczenia.

         Aby dowiedzie si czego wicej, stanowczo powinno si przeczyta
         dokumentacj programu gettext, dostpn w pakiecie gettext-doc.

   JAK zamieni t/lumaczenie z powrotem do pliku dokumentacji?
       Po zakoczeniu tlumaczenia zapewne nalealoby wygenerowa przetlumaczone
       dokumenty i rozdystrybuowa je wrod uytkownikow, razem z oryginalnymi
       dokumentami. Aby to zrobi, naley uy programu po4a-translate(1) w ten
       sposob (XX jest kodem jzyka):

         $ po4a-translate -f <format> -m <master.doc> -p <doc.XX.po> -l <XX.doc>

       Jak wczeniej, <format> jest formatem dokumentu master.doc. Jednak tym
       razem plik PO, przekazany w opcji -p, jest czci wejcia - jest to Twoje
       tlumaczenie. Wyjcie jest zapisywane w XX.doc.

       Wicej szczegolow mona znale w <po4a-translate(1)>.

   JAK zaktualizowa t/lumaczenie programem po4a?
       Aby zaktualizowa tlumaczenie, gdy zmieni si oryginalny plik master.doc,
       naley uy po4a-updatepo(1) w nastpujcy sposob:

         $ po4a-updatepo -f <format> -m <nowy_master.doc> -p <stary_doc.XX.po>

       (Wicej szczegolow mona znale w <po4a-updatepo(1)>).

       Oczywicie ta operacja nie spowoduje automagicznego przetlumaczenia
       nowych akapitow oryginalnego dokumentu. Naley rcznie uaktualni plik PO.
       Podobnie naley zaktualizowa tlumaczenie akapitow, ktore si cho troch
       zmienily. Aby mie pewno, e adnego z nich nie ominiesz, zostaly one
       zaznaczone jako "fuzzy" (niepewne) i zanim po4a-translate bdzie mogl
       ich uy, to zaznaczenie musi zosta usunite. Tak jak w przypadku
       pierwszego tlumaczenia najlepiej jest uy ulubionego edytora.

       Kiedy plik PO bdzie znowu aktualny, bez adnych wpisow
       nieprzetlumaczonych lub niepewnych ("fuzzy"), mona wygenerowa
       przetlumaczony plik dokumentacji, tak jak to opisano w poprzedniej
       sekcji.

   JAK skonwertowa istniejce t/lumaczenia do po4a?
       Czsto si zdarzalo, e tlumaczyle dokument rcznie dopoty, dopoki nie
       nastpila wiksza reorganizacja oryginalnego dokumentu master.doc. W tej
       sytuacji, po kilku nieprzyjemnych probach z diffem lub podobnymi
       narzdziami, moesz zechcie skonwertowa dokument do po4a. Oczywicie naley
       go skonwertowa tak, aby nie utraci istniejcych tlumacze. Nie naley si
       obawia, ten przypadek take jest obslugiwany przez po4a i jest nazywany
       procesem przechodzenia do formatu gettext.

       Kluczow kwesti jest to, aby struktura tlumaczonego dokumentu byla taka
       sama jak oryginalu, tak eby narzdzia mogly odpowiednio dopasowa
       zawarto.

       Jeli masz szczcie (tj. struktura obu dokumentow dokladnie do siebie
       pasuje), wszystko zadziala bez adnego problemu i bdzie gotowe w cigu
       paru sekund. W przeciwnym razie moesz zrozumie dlaczego ten proces ma
       tak brzydk nazw i przygotuj si na do nieprzyjemn prac. W kadym razie,
       pamitaj, e jest to cena za komfort, ktory poniej dostarczy po4a. Dobre
       w tym wszystkim jest to, e trzeba to zrobi tylko raz.

       Nie bd si dlugo nad tym rozwodzil. Aby ulatwi proces, wane jest
       znalezienie dokladnie tej wersji oryginalu, ktora byla przetlumaczona.
       Najlepiej, jeli zanotowale sobie wersj z CVS-u dokumentu uytego do
       tlumaczenia i jej nie modyfikowale w procesie tlumaczenia, tak e moesz
       jej teraz uy.

       Nie zadziala to dobrze, jeli uyje si uaktualnionego tekstu oryginalu ze
       starym tlumaczeniem. Pozostaje to moliwe, ale jest to trudniejsze i
       naprawd powinno si tego unika, gdy tylko jest to moliwe. Jeeli nie
       udalo Ci si znale ponownie starego oryginalu, to najlepszym rozwizaniem
       jest znalezienie kogo, kto przeprowadzi za Ciebie proces przechodzenia
       na format gettext (ale, prosz, niech nie bd to ja ;).

       By moe zbytnio w tym momencie dramatyzuj. Jednak nawet, gdy proces si
       nie udaje, pozostaje mimo wszystko szybsz drog ni tlumaczenie
       wszystkiego od nowa. Udalo mi si przepuci przez ten proces francuskie
       tlumaczenie dokumentacji Perla w cigu jednego dnia, nawet wtedy, gdy
       wszystko szlo le. Bylo to ponad dwa megabajty tekstu, ktorego
       tlumaczenie od nowa trwaloby miesicami lub dluej.

       Prosz najpierw pozwoli mi wyjani podstawy tej procedury, a potem powroc
       do wskazowek, co zrobi, gdy proces si nie udaje. Dla lepszego
       zrozumienia, ponownie uyjemy powyszego przykladu.

       Jeeli jest dostpny stary plik master.doc z odpowiadajcymi mu
       tlumaczeniami XX.doc, przechodzenie do formatu gettext mona zrobi
       bezporednio do pliku doc.XX.po bez rcznego tlumaczenia pliku
       t/lumaczenie.pot:

        $ po4a-gettextize -f <format> -m <stary_oryginal.doc> -l <XX.doc> -p <doc.XX.po>

       Jeli masz szczcie, to to wszystko. Stare tlumaczenia zostaly
       skonwertowane do po4a i mona od razu zacz ich aktualizowanie. Naley
       tylko trzymajc si procedury opisanej kilka sekcji wczeniej,
       zsynchronizowa plik PO z najnowszym oryginalnym dokumentem i
       odpowiednio zaktualizowa tlumaczenia.

       Prosz zauway, e nawet jeli wydaje si, e wszystko zadzialalo poprawnie,
       moe si okaza, e jednak wystpily bldy podczas tego procesu. Po4a nie
       rozumie przetwarzanych tekstow, wic nie moe by by pewne, e tlumaczenia
       s poprawnie przypisane do oryginalow. Dlatego wszystkie komunikaty s
       oznaczone jako "fuzzy" (niepewne). Przed usuniciem tych znacznikow,
       prosz uwanie sprawdzi kade tlumaczenie.

       Bardzo czsto struktury dokumentow nie pasuj dokladnie do siebie, przez
       co po4a-gettextize nie moe poprawnie wykona swojego zadania. W tym
       punkcie gra toczy si o to, aby tak pozmienia pliki, aby ich cholerne
       struktury sobie odpowiadaly.

       Pomocne moe by przeczytanie poniej sekcji Proces przekszta/lcania do
       formatu gettext: jak to dzia/la?. Zrozumienie wewntrznych procesow pomoe
       wykona zadanie. Plusem jest to, e w razie niepowodzenia,
       po4a-gettextize glono powie, co poszlo le, umoliwiajc poznanie
       komunikatow, ktore do siebie nie pasowaly, ich pozycj w tekcie i typ
       kadego z nich. Co wicej, plik PO wygenerowany do tej pory, bdzie
       zachowany jako gettextization.failed.po.

       -   Naley usun wszystkie dodatkowe czci tlumaczenia, takie jak sekcja,
           w ktorej podano nazwisko tlumacza i podzikowania dla wszystkich
           ludzi, ktorzy pomagali przy tlumaczeniu. Poniej takie czci bdzie
           mona z powrotem doda, uywajc zalcznikow, opisanych w nastpnym
           rozdziale.

       -   Nie wahaj si edytowa zarowno pliku oryginalnego, jak i jego
           tlumaczenia. Najwaniejsz rzecz jest otrzymanie pliku PO. Potem
           bdzie mona go zaktualizowa. Edytowanie tlumacze powinno by jednak
           preferowane, poniewa uproci to pewne rzeczy po zakoczeniu si
           procesu przeksztalcania na format gettext.

       -   Jeli jest taka potrzeba, naley usun kilka czci oryginalnego
           dokumentu, ktore nie s przetlumaczone. Poniej podczas
           synchronizowania PO z dokumentem czci te si pojawi same.

       -   Jeli w niewielkim stopniu zmienile struktur dokumentu (polczenie
           dwoch akapitow, albo podzielenie innego akapitu), wycofaj te
           zmiany. Jeli te zmiany mialy zwizek z problemami wystpujcym w
           oryginalnym dokumencie, powiniene poinformowa o nich jego autora.
           Korzyci z poprawienie ich tylko w Twoim tlumaczeniu bdzie miala
           tyko cz spolecznoci. Co wicej, takie poprawki nie s moliwe, gdy si
           uywa po4a.

       -   Czasami zawartoci akapitow si zgadzaj, ale ich typy nie.
           Poprawienie tego zaley od formatu. W formatach POD i man, czsto
           bierze si to z tego, e jeden z tych dwoch akapitow zawiera lini
           zaczynajc si od bialego znaku, a drugi - nie. W tych formatach
           tekst takich akapitow nie moe by zawijany i dlatego wystpuje
           niezgodno typow. Rozwizaniem jest usunicie spacji. Moe to by take
           literowka w nazwie elementu.

           Podobnie, dwa akapity mog zosta scalone razem w formacie POD, jeeli
           rozdzielajca linia zawiera spacje lub kiedy brakuje pustej linii
           przed lini ==item i zawartoci tego elementu.

       -   Czasami wystpuje rozsynchronizowanie midzy plikami i tlumaczenie
           jest przypisane do zlego akapitu oryginalu. Jest to oznaka, e w
           rzeczywistoci problem ley w plikach. Prosz znale w
           gettextization.failed.po miejsce, gdzie zaczyna si
           rozsynchronizowanie, a nastpnie poprawi w tym miejscu pliki
           wejciowe.

       -   Czasami moe si wydawa, e po4a zjadlo jak cz tekstu albo z
           oryginalu, albo z tlumaczenia. gettextization.failed.po wskazuje, e
           oba pliki dokladnie do siebie pasowaly, a przetwarzanie koczy si
           bldem poniewa nastpila proba dopasowania jakiego akapitu do akapitu
           po (lub przed) tym wlaciwym, tak jakby ten wlaciwy si ulotnil. Mona
           tylko kl na po4a, tak jak ja kllem, gdy mi si to zdarzylo po raz
           pierwszy. Serio.

           Ta nieszczliwa sytuacja zdarza si, kiedy ten sam akapit jest
           powtorzony w dokumencie. W tym przypadku nie jest tworzony nowy
           wpis w pliku PO, ale dodawane jest tylko nowe odwolanie do ju
           istniejcego wpisu.

           Tak wic, kiedy ten sam akapit pojawia si dwa razy w oryginalnym
           dokumencie, ale nie jest przetlumaczony w dokladnie ten sam sposob,
           mona mie wraenie, e ten akapit oryginalu zniknl. Wystarczy usun
           nowe tlumaczenie. Jeli preferowalby usunicie pierwszego z tych
           tlumacze, bo drugie jest lepsze, po prostu przenie drugie
           tlumaczenie w miejsce pierwszego.

           Odwrotnie, jeli dwa podobne, ale jednak rone, akapity byly
           przetlumaczone dokladnie tak samo, to jeden akapit tlumaczenia
           zniknie. Rozwizaniem jest dodanie glupiego tekstu do oryginalnego
           akapitu (takiego jak "roni si"). Nie trzeba si tego ba, takie
           rzeczy znikn podczas synchronizacji, a kiedy taki tekst jest
           wystarczajco krotki, gettext dopasuje Twoje tlumaczenie do
           istniejcego tekstu (oznaczajc je jako niepewne ["fuzzy"], czym nie
           powinno si przejmowa, gdy wszystkie komunikaty s tak oznaczone
           zaraz po procesie przeksztalcania na format gettext).

       Mamy nadziej, e te porady pomog w procesie przeksztalcania do formatu
       gettext i w otrzymaniu pliku PO. Mona teraz ten plik zsynchronizowa i
       zacz go tlumaczy. Prosz zauway, e w wypadku dlugich plikow, pierwsza
       synchronizacja moe zaj duo czasu.

       Na przyklad, pierwsze wykonanie po4a-updatepo na francuskim tlumaczeniu
       dokumentacji Perla (plik PO o rozmiarze 5.5 Mb) zajlo okolo dwoch dni
       na komputerze 1Ghz G5. Tak, 48 godzin. Ale kolejne zajmuj tylko
       kilkanacie sekund na moim starym laptopie. Dzieje si tak, poniewa na
       samym pocztku wikszo msgid pliku PO nie pasuje do adnego msgid w pliku
       POT. Wymusza to na programie gettext wyszukiwanie najbardziej zblionego
       msgid, uywajc kosztownego algorytmu bliskoci lacuchow znakow.

   JAK doda dodatkowy tekst do t/lumacze (np. nazwisko t/lumacza)?
       Z powodu rozwiza stosowanych przez gettext, zrobienie tego moe by
       trudniejsze w po4a ni bylo wczeniej, kiedy to plik byl po prostu rcznie
       edytowany. Jednak pozostaje to moliwe, dziki tak zwanym za/lcznikom.

       Dla lepszego zrozumienia mona przyj, e zalczniki s rodzajem lat (patch)
       aplikowanych do przetlumaczonego dokumentu po zakoczeniu przetwarzania.
       Roni si one od zwyklych lat (maj tylko jedn lini kontekstu, ktora moe
       zawiera wyraenie regularne Perla, i mog tylko dodawa nowy tekst bez
       usuwania czegokolwiek), ale funkcjonalno jest taka sama.

       Celem jest danie tlumaczowi moliwoci dolczenie do dokumentu dodatkowej
       zawartoci, ktora nie jest tlumaczeniem oryginalnego dokumentu.
       Najczciej uywany jest do dodawania sekcji dotyczcej samego tlumaczenia,
       wypisania wspolpracownikow lub podania sposobu zglaszania bldow
       znalezionych w tlumaczeniu.

       Zalcznik musi by podany jako osobny plik, ktorego pierwsza linia
       zawiera naglowek okrelajcy, gdzie naley umieci tekst zalcznika. Reszta
       pliku zalcznika bdzie umieszczona bez zmian w okrelonej pozycji
       wynikowego dokumentu.

       Skladnia naglowka jest calkiem sztywna: musi zaczyna si od tekstu
       PO4A-HEADER: poprzedzajcego rozdzielon rednikami (;) list pol
       klucz=warto. Spacje S istotne. Prosz zauway, e nie mona uy rednikow (;)
       w wartoci, a ich cytowanie za pomoc odwrotnego ukonika nie pomaga.

       Tak, brzmi to strasznie, ale ponisze przyklady powinny pomoc w
       napisaniu odpowiedniej linii naglowka. Aby zilustrowa dyskusj, zalomy,
       e chcemy doda sekcj "O tlumaczeniu" zaraz po sekcji "O dokumencie".

       Kilka moliwych kluczy naglowka:

       position (obowizkowe)
           wyraenie regularne. Zalcznik bdzie umieszczony w pobliu linii
           pasujcej do wyraenia regularnego. Prosz zauway, e mowimy tutaj o
           dokumencie przetlumaczonym, a nie o oryginale. Jeli wicej ni jedna
           linia pasuje do tego wyraenia, dodawanie zalcznika si nie
           powiedzie. Istotnie, lepiej jest zglosi bld ni wstawi zalcznik w
           nieodpowiednie miejsc.

           T lini bdziemy dalej nazywa punktem pozycji. Punkt, w ktorym
           zalcznik jest dodawany nazwiemy punktem wstawienia. Te dwa punkty s
           blisko siebie, ale nie s sobie rowne. Na przyklad, aby doda now
           sekcj latwiej zaczepi punkt pozycji na tytule poprzedniej sekcji i
           wytlumaczy programowi po4a, gdzie ta sekcja si koczy (naley pamita,
           e punkt pozycji jest podany przez wyraenie regularne, ktore powinno
           dopasowywa si do pojedynczej linii).

           Zaleno miejsca punktu wstawienia w stosunku do punkty pozycji jest
           okrelana przez pola mode, beginboundary i endboundary, opisane
           poniej.

           W naszym przypadku byloby to:

                position=<title>O dokumencie</title>

       mode (obowizkowe)
           Moe by to jeden z nastpujcych lacuchow znakow: before (= przed) lub
           after (= po), okrelajcych pozycj dodatku w stosunku do punktu
           pozycji.

           Poniewa chcemy now sekcj umieci pod t, ktor wyszukalimy, mamy:

                mode=after

       beginboundary (uywany, gdy mode=after i obowizkowy w tym wypadku)
       endboundary (jak wyej)
           wyraenie regularne pasujce do koca sekcji, po ktorej jest dodawany
           zalcznik.

           W trybie after punkt wstawienia jest za punktem pozycji, ale nie
           bezporednio za! Jest on umieszczony na kocu sekcji zaczynajcej si w
           punkcie pozycji, czyli za albo przed lini pasujc do argumentu
           ???boundary w zalenoci od tego, czy bylo uyte beginboundary, czy
           endboundary.

           W rozpatrywanym przypadku moemy wybra wskazanie koca dopasowywanej
           sekcji, dodajc:

              endboundary=</section>

           albo moemy wskaza pocztek kolejnej sekcji w nastpujcy sposob:

              beginboundary=<section>

           W obu wypadkach zalcznik bdzie umieszczony po </section>, a przed
           <section>. Ten pierwszy sposob dziala lepiej, poniewa zadziala
           nawet wtedy, gdy dokument zostanie zreorganizowany.

           Obie formy istniej poniewa formaty dokumentacji s rone. Niektore z
           nich zawieraj znacznik koca sekcji (tak jak </section>, ktorej
           wlanie uylimy), a inne (np. man) tego koca nie oznaczaj w aden
           szczegolny sposob. W pierwszym przypadku boundary powinno odpowiada
           kocowi sekcji, tak e punkt wstawienia nastpuje po niej. W drugim
           przypadku boundary powinno pasowa do pocztku nastpnej sekcji, a
           punkt wstawienia powinien by umieszczony zaraz przed ni.

       Moe si to wydawa niejasne, nastpne przyklady powinny co nieco
       wyklarowa.

       Podsumowujc przyklady podane do tej pory: aby doda sekcj "O
       tlumaczeniu" po sekcji "O dokumencie" w dokumencie SGML, naley uy
       jednej z poniszych linii naglowka:
          PO4A-HEADER: mode=after; position=O dokumencie; endboundary=</section>
          PO4A-HEADER: mode=after; position=O dokumencie; beginboundary=<section>

       Aby doda co po nastpujcej sekcji nroff:
           .SH "AUTORZY"

         powinno si ustawi positon pasujce do tej linii oraz beginboundary
         pasujce do pocztku nastpnej sekcji (tj. ^\.SH). Zalcznik zostanie
         dodany po punkcie pozycji i zaraz przed pierwsz lini pasujc do
         beginboundary. Czyli:

          PO4A-HEADER:mode=after;position=AUTORZY;beginboundary=\.SH

       Aby zamiast dodawa cal sekcj, doda co do jakiej sekcji (np. po
       "Copyright Big Dude"), trzeba poda position pasujce do tej linii i
       beginboundary pasujce do jakiejkolwiek linii.
          PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

       Aby doda co na kocu dokumentu, naley poda position pasujce do
       jakiejkolwiek linii pliku (ale tylko jednej linii. Po4a nie przetworzy
       tego, jeli linia nie bdzie unikatowa) i poda endboundary nie pasujce do
       niczego. Nie naley uywa tutaj prostych tekstow jak "EOF", tylko takich,
       ktore maj male szanse pojawienia si w dokumencie.
          PO4A-HEADER:mode=after;position=<title>O dokumencie</title>;beginboundary=NieistniejaLiniaPo4a

       W kadym wypadku naley pamita, e s to wyraenia regularne. Na przyklad,
       aby dopasowa koniec sekcji nroff, koczcej si lini

         .fi

       nie naley uywa .fi jako endboundary, poniewa bdzie on pasowal do "the[
       fi]le" co raczej nie jest tym, czego mona by oczekiwa. Poprawnym
       endboundary w tym przypadku jest ^\.fi$.

       Jeli zalcznik nie trafil tam, gdzie powinien, sprobuj przekaza
       narzdziom po4a argument -vv, ktory powinien pomoc wyjani co si dzieje
       podczas dodawania zalcznika.

       Bardziej szczeg'o/lowy przyk/lad

       Oryginalny dokument (w formacie POD):

        |=head1 NAZWA
        |
        |dummy - fikcyjny program
        |
        |=head1 AUTOR
        |
        |ja

       Wtedy nastpujcy dodatek spowoduje dodanie sekcji (w jzyku francuskim)
       na koniec tego pliku (w jz. francuskim "TRADUCTEUR" oznacza "TLUMACZ",
       a "moi" znaczy "ja")

        |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
        |
        |=head1 TRADUCTEUR
        |
        |moi

       Aby umieci dodatek przed sekcj AUTOR, naley uy nastpujcego naglowka:

        PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

       To dziala, poniewa nastpn lini pasujc do beginboundary /^=head1/ po
       sekcji "NAZWA" (przetlumaczonej na francuskie "NOM") jest linia
       opisujca autorow. Tak wic zalcznik zostanie umieszczony pomidzy obiema
       sekcjami.

   JAK to wszystko zrobi, wywo/lujc tylko jeden program?
       Uytkownicy udowodnili, e takie uycie po4a jest naraone na bldy, poniewa
       naley we wlaciwym porzdku wywola dwa rone programy (po4a-updatepo, a
       nastpnie po4a-translate), z ktorych kady wymaga podania wicej ni 3
       argumentow. Co wicej, w tym systemie bylo trudno uy tylko jednego pliku
       PO dla wszystkich dokumentow, kiedy uyto wicej ni jednego formatu.

       Program po4a(1) zaprojektowano, aby rozwiza te trudnoci. Kiedy tylko
       projekt zostanie skonwertowany do tego systemu, mona napisa prosty plik
       konfiguracyjny opisujcy miejsce poloenia plikow tlumacze (PO i POT) i
       oryginalnych dokumentow, ich formaty oraz miejsce, gdzie powinny trafia
       przetlumaczone dokumenty.

       Uruchomienie po4a(1) na tym pliku spowoduje zsynchronizowanie
       wszystkich plikow PO z oryginalnym dokumentem, tak eby przetlumaczony
       dokument zostal poprawnie wygenerowany. Oczywicie naley ten program
       wywola dwa razy: raz przed edytowaniem pliku PO, eby go zaktualizowa, i
       raz po jego edycji, aby otrzyma calkowicie aktualny przetlumaczony
       dokument . Tylko e potrzebujesz zapamita tylko jedn komend linii
       polece.

   JAK dostosowa po4a do w/lasnych potrzeb?
       Moduly po4a maj opcje (okrelane przez -o opcja), ktorych mona uy, eby
       zmieni zachowanie modulow.

       Moliwe jest take dostosowywanie modulu oraz modulu nowego / pochodnego
       / zmodyfikowanego przez umieszczenie go w katalogu lib/Locale/Po4a/ i
       dodanie lib do cieki okrelonej w zmiennej rodowiskowej PERLLIB lub
       PERL5LIB. Na przyklad:

          PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg

       Uwaga: rzeczywista nazwa katalogu lib nie jest istotna.

Jak to dzia/la?

       Ten rozdzial zawiera krotki opis wewntrznych mechanizmow po4a, tak e
       bdziesz mial wicej odwagi, aby pomoc nam w jego tworzeniu i
       udoskonalaniu. Moe take Ci pomoc w zrozumieniu, dlaczego nie dziala
       tak, jak by tego oczekiwal, oraz jak rozwiza napotkane problemy.

   Jak wygldaj szczeg'o/ly?
       Architektura po4a jest zorientowana obiektowo (w Perlu, czy to nie
       eleganckie?). Wspolny przodek wszystkich klas parserow zwie si
       TransTractor. Ta dziwna nazwa wzila si std, e jest on odpowiedzialny za
       tlumaczenie dokumentu i wydobywanie komunikatow.

       Bardziej formalnie mowic, pobiera dokument do przetlumaczenia oraz plik
       PO zawierajcy tlumaczenia uywany jako wejcie podczas tworzenia dwoch
       oddzielnych plikow wyjciowych: innego pliku PO (wyniku wyodrbniania
       komunikatow z dokumentu wejciowego) oraz przetlumaczonego dokumentu
       (majcego tak sam struktur jak plik wejciowy, ale ze wszystkimi
       komunikatami zamienionymi na zawarto wejciowego pliku PO). Poniej jest
       graficzne przedstawienie tego procesu:

          Dokument wejciowy -\                          /-> Dokument wyjciowy
                               \      TransTractor::    /    (przetlumaczony)
                                +-->--   parse()  --- -+
                               /                        \
          Wejciowy PO -------/                          \---> Wyjciowy PO
                                                               (wyodrbniony)

       Ta mala ko jest podstaw calej architektury po4a. Jeli pominiesz
       wejciowy plik PO i dokument wyjciowy, otrzymasz po4a-gettextize. Jeli
       podasz oba pliki wejciowe i zlekcewaysz wyjciowy plik PO, otrzymasz
       po4a-translate.

       TransTractor::parse() jest wirtualn funkcj zaimplementowan w kadym
       module. Tutaj podano prosty przyklad, eby zobrazowa jej dzialanie.
       Przetwarza list akapitow, z ktorych kady zaczyna si od <p>.

         1 sub parse {
         2   PARAGRAPH: while (1) {
         3     $my ($paragraph,$pararef,$line,$lref)=("","","","");
         4     $my $first=1;
         5     while (($line,$lref)=$document->shiftline() && defined($line)) {
         6       if ($line =~ m/<p>/ && !$first--; ) {
         7         $document->unshiftline($line,$lref);
         8
         9         $paragraph =~ s/^<p>//s;
        10         $document->pushline("<p>".$document->translate($paragraph,$pararef));
        11
        12         next PARAGRAPH;
        13       } else {
        14         $paragraph .= $line;
        15         $pararef = $lref unless(length($pararef));
        16       }
        17     }
        18     return; # Nie otrzymano linii? Koniec pliku wejciowego.
        19   }
        20 }

       W linii 6. po raz drugi napotkalimy <p>. Oznacza to kolejny akapit.
       Powinnimy dlatego zwroci otrzyman lini do oryginalnego dokumentu (linia
       7.), a na wyjcie doloy akapit zbudowany do tej pory. Po usuniciu z
       niego pocztkowego <p> w linii 9., dokladamy ten element polczony z
       tlumaczeniem reszty akapitu.

       Funkcja translate() jest bardzo fajna (cool ;)). Dodaje swoje argumenty
       na koniec wynikowego pliku PO (ekstrakcja) i zwraca ich tlumaczenie,
       znalezione w wejciowym pliku PO (tlumaczenie). Poniewa jest uywana jako
       cz argumentu pushline(), tlumaczenie lduje w wynikowym dokumencie.

       Czy to nie jest fajne? Jest moliwe zbudowanie kompletnego modulu po4a w
       mniej ni 20 liniach, jeeli tylko format jest wystarczajco prosty...

       Wicej informacji o tym mona znale w Locale::Po4a::TransTractor(3pm).

   Proces przekszta/lcania do formatu gettext: jak to dzia/la?
       Idea jest nastpujca: pobranie oryginalnego dokumentu i jego tlumaczenia
       i powiedzenie, e n-ty komunikat wyodrbniony z tlumaczenia jest
       tlumaczeniem n-tego komunikatu wyodrbnionego z oryginalu. Aby to
       zadzialalo, oba pliki musz mie dokladnie tak sam struktur. Na przyklad,
       jeeli pliki maj ponisz struktur, to jest raczej niemoliwe, by 4.
       komunikat tlumaczenia (typu "rozdzial") byl tlumaczeniem 4. komunikatu
       oryginalu (typu "akapit").

          Oryginal         Tlumaczenie

          rozdzial          rozdzial
             akapit            akapit
             akapit            akapit
             akapit         rozdzial
          rozdzial             akapit
             akapit            akapit

       Aby to osign, parsery po4a s uywane zarowno na pliku oryginalu, jak i
       tlumaczenia, eby utworzy pliki PO, a nastpnie jest budowany z nich
       trzeci plik PO zawierajcy komunikaty z drugiego pliku jako tlumaczenia
       komunikatow z pierwszego. Aby sprawdzi, e komunikaty, ktore ze sob
       lczymy, s rzeczywicie odpowiadajcymi sobie tlumaczeniami, parsesy
       dokumentow w po4a powinny umieszcza informacje o typach skladniowych
       komunikatow wyodrbnionych z dokumentu (wszystkie istniejce to robi,
       Twoj te powinien). Nastpnie te informacje s uywane do sprawdzenia, e
       oba dokumenty maj t sam skladni. W poprzednim przykladzie pozwolilo nam
       to wykry, e 4. komunikat jest w jednym przypadku akapitem, a w drugim -
       tytulem rozdzialu i zglosi problem.

       Teoretycznie byloby moliwe zsynchronizowanie plikow po wykryciu
       problemu (tak, jak to robi diff). Niestety, nie jest jasne, co zrobi z
       komunikatami, ktore nie wystpujc w jednym z plikow, byly przyczyn
       rozsynchronizowania. Dlatego obecna implementacja nie stara si
       synchronizowa plikow i zglasza bld, kiedy co poszlo le, wymagajc od
       uytkownika rcznego zmodyfikowania plikow w celu rozwizania problemu.

       Nawet z tymi zabezpieczeniami, rzeczy mog le si potoczy. Wlanie dlatego
       wszystkie tlumaczenia odgadnite w ten sposob s zaznaczane jako niepewne
       ("fuzzy"), aby tlumacz je przejrzal i sprawdzil.

   Za/lcznik: Jak to dzia/la?
       Hmm, to calkiem proste. Tlumaczony dokument nie jest bezporednio
       zapisywany na dysk, ale trzymany w pamici, dopoki wszystkie zalczniki
       nie zostan dodane. Wykorzystane algorytmy s raczej proste. Szukamy
       linii pasujcej do wyraenia regularnego okrelajcego pozycj i dodajemy
       zalcznik przed t lin, jeli tryb = before. Jeli nie jestemy w tym
       trybie, to szukamy nastpnej linii pasujcej do ograniczenia i wstawiamy
       zalcznik po tej linii, jeli jest to endboundary, lub przed ni, jeli
       jest to beginboundary.

FAQ

       Ten rozdzial zawiera odpowiedzi na czsto zadawane pytania. Tak naprawd,
       wikszo tych pyta moe by sformulowanych jako "Dlaczego po4a zostalo
       zaprojektowane tak, a nie inaczej?". Jeli wydaje Ci si, e po4a nie jest
       wlaciwym narzdziem do tlumaczenia dokumentacji, powiniene rozway
       przeczytanie tego rozdzialu. Jeli nie znajdziesz w nim odpowiedzi na
       swoje pytanie, prosimy si z nami skontaktowa poprzez list dyskusyjn
       <po4a-devel@lists.alioth.debian.org>. Uwielbiamy zna opinie
       uytkownikow.

   Dlaczego trzeba t/lumaczy kady akapit osobno?
       Tak, w po4a, kady akapit jest tlumaczony osobno (w zasadzie, to kady
       modul o tym decyduje, ale wszystkie istniejce moduly tak robi i Twoj
       take powinien). S dwie glowne przyczyny takiego rozwizania:

       o Kiedy techniczne czci dokumentu s ukryte, tlumacz nie moe w nich
         zrobi balaganu. Im mniej znacznikow pokazujemy tlumaczowi, tym mniej
         bldow moe popelni.

       o Przycinanie dokumentu pomaga odizolowa zmiany w oryginalnym
         dokumencie. Kiedy oryginal zostanie zmieniony, ten proces uproci
         wyszukanie czci tlumacze potrzebujcych aktualizacji.

       Nawet biorc pod uwag te plusy, niektorym ludziom nie podoba si osobne
       tlumaczenie kadego akapitu. Postaram si odpowiedzie na ich obawy:

       o Takie podejcie sprawdzilo si w projekcie KDE, pozwalajc temu
         zespolowi na wyprodukowanie znacznej iloci przetlumaczonej i
         aktualnej dokumentacji.

       o Tlumacze mog wci uywa kontekstu tlumaczenia, poniewa wszystkie
         komunikaty w pliku PO s w takiej samej kolejnoci jak w oryginalnym
         dokumencie. Tlumaczenie sekwencyjne jest podobne, niezalenie, czy
         uywa si po4a czy nie. I w kadym wypadku najlepszym sposobem
         otrzymania kontekstu pozostaje skonwertowanie dokumentu do formatu
         dokumentu drukowanego, poniewa formaty rodlowe tekstu mog nie by zbyt
         czytelne.

       o Takie podejcie jest uywany przez profesjonalnych tlumaczy. Zgadzam
         si, maj oni troch inne cele ni tlumacze oprogramowania open-source.
         Na przyklad moliwo latwego zarzdzania tlumaczeniem jest czsto dla
         nich mniej istotna, poniewa zawarto rzadko si zmienia.

   Dlaczego nie podzieli na zdania (lub mniejsze czci)?
       Profesjonalne narzdzie tlumaczy czasami dziel dokument na poszczegolne
       zdania, aby zmaksymalizowa wykorzystanie wczeniejszych tlumacze i
       zwikszy szybko tlumaczenia. Problemem jest jednak to, e w zalenoci od
       kontekstu to samo zdanie moe mie kilka tlumacze.

       Akapity s z definicji dlusze ni zdania. Jeeli w dwoch dokumentach ten
       sam akapit wystpuje, to moemy zaloy, e jego znaczenie (i tlumaczenie)
       jest takie samo, niezalenie od kontekstu.

       Dzielenie na czci mniejsze ni zdania byloby czym bardzo niedobrym. Za
       duo miejsca by zajlo napisanie tu wyjanienie dlaczego, ale
       zainteresowany czytelnik moe na przyklad przeczyta stron podrcznika
       Locale::Maketext::TPJ13(3pm) (pochodzc z dokumentacji Perla). W
       skrocie, kady jzyk ma okrelone zasady skladniowe i nie istnieje taki
       sposob budowania zda przez lczenie ich czci, ktory by dzialal dla
       wszystkich istniejcych jzykow (lub nawet dla tylko 5 czy 10
       najpopularniejszych).

   Dlaczego nie umieci orygina/lu jako komentarza do t/lumaczenia (lub w inny
       spos'ob)?
       Na pierwszy rzut oka gettext nie wydaje si by przeznaczony do
       wszystkich rodzajow tlumacze. Na przyklad nie wydawal si on by
       przystosowany do debconfa, interfejsu wszystkich pakietow Debiana
       uywanego do interakcji z uytkownikiem podczas instalacji. W tym
       przypadku teksty do tlumaczenia byly calkiem krotkie (tuzin linii dla
       kadego pakietu) i bylo trudno umieci tlumaczenie w specjalnym pliku
       poniewa musialo by dostpne jeszcze przed zainstalowaniem pakietu.

       To dlatego opiekun debconfa zdecydowal zaimplementowa inne rozwizanie,
       w ktorym tlumaczenia s umieszczane w tym samym pliku, co oryginal. Jest
       to pocigajce. Kto moglby nawet chcie co takiego zrobi dla XML-a na
       przyklad. Moglby on wyglda tak:

        <section>
         <title lang="en">My title</title>
         <title lang="fr">Mon titre</title>

         <para>
          <text lang="en">My text.</text>
          <text lang="fr">Mon texte.</text>
         </para>
        </section>

       Jednak bylo to na tyle problematyczne, e obecnie jest uywane rozwizanie
       oparte na plikach PO. Tylko oryginalny tekst moe by edytowany w pliku,
       a tlumaczenia musz si pojawi w plikach PO, wycignitych z glownego
       szablonu (lczonych z powrotem w czasie kompilacji pakietu). Ten stary
       system jest potpiany z kilku powodow:

       o   problemy w zarzdzaniu

           Jeeli kilku tlumaczy dostarczy lat w tym samym czasie, bdzie trudno
           polczy te laty wszystkie razem.

           Jak wykry te zmiany w oryginale, ktore musz by zastosowane w
           tlumaczeniach? Aby uy programu diff, trzeba bylo zanotowa wersj
           oryginalu, ktora zostala przetlumaczone. Tj. potrzebujesz pliku PO
           w Twoim pliku.

       o   problemy z kodowaniem znakow

           Rozwizanie to jest dobre tylko dla europejskich jzykow, jednak
           wprowadzenie koreaskiego, rosyjskiego lub arabskiego bardzo
           wszystko komplikuje. Rozwizaniem moglby by UTF, jednak wci jest z
           nim kilka problemow.

           Co wicej takie problemy s trudne do wychwycenia (tj. tylko
           Koreaczycy zauwa e kodowanie znakow w koreaskim tekcie jest zepsute
           [bo tlumacz byl Rosjaninem]).

       gettext rozwizuje wszystkie te problemy razem.

   Ale gettext nie zosta/l zaprojektowany do takiego uycia!
       To prawda, ale do tej pory nikt nie znalazl lepszego rozwizania. Jedyn
       znan alternatyw jest rczne tlumaczenie ze wszystkimi problemami w jego
       zarzdzaniu.

   Co z innymi narzdziami do t/lumacze dokumentacji wykorzystujcymi gettext?
       O ile mi wiadomo, s tylko dwa takie:

       poxml
           Jest to narzdzie rozwijane przez ludzi z KDE obslugujce format
           DocBook XML. O ile mi wiadomo, byl to pierwszy program wycigajcy
           lacuchy znakow do przetlumaczenia z dokumentacji do plikow PO i
           wstawiajcy je z powrotem po przetlumaczeniu.

           Moe on obslugiwa tylko XML i czciowo DTD. Jestem bardzo
           niezadowolony z obslugi list, ktore zostaj umieszczone w jednym
           wielkim msgid. Kiedy lista staje si dluga, sprawa si komplikuje.

       po-debiandoc
           Program utworzony przez Denisa Barbiera jest poprzednikiem modulu
           SGML po4a, ktory w mniejszym bd wikszym stopniu go zastpuje, czynic
           przestarzalym. Zgodnie ze sw nazw obsluguje tylko DebianDoc DTD,
           ktory jest DTD mniej lub bardziej przestarzalym.

       Najwiksz zalet po4a nad nimi jest latwo umieszczania dodatkowej
       zawartoci (co jest nawet gorsze tutaj) i przejcia na format gettext.

   Przekazywanie deweloperom wiedzy o t/lumaczeniu
       Probujc tlumaczy dokumentacj lub programy mona napotka trzy rodzaje
       problemow: lingwistyczne (nie kady mowi dwoma jzykami), techniczne (to
       dlatego istnieje po4a) i ludzkie. Nie wszyscy deweloperzy rozumiej
       potrzeb tlumacze. Nawet majc dobre chci, mog ignorowa potrzeb
       upraszczania pracy tlumaczy. Aby w tym pomoc, po4a dostarcza wiele
       dokumentacji, do ktorej mona si odnosi.

       Innym wanym punktem jest to, e kady plik z tlumaczeniem zaczyna si od
       krotkiego komentarza okrelajcego, czym jest ten plik i jak go uy.
       Powinno to pomoc deweloperom, zalanym tonami plikow w ronych jzykach,
       ktorych nie znaj, pomoc w poprawnym obslueniu tego.

       W projekcie po4a przetlumaczone dokumenty nie s plikami rodlowymi.
       Poniewa jestemy przyzwyczajeni do tego, e pliki sgml s plikami
       rodlowymi, latwo jest o pomylk. Dlatego wszystkie pliki zawieraj taki
       naglowek:

        |       ****************************************************
        |       *         PLIK WYGENEROWANY, NIE EDYTOWA          *
        |       * TO NIE JEST PLIK RODLOWY, ALE WYNIK KOMPILACJI  *
        |       ****************************************************
        |
        | Ten plik zostal wygenerowany przez po4a-translate(1). Nie przechowuj go
        | (na przyklad w CVS-ie), ale przechowuj plik PO, uyty jako plik rodlowy
        | przez polecenie po4a-translate.
        |
        | Tak naprawd, potraktuj ten plik jako plik binarny, a plik PO jako zwykly
        | plik rodlowy: jeli plik PO zaginie, to bdzie trudniej zachowa aktualno
        | tego tlumaczenia ;)

       Podobnie, to co naley zrobi ze zwyklymi plikami PO programu gettext, to
       skopiowa je do katalogu po/. Ale w przypadku plik'ow zarzdzanych przez
       po4a to nie dzia/la. Najwikszym ryzykiem tutaj jest to, e deweloper
       usunie istniejce tlumaczenia jego programu wraz z tlumaczeniami
       dokumentacji. (Oba nie mog by przechowywane w jednym pliku PO, poniewa
       program wymaga instalacji pliku tlumacze jako pliku mo, podczas gdy
       dokumentacja uywa tlumacze w czasie kompilacji). Dlatego pliki PO
       tworzone przez modul po-debiandoc zawieraj poniszy naglowek:

        #
        #  RADY DLA DEWELOPEROW:
        #    - nie trzeba rcznie edytowa plikow POT i PO.
        #    - ten plik zawiera tlumaczenie Twoich szablonow confiteor.
        #      Nie zastpuj tlumacze Twojego programu tym plikiem !!
        #        (albo tlumacze bd na Ciebie wciekli)
        #
        #  RADY DLA TLUMACZY:
        #    Jeli nie jeste zaznajomiony z formatem PO, warto przeczyta
        #    dokumentacj pakietu gettext, zwlaszcza sekcje powicone
        #    temu formatowi. Na przyklad uruchom:
        #         info -n "(gettext)PO Files"
        #         info -n "(gettext)Heder Centry"
        #
        #    Informacje specyficzne po-debconf s dostpne w
        #            /usr/share/doc/po-debconf/README-trans
        #        lub http://www.debian.org/intl/l10n/po-debconf/README-trans
        #

   PODSUMOWANIE plus'ow i minus'ow rozwizania opartego na gettext
       o Tlumaczenia nie s trzymane wraz z oryginalem, co pozwala w prosty
         sposob wykry, czy tlumaczenia nie s przestarzale.

       o Tlumaczenia s przechowywane w oddzielnych plikach, dziki czemu
         tlumacze ronych jzykow sobie nie przeszkadzaj, zarowno kiedy podsylaj
         swoje tlumaczenia, jak i kiedy zmieniaj kodowanie znakow pliku.

       o Wewntrznie jest oparty na pakiecie gettext (ale po4a oferuje bardzo
         prosty interfejs, tak e nie ma potrzeby poznawania wewntrznych
         mechanizmow, aby go uy). W ten sposob, nie musimy ponownie wymyla
         kola, a poniewa gettext jest szeroko uywany, mamy nadziej, e w
         wikszym lub mniejszym stopniu jest wolny od bldow.

       o Z punktu widzenia kocowego uytkownika nic si nie zmienilo (poza tym,
         e tlumaczenia s lepiej zarzdzane). Wynikowe pliki z dokumentacj s tak
         samo dystrybuowane.

       o Tlumacze nie musz uczy si skladni nowego pliku i mog po prostu uy
         swojego ulubionego edytora plikow PO (jak tryb PO Emasca, Lokalize
         lub Gtranslator).

       o gettext udostpnia prosty sposob otrzymania statystyk o tym, co
         zostalo zrobione, co powinno by przejrzane i zaktualizowane, a co
         jeszcze jest do zrobienia. Przyklady mona znale POD tymi adresami:

          - http://kv-53.narod.ru/kaider1.png
          - http://www.debian.org/intl/l10n/

       Nie wszystko zloto, co si wieci - to podejcie ma take kilka minusow, z
       ktorymi musimy sobie poradzi.

       o Na pierwszy rzut oka zalczniki s... dziwne.

       o Nie mona dostosowywa tlumaczonego tekstu do wlasnych upodoba, na
         przyklad przez podzielenie w danym miejscu na akapity, polczenie
         dwoch innych akapitow w jeden. Jednak w pewnym sensie, jeeli jest
         jaki problem z oryginalem, powinno to zosta zgloszone jako bld.

       o Nawet majc latwy interfejs, wci pozostaje nowym narzdziem, ktorego
         trzeba si uczy.

         Jednym z moich marze jest zintegrowanie w jaki sposob po4a z
         programami Gtranslator lub Lokalize. Kiedy plik SGML jest otwierany,
         komunikaty zostaj automatycznie wycigane. Kiedy jest zamykany,
         przetlumaczony plik jest zapisywany na dysk. Jeli uda nam si zrobi
         modul MS Word (TM) (a przynajmniej RFT), to bd mogli go nawet uywa
         profesjonalni tlumacze.

AUTORZY

        Denis Barbier <barbier,linuxfr.org>
        Martin Quinson (mquinson#debian.org)