Provided by: po4a_0.41-1ubuntu1_all bug

NAZWA

       po4a - narzędzia do tłumaczeń dokumentacji i innych materiałów

Wstęp

       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.

Spis treści

       Dokument jest zorganizowany następująco:

       1. Dlaczego powinno się używać po4a? Jakie są jego zalety?
           Ten rozdział wprowadzenia wyjaśnia motywy i filozofię projektu.
           Jeżeli rozważasz użycie po4a do Twoich tłumaczeń, powinieneś
           najpierw przeczytać ten rozdział.

       2. Jak używać po4a?
           Rozdział ten jest rodzajem podręcznika i próbuje odpowiedzieć na
           pytania użytkowników, pozwalając lepiej zrozumieć cały proces.
           Odpowiada, jak wykonać różne rzeczy w po4a, i służy jako
           wprowadzenie do dokumentacji konkretnych narzędzi.

           JAK zacząć nowe tłumaczenie?
           JAK zamienić tłumaczenie z powrotem do pliku dokumentacji?
           JAK zaktualizować tłumaczenie programem po4a?
           JAK skonwertować istniejące tłumaczenia do po4a?
           JAK dodać dodatkowy tekst do tłumaczeń (np. nazwisko tłumacza)?
           JAK to wszystko zrobić, wywołując tylko jeden program?
           JAK dostosować po4a do własnych potrzeb?
       3. Jak to działa?
           Ten rozdział zawiera krótki opis wewnętrznych mechanizmów po4a, tak
           że będziesz miał więcej odwagi, aby pomóc nam w jego tworzeniu i
           udoskonalaniu. Może także Ci pomóc w zrozumieniu, dlaczego nie
           działa tak, jak byś tego oczekiwał, oraz jak rozwiązać napotkane
           problemy.

       4. FAQ
           Ten rozdział zawiera odpowiedzi na często zadawane pytania. Tak
           naprawdę, większość tych pytań może być sformułowanych jako
           "Dlaczego po4a zostało zaprojektowane tak, a nie inaczej?". Jeśli
           wydaje Ci się, że po4a nie jest właściwym narzędziem do tłumaczenia
           dokumentacji, powinieneś rozważyć przeczytanie tego rozdziału.
           Jeśli 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
           użytkowników.

       5. Specyficzne uwagi o modułach
           Ten rozdział opisuje rzeczy specyficzne dla każdego modułu, z
           punktu widzenia zarówno tłumacza, jak i autora oryginalnego
           dokumentu. Czytając ten rozdział, dowiesz się, kiedy dany moduł
           wykonuje tłumaczenia oraz jakich zasad powinieneś przestrzegać,
           pisząc oryginalny dokument, aby uprościć życie tłumaczom.

           W zasadzie, ta sekcja nie jest częścią tego dokumentu. Zamiast tego
           jest umieszczana w dokumentacji każdego modułu. Pomaga to w
           zapewnieniu aktualności tych informacji, trzymając kod i
           dokumentację razem.

Dlaczego używać po4a? Do czego jest on przydatny?

       Podoba mi się idea wolnego oprogramowania, pozwalającego każdemu na
       dostęp do programów i ich kodów źródłowych. Będąc jednak Francuzem,
       jestem świadomy tego, że licencja programu nie jest jedynym
       ograniczeniem otwartości oprogramowania: nieprzetłumaczone
       oprogramowanie jest bezużyteczne dla ludzi nieznających angielskiego,
       więc ciągle czeka na nas dużo pracy, żeby udostępnić je każdej takiej
       osobie.

       Świadomość tego problemu wśród osób związanych z oprogramowaniem open-
       source ostatnio znacznie wzrosła. Wygraliśmy, jako tłumacze, pierwszą
       bitwę i przekonaliśmy wszystkich o znaczeniu tłumaczeń. Niestety, to
       była ta łatwiejsza część. Teraz musimy wykonać naszą pracę i
       przetłumaczyć wszystkie te rzeczy.

       Właściwie oprogramowanie typu open-source ma dość przyzwoity poziom
       tłumaczeń, dzięki wspaniałemu pakietowi gettext, który ma możliwości
       wyodrębniania z programu komunikatów do przetłumaczenia, przekazywania
       tłumaczom plików w jednolitym formacie i używania wyników ich pracy do
       pokazywania użytkownikowi przetłumaczonych komunikatów w czasie
       działania programu.

       W przypadku dokumentacji sytuacja jest trochę inna. Zbyt często się
       zdarza, że tłumaczony dokument nie jest dostatecznie widoczny (nie jest
       dystrybuowany jako część programu), jest tylko częściowy lub nie jest
       aktualny. Ostatnia sytuacja jest najgorszą z możliwych. Przestarzałe
       tłumaczenie, opisujące stare, już nieistniejące zachowanie programu,
       może być o wiele gorsze dla użytkownika niż brak tłumaczenia w ogóle.

   Problem do rozwiązania
       Tłumaczenie dokumentacji samo w sobie nie jest zbyt trudne. Teksty są
       dużo dłuższe niż komunikaty wyświetlane przez program, więc ich
       tłumaczenie zajmuje trochę więcej czasu, nie wymaga przy tym jednak
       żadnych umiejętności technicznych. Trudniejszą częścią pracy jest
       zarządzanie tłumaczeniem. Wykrywanie części, które się zmieniły i
       powinny być zaktualizowane, jest bardzo trudne, podatne na błędy i
       wysoce nieprzyjemne. Najprawdopodobniej wyjaśnia to, dlaczego tak wiele
       przetłumaczonej dokumentacji nie jest aktualne.

   Odpowiedzi po4a
       Tak więc, celem po4a jest uczynienie tłumaczeń dokumentacji atwymi do
       zarzdzania. Ideą jest wykorzystanie metodologii gettexta na tym nowym
       polu. Tak jak w programie gettext, teksty są wyodrębniane z ich
       oryginalnych miejsc, aby mogły w jednolitym formacie zostać
       zaprezentowane tłumaczowi. Klasyczne narzędzia gettexta pomogą im
       uaktualnić ich pracę, kiedy pojawi się nowa wersja oryginalnego
       dokumentu. W przeciwieństwie zaś do klasycznego modelu gettext,
       tłumaczenia są wstawiane do struktury oryginalnego dokumentu, tak żeby
       mogły być przetwarzane i dystrybuowane w dokładnie taki sam sposób, co
       wersja angielska.

       Dzięki temu stało się łatwiejsze znalezienie do przetłumaczenia
       zmienionych części dokumentu. Innym plusem jest to, że w wypadku
       zasadniczej reorganizacji struktury dokumentu, gdy rozdziały są
       przesuwane, łączone lub dzielone, narzędzia wykonają prawie całą brudną
       robotę. Wyodrębnianie ze struktury dokumentu tekstów do przetłumaczenia
       pozwala tłumaczom nie przejmować się złożonością struktury dokumentu i
       zmniejsza szanse otrzymania dokumentu o niepoprawnej strukturze (choć
       zawsze jest to możliwe).

       W sekcji FAQ poniżej opisano kompletną listę plusów i minusów tego
       rozwiązania.

   Obsługiwane formaty
       Obecnie rozwiązanie to zaimplementowano z sukcesem dla kilku formatów
       tekstu:

       man

       Format starych, dobrych stron podręcznika ekranowego, używanego przez
       wiele programów. Obsługa tego formatu w po4a jest mile widziana,
       ponieważ ten format jest raczej trudny w użyciu i niezbyt przyjazny dla
       nowych użytkowników. Moduł Locale::Po4a::Man(3pm) obsługuje również
       format mdoc,używany przez strony podręcznika systemu BSD (całkiem
       często występujących również pod Linuksem).

       pod

       Jest to format dokumentacji Perla. W ten sposób jest udokumentowany sam
       język i jego rozszerzenia, a także większość istniejących skryptów
       Perla. Łączenie dokumentacji i kodu w jednym pliku, pomaga utrzymywać
       aktualność dokumentacji. Upraszcza to życie programisty, ale niestety,
       nie tłumacza.

       sgml

       Nawet jeśli jest obecnie wypierany przez XML, ten format jest wciąż
       raczej często używany w dokumentach o długości większej niż kilka
       ekranów. Pozwala tworzyć kompletne książki. Aktualizowane tłumaczeń tak
       długich dokumentów może być prawdziwym koszmarem. Program diff bardzo
       często okazuje się bezużyteczny, jeśli zmieni się struktura
       oryginalnego tekstu. Na szczęście, z pomocą może przyjść po4a.

       Obecnie obsługiwane są tylko DTD DebianDoc i docbook, ale dodanie
       obsługi nowego typu jest bardzo proste. Jest nawet możliwe użycie po4a
       z nieznanym DTD SGML bez zmiany kodu - przez podanie wymaganych
       informacji w parametrach linii poleceń. Szczegóły można znaleźć w
       Locale::Po4a::Sgml(3pm).

       TeX / LaTeX

       Format LaTeX jest głównym formatem dokumentacji używanym w publikacjach
       pisanych przez ludzi związanych ze światem wolnego oprogramowania.
       Moduł Locale::Po4a::LaTeX(3pm) był testowany na dokumentacji Pythona,
       książce i kilku prezentacjach.

       texinfo

       Cała dokumentacja GNU jest pisana w tym formacie (i jest to nawet jedno
       z wymagań stawianych projektom , które chcą stać się oficjalnymi
       projektami GNU). Wsparcie dla  Locale::Po4a::Texinfo(3pm) jest wciąż w
       fazie początkowej. Prosimy o zgłaszanie błędów i przesyłanie uwag
       dotyczących brakujących funkcjonalności.

       xml

       XML jest formatem bazowym wielu innych formatów dokumentacji.

       Obecnie po4a obsługuje DocBook DTD. Szczegóły można znaleźć w
       Locale::Po4a::Docbook(3pm).

       inne

       Po4a może także obsługiwać kilka rzadszych lub bardziej
       specjalizowanych formatów, takich jak dokumentacja opcji kompilacji
       jąder 2.4 lub diagramów wyprodukowanych przez narzędzie dia. Dodanie
       nowego formatu jest często bardzo proste, a głównym zadaniem jest
       napisanie parsera tego formatu. Więcej informacji o tym można znaleźć w
       Locale::Po4a::TransTractor(3pm).

   Formaty niewspierane
       Niestety, po4a ciągle nie obsługuje kilku formatów dokumentacji.

       Istnieje cała masa innych formatów, które byśmy chcieli obsługiwać w
       po4a, i nie są to tylko formaty dokumentacji. W zasadzie, naszym celem
       jest wypełnienie wszystkich dziur pozostawionych przez klasyczne
       narzędzia gettext. Obejmuje to opisy pakietów (deb i rpm), pytania
       skryptów instalacyjnych pakietów, logi zmian pakietów i wszystkie
       specjalizowane formaty używane przez programy, jak na przykład
       scenariusze gier lub pliki zasobów wine.

Jak używać po4a?

       Rozdział ten jest rodzajem podręcznika i próbuje odpowiedzieć na
       pytania użytkowników, pozwalając lepiej zrozumieć cały proces.
       Odpowiada, jak wykonać różne rzeczy w po4a, i służy jako wprowadzenie
       do dokumentacji konkretnych narzędzi.

   Graficzne podsumowanie
       Następujący schemat pokazuje poglądowo proces tłumaczenia dokumentacji
       z użyciem po4a. Nie powinno się przejmować jego pozorną złożonością,
       która wzięła się stąd, że pokazaliśmy tutaj cay proces. Po
       skonwertowaniu projektu do po4a, istotna będzie tylko prawa część
       schematu.

       Proszę zauważyć, że master.doc występuje tu jako przykład pliku
       dokumentacji do przetłumaczenia, a tumaczenie.doc jest odpowiadającym
       mu tekstem przetłumaczonym. Rozszerzeniem może być  .pod, .xml lub
       .sgml, zależnie od formatu pliku. Każdą część rysunku omówimy
       szczegółowo w następnych sekcjach.

                                          master.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
       {tłumaczenie}    |            { aktualizacja master.doc }       :
            :           |                     |                        :
          XX.doc        |                     V                        V
       (nieobowiązkowy) |                  master.doc ------->-------->+
            :           |                   (nowy)                     |
            V           V                     |                        |
         [po4a-gettextize]   doc.XX.po--->+   |                        |
                 |           (stary)      |   |                        |
                 |              ^         V   V                        |
                 |              |     [po4a-updatepo]                  |
                 V              |           |                          V
         tłumaczenie.pot        ^           V                          |
                 |              |         doc.XX.po                    |
                 |              |         (fuzzy)                      |
          { tłumaczenie }       |           |                          |
                 |              ^           V                          V
                 |              |     {ręczna edycja}                  |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<---- doc.XX.po  załącznik    master.doc
            (początkowy)                  (aktualny) (opcjonalny)  (aktualny)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                                  [po4a-translate]
                                                         |
                                                         V
                                                       XX.doc
                                                     (aktualny)

       Lewa część pokazuje konwersję tłumaczenia nie używającego jeszcze po4a
       do tego systemu. Góra prawej części pokazuje akcje autora oryginału
       (aktualizowanie dokumentacji). Środek prawej części obrazuje
       automatyczne akcje po4a. Nowy materiał jest wyodrębniany i porównywany
       z istniejącymi tłumaczeniami. Znajdowane są części, które się nie
       zmieniły, i dla nich używane jest poprzednie tłumaczenie. Części
       zmodyfikowane tylko w nieznacznym stopniu są także łączone z
       poprzednimi tłumaczeniami, ale dodawany jest specjalny znacznik,
       mówiący, że tłumaczenie musi być uaktualnione. Dół rysunku pokazuje
       sposób, w jaki jest budowany sformatowany dokument.

       Właściwie, jedyną ręczną operacją, którą musi wykonać tłumacz jest
       część oznaczona {ręczna edycja}. Przykro nam, po4a tylko pomaga
       tłumaczyć, ale niestety niczego za Ciebie nie przetłumaczy...

   JAK zacząć nowe tłumaczenie?
       Ta sekcja opisuje kroki niezbędne do rozpoczęcia nowego tłumaczenia z
       użyciem po4a. Konwertowanie istniejącego projektu do tego systemu
       opisano w szczegółach w odpowiedniej sekcji.

       Aby zacząć nowe tłumaczenie, używając po4a, należy wykonać następujące
       kroki:

       - Wyciągnąć tekst do przetłumaczenia z oryginalnego dokumentu
         <master.doc> do nowego szablonu pliku <tumaczenie.pot> (w formacie
         programu gettext). Aby to zrobić, należy wywołać program
         po4a-gettextize w następujący sposób:

           $ po4a-gettextize -f <format> -m <master.doc> -p <tłumaczenie.pot>

         <format> jest oczywiście formatem używanym w dokumencie master.doc.
         Jak można oczekiwać, plikiem wyjściowym jest tumaczenie.pot. Więcej
         szczegółów o dostępnych opcjach można znaleźć w po4a-gettextize(1).

       - Przetłumaczyć to, co jest do przetłumaczenia. W tym celu należy
         zmienić nazwę pliku POT na przykład na doc.XX.po (gdzie XX jest kodem
         ISO639 języka, na który się tłumaczy, np. fr dla języka francuskiego)
         i edytować powstały plik. Zazwyczaj dobrym pomysłem jest nienazywanie
         tego pliku XX.po, aby uniknąć pomylenia z tłumaczeniem komunikatów
         programu, ale wybór należy do Ciebie. Proszę nie zapominać o
         uaktualnieniu nagłówków pliku PO; są one bardzo ważne.

         Do tłumaczenia można wykorzystać tryb PO Emacsa, program Lokalize
         (oparty na KDE) lub Gtranslator (oparty na GNOME) lub jakikolwiek
         inny program, w zależności od upodobań tłumacza. Można nawet użyć
         dobrego starego edytora vi, mimo że nie ma on specjalnego trybu
         ułatwiającego tłumaczenia.

         Aby dowiedzieć się czegoś więcej, stanowczo powinno się przeczytać
         dokumentację programu gettext, dostępną w pakiecie gettext-doc.

   JAK zamienić tłumaczenie z powrotem do pliku dokumentacji?
       Po zakończeniu tłumaczenia zapewne należałoby wygenerować
       przetłumaczone dokumenty i rozdystrybuować je wśród użytkowników, razem
       z oryginalnymi dokumentami. Aby to zrobić, należy użyć programu
       po4a-translate(1) w ten sposób (XX jest kodem języka):

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

       Jak wcześniej, <format> jest formatem dokumentu master.doc. Jednak tym
       razem plik PO, przekazany w opcji -p, jest częścią wejścia - jest to
       Twoje tłumaczenie. Wyjście jest zapisywane w XX.doc.

       Więcej szczegółów można znaleźć w <po4a-translate(1)>.

   JAK zaktualizować tłumaczenie programem po4a?
       Aby zaktualizować tłumaczenie, gdy zmieni się oryginalny plik
       master.doc, należy użyć po4a-updatepo(1) w następujący sposób:

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

       (Więcej szczegółów można znaleźć w <po4a-updatepo(1)>).

       Oczywiście ta operacja nie spowoduje automagicznego przetłumaczenia
       nowych akapitów oryginalnego dokumentu. Należy ręcznie uaktualnić plik
       PO. Podobnie należy zaktualizować tłumaczenie akapitów, które się choć
       trochę zmieniły. Aby mieć pewność, że żadnego z nich nie ominiesz,
       zostały one zaznaczone jako "fuzzy" (niepewne) i zanim po4a-translate
       będzie mógł ich użyć, to zaznaczenie musi zostać usunięte. Tak jak w
       przypadku pierwszego tłumaczenia najlepiej jest użyć ulubionego
       edytora.

       Kiedy plik PO będzie znowu aktualny, bez żadnych wpisów
       nieprzetłumaczonych lub niepewnych ("fuzzy"), można wygenerować
       przetłumaczony plik dokumentacji, tak jak to opisano w poprzedniej
       sekcji.

   JAK skonwertować istniejące tłumaczenia do po4a?
       Często się zdarzało, że tłumaczyłeś dokument ręcznie dopóty, dopóki nie
       nastąpiła większa reorganizacja oryginalnego dokumentu master.doc. W
       tej sytuacji, po kilku nieprzyjemnych próbach z diffem lub podobnymi
       narzędziami, możesz zechcieć skonwertować dokument do po4a. Oczywiście
       należy go skonwertować tak, aby nie utracić istniejących tłumaczeń. Nie
       należy się obawiać, ten przypadek także jest obsługiwany przez po4a i
       jest nazywany procesem przechodzenia do formatu gettext.

       Kluczową kwestią jest to, aby struktura tłumaczonego dokumentu była
       taka sama jak oryginału, tak żeby narzędzia mogły odpowiednio dopasować
       zawartość.

       Jeśli masz szczęście (tj. struktura obu dokumentów dokładnie do siebie
       pasuje), wszystko zadziała bez żadnego problemu i będzie gotowe w ciągu
       paru sekund. W przeciwnym razie możesz zrozumieć dlaczego ten proces ma
       taką brzydką nazwę i przygotuj się na dość nieprzyjemną pracę. W każdym
       razie, pamiętaj, że jest to cena za komfort, który później dostarczy
       po4a. Dobre w tym wszystkim jest to, że trzeba to zrobić tylko raz.

       Nie będę się długo nad tym rozwodził. Aby ułatwić proces, ważne jest
       znalezienie dokładnie tej wersji oryginału, która była przetłumaczona.
       Najlepiej, jeśli zanotowałeś sobie wersję z CVS-u dokumentu użytego do
       tłumaczenia i jej nie modyfikowałeś w procesie tłumaczenia, tak że
       możesz jej teraz użyć.

       Nie zadziała to dobrze, jeśli użyje się uaktualnionego tekstu oryginału
       ze starym tłumaczeniem. Pozostaje to możliwe, ale jest to trudniejsze i
       naprawdę powinno się tego unikać, gdy tylko jest to możliwe. Jeżeli nie
       udało Ci się znaleźć ponownie starego oryginału, to najlepszym
       rozwiązaniem jest znalezienie kogoś, kto przeprowadzi za Ciebie proces
       przechodzenia na format gettext (ale, proszę, niech nie będę to ja ;).

       Być może zbytnio w tym momencie dramatyzuję. Jednak nawet, gdy proces
       się nie udaje, pozostaje mimo wszystko szybszą drogą niż tłumaczenie
       wszystkiego od nowa. Udało mi się przepuścić przez ten proces
       francuskie tłumaczenie dokumentacji Perla w ciągu jednego dnia, nawet
       wtedy, gdy wszystko szło źle. Było to ponad dwa megabajty tekstu,
       którego tłumaczenie od nowa trwałoby miesiącami lub dłużej.

       Proszę najpierw pozwolić mi wyjaśnić podstawy tej procedury, a potem
       powrócę do wskazówek, co zrobić, gdy proces się nie udaje. Dla lepszego
       zrozumienia, ponownie użyjemy powyższego przykładu.

       Jeżeli jest dostępny stary plik master.doc z odpowiadającymi mu
       tłumaczeniami XX.doc, przechodzenie do formatu gettext można zrobić
       bezpośrednio do pliku doc.XX.po bez ręcznego tłumaczenia pliku
       tumaczenie.pot:

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

       Jeśli masz szczęście, to to wszystko. Stare tłumaczenia zostały
       skonwertowane do po4a i można od razu zacząć ich aktualizowanie. Należy
       tylko trzymając się procedury opisanej kilka sekcji wcześniej,
       zsynchronizować plik PO z najnowszym oryginalnym dokumentem i
       odpowiednio zaktualizować tłumaczenia.

       Proszę zauważyć, że nawet jeśli wydaje się, że wszystko zadziałało
       poprawnie, może się okazać, że jednak wystąpiły błędy podczas tego
       procesu. Po4a nie rozumie przetwarzanych tekstów, więc nie może być być
       pewne, że tłumaczenia są poprawnie przypisane do oryginałów. Dlatego
       wszystkie komunikaty są oznaczone jako "fuzzy" (niepewne). Przed
       usunięciem tych znaczników, proszę uważnie sprawdzić każde tłumaczenie.

       Bardzo często struktury dokumentów nie pasują dokładnie do siebie,
       przez co po4a-gettextize nie może poprawnie wykonać swojego zadania. W
       tym punkcie gra toczy się o to, aby tak pozmieniać pliki, aby ich
       cholerne struktury sobie odpowiadały.

       Pomocne może być przeczytanie poniżej sekcji Proces przekształcania do
       formatu gettext: jak to działa?. Zrozumienie wewnętrznych procesów
       pomoże wykonać zadanie. Plusem jest to, że w razie niepowodzenia,
       po4a-gettextize głośno powie, co poszło źle, umożliwiając poznanie
       komunikatów, które do siebie nie pasowały, ich pozycję w tekście i typ
       każdego z nich. Co więcej, plik PO wygenerowany do tej pory, będzie
       zachowany jako gettextization.failed.po.

       -   Należy usunąć wszystkie dodatkowe części tłumaczenia, takie jak
           sekcja, w której podano nazwisko tłumacza i podziękowania dla
           wszystkich ludzi, którzy pomagali przy tłumaczeniu. Później takie
           części będzie można z powrotem dodać, używając załączników,
           opisanych w następnym rozdziale.

       -   Nie wahaj się edytować zarówno pliku oryginalnego, jak i jego
           tłumaczenia. Najważniejszą rzeczą jest otrzymanie pliku PO. Potem
           będzie można go zaktualizować. Edytowanie tłumaczeń powinno być
           jednak preferowane, ponieważ uprości to pewne rzeczy po zakończeniu
           się procesu przekształcania na format gettext.

       -   Jeśli jest taka potrzeba, należy usunąć kilka części oryginalnego
           dokumentu, które nie są przetłumaczone. Później podczas
           synchronizowania PO z dokumentem części te się pojawią same.

       -   Jeśli w niewielkim stopniu zmieniłeś strukturę dokumentu
           (połączenie dwóch akapitów, albo podzielenie innego akapitu),
           wycofaj te zmiany. Jeśli te zmiany miały związek z problemami
           występującym w oryginalnym dokumencie, powinieneś poinformować o
           nich jego autora. Korzyści z poprawienie ich tylko w Twoim
           tłumaczeniu będzie miała tyko część społeczności. Co więcej, takie
           poprawki nie są możliwe, gdy się używa po4a.

       -   Czasami zawartości akapitów się zgadzają, ale ich typy nie.
           Poprawienie tego zależy od formatu. W formatach POD i man, często
           bierze się to z tego, że jeden z tych dwóch akapitów zawiera linię
           zaczynającą się od białego znaku, a drugi - nie. W tych formatach
           tekst takich akapitów nie może być zawijany i dlatego występuje
           niezgodność typów. Rozwiązaniem jest usunięcie spacji. Może to być
           także literówka w nazwie elementu.

           Podobnie, dwa akapity mogą zostać scalone razem w formacie POD,
           jeżeli rozdzielająca linia zawiera spacje lub kiedy brakuje pustej
           linii przed linią ==item i zawartością tego elementu.

       -   Czasami występuje rozsynchronizowanie między plikami i tłumaczenie
           jest przypisane do złego akapitu oryginału. Jest to oznaka, że w
           rzeczywistości problem leży w plikach. Proszę znaleźć w
           gettextization.failed.po miejsce, gdzie zaczyna się
           rozsynchronizowanie, a następnie poprawić w tym miejscu pliki
           wejściowe.

       -   Czasami może się wydawać, że po4a zjadło jakąś część tekstu albo z
           oryginału, albo z tłumaczenia. gettextization.failed.po wskazuje,
           że oba pliki dokładnie do siebie pasowały, a przetwarzanie kończy
           się błędem ponieważ nastąpiła próba dopasowania jakiegoś akapitu do
           akapitu po (lub przed) tym właściwym, tak jakby ten właściwy się
           ulotnił. Można tylko kląć na po4a, tak jak ja kląłem, gdy mi się to
           zdarzyło po raz pierwszy. Serio.

           Ta nieszczęśliwa sytuacja zdarza się, kiedy ten sam akapit jest
           powtórzony w dokumencie. W tym przypadku nie jest tworzony nowy
           wpis w pliku PO, ale dodawane jest tylko nowe odwołanie do już
           istniejącego wpisu.

           Tak więc, kiedy ten sam akapit pojawia się dwa razy w oryginalnym
           dokumencie, ale nie jest przetłumaczony w dokładnie ten sam sposób,
           można mieć wrażenie, że ten akapit oryginału zniknął. Wystarczy
           usunąć nowe tłumaczenie. Jeśli preferowałbyś usunięcie pierwszego z
           tych tłumaczeń, bo drugie jest lepsze, po prostu przenieś drugie
           tłumaczenie w miejsce pierwszego.

           Odwrotnie, jeśli dwa podobne, ale jednak różne, akapity były
           przetłumaczone dokładnie tak samo, to jeden akapit tłumaczenia
           zniknie. Rozwiązaniem jest dodanie głupiego tekstu do oryginalnego
           akapitu (takiego jak "różnię się"). Nie trzeba się tego bać, takie
           rzeczy znikną podczas synchronizacji, a kiedy taki tekst jest
           wystarczająco krótki, gettext dopasuje Twoje tłumaczenie do
           istniejącego tekstu (oznaczając je jako niepewne ["fuzzy"], czym
           nie powinno się przejmować, gdyż wszystkie komunikaty są tak
           oznaczone zaraz po procesie przekształcania na format gettext).

       Mamy nadzieję, że te porady pomogą w procesie przekształcania do
       formatu gettext i w otrzymaniu pliku PO. Można teraz ten plik
       zsynchronizować i zacząć go tłumaczyć. Proszę zauważyć, że w wypadku
       długich plików, pierwsza synchronizacja może zająć dużo czasu.

       Na przykład, pierwsze wykonanie po4a-updatepo na francuskim tłumaczeniu
       dokumentacji Perla (plik PO o rozmiarze 5.5 Mb) zajęło około dwóch dni
       na komputerze 1Ghz G5. Tak, 48 godzin. Ale kolejne zajmują tylko
       kilkanaście sekund na moim starym laptopie. Dzieje się tak, ponieważ na
       samym początku większość msgid pliku PO nie pasuje do żadnego msgid w
       pliku POT. Wymusza to na programie gettext wyszukiwanie najbardziej
       zbliżonego msgid, używając kosztownego algorytmu bliskości łańcuchów
       znaków.

   JAK dodać dodatkowy tekst do tłumaczeń (np. nazwisko tłumacza)?
       Z powodu rozwiązań stosowanych przez gettext, zrobienie tego może być
       trudniejsze w po4a niż było wcześniej, kiedy to plik był po prostu
       ręcznie edytowany. Jednak pozostaje to możliwe, dzięki tak zwanym
       załącznikom.

       Dla lepszego zrozumienia można przyjąć, że załączniki są rodzajem łat
       (patch) aplikowanych do przetłumaczonego dokumentu po zakończeniu
       przetwarzania. Różnią się one od zwykłych łat (mają tylko jedną linię
       kontekstu, która może zawierać wyrażenie regularne Perla, i mogą tylko
       dodawać nowy tekst bez usuwania czegokolwiek), ale funkcjonalność jest
       taka sama.

       Celem jest danie tłumaczowi możliwości dołączenie do dokumentu
       dodatkowej zawartości, która nie jest tłumaczeniem oryginalnego
       dokumentu. Najczęściej używany jest do dodawania sekcji dotyczącej
       samego tłumaczenia, wypisania współpracowników lub podania sposobu
       zgłaszania błędów znalezionych w tłumaczeniu.

       Załącznik musi być podany jako osobny plik, którego pierwsza linia
       zawiera nagłówek określający, gdzie należy umieścić tekst załącznika.
       Reszta pliku załącznika będzie umieszczona bez zmian w określonej
       pozycji wynikowego dokumentu.

       Składnia nagłówka jest całkiem sztywna: musi zaczynać się od tekstu
       PO4A-HEADER: poprzedzającego rozdzieloną średnikami (;) listę pól
       klucz=warto. Spacje SĄ istotne. Proszę zauważyć, że nie można użyć
       średników (;) w wartości, a ich cytowanie za pomocą odwrotnego ukośnika
       nie pomaga.

       Tak, brzmi to strasznie, ale poniższe przykłady powinny pomóc w
       napisaniu odpowiedniej linii nagłówka. Aby zilustrować dyskusję,
       załóżmy, że chcemy dodać sekcję "O tłumaczeniu" zaraz po sekcji "O
       dokumencie".

       Kilka możliwych kluczy nagłówka:

       position (obowiązkowe)
           wyrażenie regularne. Załącznik będzie umieszczony w pobliżu linii
           pasującej do wyrażenia regularnego. Proszę zauważyć, że mówimy
           tutaj o dokumencie przetłumaczonym, a nie o oryginale. Jeśli więcej
           niż jedna linia pasuje do tego wyrażenia, dodawanie załącznika się
           nie powiedzie. Istotnie, lepiej jest zgłosić błąd niż wstawić
           załącznik w nieodpowiednie miejsc.

           Tę linię będziemy dalej nazywać punktem pozycji. Punkt, w którym
           załącznik jest dodawany nazwiemy punktem wstawienia. Te dwa punkty
           są blisko siebie, ale nie są sobie równe. Na przykład, aby dodać
           nową sekcję łatwiej zaczepić punkt pozycji na tytule poprzedniej
           sekcji i wytłumaczyć programowi po4a, gdzie ta sekcja się kończy
           (należy pamiętać, że punkt pozycji jest podany przez wyrażenie
           regularne, które powinno dopasowywać się do pojedynczej linii).

           Zależność miejsca punktu wstawienia w stosunku do punkty pozycji
           jest określana przez pola mode, beginboundary i endboundary,
           opisane poniżej.

           W naszym przypadku byłoby to:

                position=<title>O dokumencie</title>

       mode (obowiązkowe)
           Może być to jeden z następujących łańcuchów znaków: before (=
           przed) lub after (= po), określających pozycję dodatku w stosunku
           do punktu pozycji.

           Ponieważ chcemy nową sekcję umieścić pod tą, którą wyszukaliśmy,
           mamy:

                mode=after

       beginboundary (używany, gdy mode=after i obowiązkowy w tym wypadku)
       endboundary (jak wyżej)
           wyrażenie regularne pasujące do końca sekcji, po której jest
           dodawany załącznik.

           W trybie after punkt wstawienia jest za punktem pozycji, ale nie
           bezpośrednio za! Jest on umieszczony na końcu sekcji zaczynającej
           się w punkcie pozycji, czyli za albo przed linią pasującą do
           argumentu ???boundary w zależności od tego, czy było użyte
           beginboundary, czy endboundary.

           W rozpatrywanym przypadku możemy wybrać wskazanie końca
           dopasowywanej sekcji, dodając:

              endboundary=</section>

           albo możemy wskazać początek kolejnej sekcji w następujący sposób:

              beginboundary=<section>

           W obu wypadkach załącznik będzie umieszczony po </section>, a przed
           <section>. Ten pierwszy sposób działa lepiej, ponieważ zadziała
           nawet wtedy, gdy dokument zostanie zreorganizowany.

           Obie formy istnieją ponieważ formaty dokumentacji są różne.
           Niektóre z nich zawierają znacznik końca sekcji (tak jak
           </section>, której właśnie użyliśmy), a inne (np. man) tego końca
           nie oznaczają w żaden szczególny sposób. W pierwszym przypadku
           boundary powinno odpowiadać kocowi sekcji, tak że punkt wstawienia
           następuje po niej. W drugim przypadku boundary powinno pasować do
           pocztku nastpnej sekcji, a punkt wstawienia powinien być
           umieszczony zaraz przed nią.

       Może się to wydawać niejasne, następne przykłady powinny co nieco
       wyklarować.

       Podsumowując przykłady podane do tej pory: aby dodać sekcję "O
       tłumaczeniu" po sekcji "O dokumencie" w dokumencie SGML, należy użyć
       jednej z poniższych linii nagłówka:
          PO4A-HEADER: mode=after; position=O dokumencie; endboundary=</section>
          PO4A-HEADER: mode=after; position=O dokumencie; beginboundary=<section>

       Aby dodać coś po następującej sekcji nroff:
           .SH "AUTORZY"

         powinno się ustawić positon pasujące do tej linii oraz beginboundary
         pasujące do początku następnej sekcji (tj. ^\.SH). Załącznik zostanie
         dodany po punkcie pozycji i zaraz przed pierwszą linią pasującą do
         beginboundary. Czyli:

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

       Aby zamiast dodawać całą sekcję, dodać coś do jakiejś sekcji (np. po
       "Copyright Big Dude"), trzeba podać position pasujące do tej linii i
       beginboundary pasujące do jakiejkolwiek linii.
          PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

       Aby dodać coś na końcu dokumentu, należy podać position pasujące do
       jakiejkolwiek linii pliku (ale tylko jednej linii. Po4a nie przetworzy
       tego, jeśli linia nie będzie unikatowa) i podać endboundary nie
       pasujące do niczego. Nie należy używać tutaj prostych tekstów jak
       "EOF", tylko takich, które mają małe szanse pojawienia się w
       dokumencie.
          PO4A-HEADER:mode=after;position=<title>O dokumencie</title>;beginboundary=NieistniejąaLiniaPo4a

       W każdym wypadku należy pamiętać, że są to wyrażenia regularne. Na
       przykład, aby dopasować koniec sekcji nroff, kończącej się linią

         .fi

       nie należy używać .fi jako endboundary, ponieważ będzie on pasował do
       "the[ fi]le" co raczej nie jest tym, czego można by oczekiwać.
       Poprawnym endboundary w tym przypadku jest ^\.fi$.

       Jeśli załącznik nie trafił tam, gdzie powinien, spróbuj przekazać
       narzędziom po4a argument -vv, który powinien pomóc wyjaśnić co się
       dzieje podczas dodawania załącznika.

       Bardziej szczegowy przykad

       Oryginalny dokument (w formacie POD):

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

       Wtedy następujący dodatek spowoduje dodanie sekcji (w języku
       francuskim) na koniec tego pliku (w jęz. francuskim "TRADUCTEUR"
       oznacza "TŁUMACZ", a "moi" znaczy "ja")

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

       Aby umieścić dodatek przed sekcją AUTOR, należy użyć następującego
       nagłówka:

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

       To działa, ponieważ następną linią pasującą do beginboundary /^=head1/
       po sekcji "NAZWA" (przetłumaczonej na francuskie "NOM") jest linia
       opisująca autorów. Tak więc załącznik zostanie umieszczony pomiędzy
       obiema sekcjami.

   JAK to wszystko zrobić, wywołując tylko jeden program?
       Użytkownicy udowodnili, że takie użycie po4a jest narażone na błędy,
       ponieważ należy we właściwym porządku wywołać dwa różne programy
       (po4a-updatepo, a następnie po4a-translate), z których każdy wymaga
       podania więcej niż 3 argumentów. Co więcej, w tym systemie było trudno
       użyć tylko jednego pliku PO dla wszystkich dokumentów, kiedy użyto
       więcej niż jednego formatu.

       Program po4a(1) zaprojektowano, aby rozwiązać te trudności. Kiedy tylko
       projekt zostanie skonwertowany do tego systemu, można napisać prosty
       plik konfiguracyjny opisujący miejsce położenia plików tłumaczeń (PO i
       POT) i oryginalnych dokumentów, ich formaty oraz miejsce, gdzie powinny
       trafiać przetłumaczone dokumenty.

       Uruchomienie po4a(1) na tym pliku spowoduje zsynchronizowanie
       wszystkich plików PO z oryginalnym dokumentem, tak żeby przetłumaczony
       dokument został poprawnie wygenerowany. Oczywiście należy ten program
       wywołać dwa razy: raz przed edytowaniem pliku PO, żeby go
       zaktualizować, i raz po jego edycji, aby otrzymać całkowicie aktualny
       przetłumaczony dokument . Tylko że potrzebujesz zapamiętać tylko jedną
       komendę linii poleceń.

   JAK dostosować po4a do własnych potrzeb?
       Moduły po4a mają opcje (określane przez -o opcja), których można użyć,
       żeby zmienić zachowanie modułów.

       Możliwe jest także dostosowywanie modułu oraz modułu nowego /
       pochodnego / zmodyfikowanego przez umieszczenie go w katalogu
       lib/Locale/Po4a/ i dodanie lib do ścieżki określonej w zmiennej
       środowiskowej PERLLIB lub PERL5LIB. Na przykład:

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

       Uwaga: rzeczywista nazwa katalogu lib nie jest istotna.

Jak to działa?

       Ten rozdział zawiera krótki opis wewnętrznych mechanizmów po4a, tak że
       będziesz miał więcej odwagi, aby pomóc nam w jego tworzeniu i
       udoskonalaniu. Może także Ci pomóc w zrozumieniu, dlaczego nie działa
       tak, jak byś tego oczekiwał, oraz jak rozwiązać napotkane problemy.

   Jak wyglądają szczegóły?
       Architektura po4a jest zorientowana obiektowo (w Perlu, czy to nie
       eleganckie?). Wspólny przodek wszystkich klas parserów zwie się
       TransTractor. Ta dziwna nazwa wzięła się stąd, że jest on
       odpowiedzialny za tłumaczenie dokumentu i wydobywanie komunikatów.

       Bardziej formalnie mówiąc, pobiera dokument do przetłumaczenia oraz
       plik PO zawierający tłumaczenia używany jako wejście podczas tworzenia
       dwóch oddzielnych plików wyjściowych: innego pliku PO (wyniku
       wyodrębniania komunikatów z dokumentu wejściowego) oraz
       przetłumaczonego dokumentu (mającego taką samą strukturę jak plik
       wejściowy, ale ze wszystkimi komunikatami zamienionymi na zawartość
       wejściowego pliku PO). Poniżej jest graficzne przedstawienie tego
       procesu:

          Dokument wejściowy -\                          /-> Dokument wyjściowy
                               \      TransTractor::    /    (przetłumaczony)
                                +-->--   parse()  --- -+
                               /                        \
          Wejściowy PO -------/                          \---> Wyjściowy PO
                                                               (wyodrębniony)

       Ta mała kość jest podstawą całej architektury po4a. Jeśli pominiesz
       wejściowy plik PO i dokument wyjściowy, otrzymasz po4a-gettextize.
       Jeśli podasz oba pliki wejściowe i zlekceważysz wyjściowy plik PO,
       otrzymasz po4a-translate.

       TransTractor::parse() jest wirtualną funkcją zaimplementowaną w każdym
       module. Tutaj podano prosty przykład, żeby zobrazować jej działanie.
       Przetwarza listę akapitów, z których każdy 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 wejściowego.
        19   }
        20 }

       W linii 6. po raz drugi napotkaliśmy <p>. Oznacza to kolejny akapit.
       Powinniśmy dlatego zwrócić otrzymaną linię do oryginalnego dokumentu
       (linia 7.), a na wyjście dołożyć akapit zbudowany do tej pory. Po
       usunięciu z niego początkowego <p> w linii 9., dokładamy ten element
       połączony z tłumaczeniem reszty akapitu.

       Funkcja translate() jest bardzo fajna (cool ;)). Dodaje swoje argumenty
       na koniec wynikowego pliku PO (ekstrakcja) i zwraca ich tłumaczenie,
       znalezione w wejściowym pliku PO (tłumaczenie). Ponieważ jest używana
       jako część argumentu pushline(), tłumaczenie ląduje w wynikowym
       dokumencie.

       Czy to nie jest fajne? Jest możliwe zbudowanie kompletnego modułu po4a
       w mniej niż 20 liniach, jeżeli tylko format jest wystarczająco
       prosty...

       Więcej informacji o tym można znaleźć w
       Locale::Po4a::TransTractor(3pm).

   Proces przekształcania do formatu gettext: jak to działa?
       Idea jest następująca: pobranie oryginalnego dokumentu i jego
       tłumaczenia i powiedzenie, że n-ty komunikat wyodrębniony z tłumaczenia
       jest tłumaczeniem n-tego komunikatu wyodrębnionego z oryginału. Aby to
       zadziałało, oba pliki muszą mieć dokładnie taką samą strukturę. Na
       przykład, jeżeli pliki mają poniższą strukturę, to jest raczej
       niemożliwe, by 4. komunikat tłumaczenia (typu "rozdział") był
       tłumaczeniem 4. komunikatu oryginału (typu "akapit").

          Oryginał         Tłumaczenie

          rozdział          rozdział
             akapit            akapit
             akapit            akapit
             akapit         rozdział
          rozdział             akapit
             akapit            akapit

       Aby to osiągnąć, parsery po4a są używane zarówno na pliku oryginału,
       jak i tłumaczenia, żeby utworzyć pliki PO, a następnie jest budowany z
       nich trzeci plik PO zawierający komunikaty z drugiego pliku jako
       tłumaczenia komunikatów z pierwszego. Aby sprawdzić, że komunikaty,
       które ze sobą łączymy, są rzeczywiście odpowiadającymi sobie
       tłumaczeniami, parsesy dokumentów w po4a powinny umieszczać informacje
       o typach składniowych komunikatów wyodrębnionych z dokumentu (wszystkie
       istniejące to robią, Twój też powinien). Następnie te informacje są
       używane do sprawdzenia, że oba dokumenty mają tę samą składnię. W
       poprzednim przykładzie pozwoliło nam to wykryć, że 4. komunikat jest w
       jednym przypadku akapitem, a w drugim - tytułem rozdziału i zgłosić
       problem.

       Teoretycznie byłoby możliwe zsynchronizowanie plików po wykryciu
       problemu (tak, jak to robi diff). Niestety, nie jest jasne, co zrobić z
       komunikatami, które nie występując w jednym z plików, były przyczyną
       rozsynchronizowania. Dlatego obecna implementacja nie stara się
       synchronizować plików i zgłasza błąd, kiedy coś poszło źle, wymagając
       od użytkownika ręcznego zmodyfikowania plików w celu rozwiązania
       problemu.

       Nawet z tymi zabezpieczeniami, rzeczy mogą źle się potoczyć. Właśnie
       dlatego wszystkie tłumaczenia odgadnięte w ten sposób są zaznaczane
       jako niepewne ("fuzzy"), aby tłumacz je przejrzał i sprawdził.

   Załącznik: Jak to działa?
       Hmm, to całkiem proste. Tłumaczony dokument nie jest bezpośrednio
       zapisywany na dysk, ale trzymany w pamięci, dopóki wszystkie załączniki
       nie zostaną dodane. Wykorzystane algorytmy są raczej proste. Szukamy
       linii pasującej do wyrażenia regularnego określającego pozycję i
       dodajemy załącznik przed tą liną, jeśli tryb = before. Jeśli nie
       jesteśmy w tym trybie, to szukamy następnej linii pasującej do
       ograniczenia i wstawiamy załącznik po tej linii, jeśli jest to
       endboundary, lub przed nią, jeśli jest to beginboundary.

FAQ

       Ten rozdział zawiera odpowiedzi na często zadawane pytania. Tak
       naprawdę, większość tych pytań może być sformułowanych jako "Dlaczego
       po4a zostało zaprojektowane tak, a nie inaczej?". Jeśli wydaje Ci się,
       że po4a nie jest właściwym narzędziem do tłumaczenia dokumentacji,
       powinieneś rozważyć przeczytanie tego rozdziału. Jeśli 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 użytkowników.

   Dlaczego trzeba tłumaczyć każdy akapit osobno?
       Tak, w po4a, każdy akapit jest tłumaczony osobno (w zasadzie, to każdy
       moduł o tym decyduje, ale wszystkie istniejące moduły tak robią i Twój
       także powinien). Są dwie główne przyczyny takiego rozwiązania:

       · Kiedy techniczne części dokumentu są ukryte, tłumacz nie może w nich
         zrobić bałaganu. Im mniej znaczników pokazujemy tłumaczowi, tym mniej
         błędów może popełnić.

       · Przycinanie dokumentu pomaga odizolować zmiany w oryginalnym
         dokumencie. Kiedy oryginał zostanie zmieniony, ten proces uprości
         wyszukanie części tłumaczeń potrzebujących aktualizacji.

       Nawet biorąc pod uwagę te plusy, niektórym ludziom nie podoba się
       osobne tłumaczenie każdego akapitu. Postaram się odpowiedzieć na ich
       obawy:

       · Takie podejście sprawdziło się w projekcie KDE, pozwalając temu
         zespołowi na wyprodukowanie znacznej ilości przetłumaczonej i
         aktualnej dokumentacji.

       · Tłumacze mogą wciąż używać kontekstu tłumaczenia, ponieważ wszystkie
         komunikaty w pliku PO są w takiej samej kolejności jak w oryginalnym
         dokumencie. Tłumaczenie sekwencyjne jest podobne, niezależnie, czy
         używa się po4a czy nie. I w każdym wypadku najlepszym sposobem
         otrzymania kontekstu pozostaje skonwertowanie dokumentu do formatu
         dokumentu drukowanego, ponieważ formaty źródłowe tekstu mogą nie być
         zbyt czytelne.

       · Takie podejście jest używany przez profesjonalnych tłumaczy. Zgadzam
         się, mają oni trochę inne cele niż tłumacze oprogramowania open-
         source. Na przykład możliwość łatwego zarządzania tłumaczeniem jest
         często dla nich mniej istotna, ponieważ zawartość rzadko się zmienia.

   Dlaczego nie podzielić na zdania (lub mniejsze części)?
       Profesjonalne narzędzie tłumaczy czasami dzielą dokument na
       poszczególne zdania, aby zmaksymalizować wykorzystanie wcześniejszych
       tłumaczeń i zwiększyć szybkość tłumaczenia. Problemem jest jednak to,
       że w zależności od kontekstu to samo zdanie może mieć kilka tłumaczeń.

       Akapity są z definicji dłuższe niż zdania. Jeżeli w dwóch dokumentach
       ten sam akapit występuje, to możemy założyć, że jego znaczenie (i
       tłumaczenie) jest takie samo, niezależnie od kontekstu.

       Dzielenie na części mniejsze niż zdania byłoby czymś bardzo niedobrym.
       Za dużo miejsca by zajęło napisanie tu wyjaśnienie dlaczego, ale
       zainteresowany czytelnik może na przykład przeczytać stronę podręcznika
       Locale::Maketext::TPJ13(3pm) (pochodzącą z dokumentacji Perla). W
       skrócie, każdy język ma określone zasady składniowe i nie istnieje taki
       sposób budowania zdań przez łączenie ich części, który by działał dla
       wszystkich istniejących języków (lub nawet dla tylko 5 czy 10
       najpopularniejszych).

   Dlaczego nie umieścić oryginału jako komentarza do tłumaczenia (lub w inny
       sposób)?
       Na pierwszy rzut oka gettext nie wydaje się być przeznaczony do
       wszystkich rodzajów tłumaczeń. Na przykład nie wydawał się on być
       przystosowany do debconfa, interfejsu wszystkich pakietów Debiana
       używanego do interakcji z użytkownikiem podczas instalacji. W tym
       przypadku teksty do tłumaczenia były całkiem krótkie (tuzin linii dla
       każdego pakietu) i było trudno umieścić tłumaczenie w specjalnym pliku
       ponieważ musiało być dostępne jeszcze przed zainstalowaniem pakietu.

       To dlatego opiekun debconfa zdecydował zaimplementować inne
       rozwiązanie, w którym tłumaczenia są umieszczane w tym samym pliku, co
       oryginał. Jest to pociągające. Ktoś mógłby nawet chcieć coś takiego
       zrobić dla XML-a na przykład. Mógłby on wyglądać 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 było to na tyle problematyczne, że obecnie jest używane
       rozwiązanie oparte na plikach PO. Tylko oryginalny tekst może być
       edytowany w pliku, a tłumaczenia muszą się pojawić w plikach PO,
       wyciągniętych z głównego szablonu (łączonych z powrotem w czasie
       kompilacji pakietu). Ten stary system jest potępiany z kilku powodów:

       ·   problemy w zarządzaniu

           Jeżeli kilku tłumaczy dostarczy łatę w tym samym czasie, będzie
           trudno połączyć te łaty wszystkie razem.

           Jak wykryć te zmiany w oryginale, które muszą być zastosowane w
           tłumaczeniach? Aby użyć programu diff, trzeba było zanotować wersję
           oryginału, która została przetłumaczone. Tj. potrzebujesz pliku PO
           w Twoim pliku.

       ·   problemy z kodowaniem znaków

           Rozwiązanie to jest dobre tylko dla europejskich języków, jednak
           wprowadzenie koreańskiego, rosyjskiego lub arabskiego bardzo
           wszystko komplikuje. Rozwiązaniem mógłby być UTF, jednak wciąż jest
           z nim kilka problemów.

           Co więcej takie problemy są trudne do wychwycenia (tj. tylko
           Koreańczycy zauważą że kodowanie znaków w koreańskim tekście jest
           zepsute [bo tłumacz był Rosjaninem]).

       gettext rozwiązuje wszystkie te problemy razem.

   Ale gettext nie został zaprojektowany do takiego użycia!
       To prawda, ale do tej pory nikt nie znalazł lepszego rozwiązania.
       Jedyną znaną alternatywą jest ręczne tłumaczenie ze wszystkimi
       problemami w jego zarządzaniu.

   Co z innymi narzędziami do tłumaczeń dokumentacji wykorzystującymi gettext?
       O ile mi wiadomo, są tylko dwa takie:

       poxml
           Jest to narzędzie rozwijane przez ludzi z KDE obsługujące format
           DocBook XML. O ile mi wiadomo, był to pierwszy program wyciągający
           łańcuchy znaków do przetłumaczenia z dokumentacji do plików PO i
           wstawiający je z powrotem po przetłumaczeniu.

           Może on obsługiwać tylko XML i częściowo DTD. Jestem bardzo
           niezadowolony z obsługi list, które zostają umieszczone w jednym
           wielkim msgid. Kiedy lista staje się długa, sprawa się komplikuje.

       po-debiandoc
           Program utworzony przez Denisa Barbiera jest poprzednikiem modułu
           SGML po4a, który w mniejszym bądź większym stopniu go zastępuje,
           czyniąc przestarzałym. Zgodnie ze swą nazwą obsługuje tylko
           DebianDoc DTD, który jest DTD mniej lub bardziej przestarzałym.

       Największą zaletą po4a nad nimi jest łatwość umieszczania dodatkowej
       zawartości (co jest nawet gorsze tutaj) i przejścia na format gettext.

   Przekazywanie deweloperom wiedzy o tłumaczeniu
       Próbując tłumaczyć dokumentację lub programy można napotkać trzy
       rodzaje problemów: lingwistyczne (nie każdy mówi dwoma językami),
       techniczne (to dlatego istnieje po4a) i ludzkie. Nie wszyscy
       deweloperzy rozumieją potrzebę tłumaczeń. Nawet mając dobre chęci, mogą
       ignorować potrzebę upraszczania pracy tłumaczy. Aby w tym pomóc, po4a
       dostarcza wiele dokumentacji, do której można się odnosić.

       Innym ważnym punktem jest to, że każdy plik z tłumaczeniem zaczyna się
       od krótkiego komentarza określającego, czym jest ten plik i jak go
       użyć. Powinno to pomóc deweloperom, zalanym tonami plików w różnych
       językach, których nie znają, pomóc w poprawnym obsłużeniu tego.

       W projekcie po4a przetłumaczone dokumenty nie są plikami źródłowymi.
       Ponieważ jesteśmy przyzwyczajeni do tego, że pliki sgml są plikami
       źródłowymi, łatwo jest o pomyłkę. Dlatego wszystkie pliki zawierają
       taki nagłówek:

        |       ****************************************************
        |       *         PLIK WYGENEROWANY, NIE EDYTOWAĆ          *
        |       * TO NIE JEST PLIK ŹRÓDŁOWY, ALE WYNIK KOMPILACJI  *
        |       ****************************************************
        |
        | Ten plik został wygenerowany przez po4a-translate(1). Nie przechowuj go
        | (na przykład w CVS-ie), ale przechowuj plik PO, użyty jako plik źródłowy
        | przez polecenie po4a-translate.
        |
        | Tak naprawdę, potraktuj ten plik jako plik binarny, a plik PO jako zwykły
        | plik źródłowy: jeśli plik PO zaginie, to będzie trudniej zachować aktualność
        | tego tłumaczenia ;)

       Podobnie, to co należy zrobić ze zwykłymi plikami PO programu gettext,
       to skopiować je do katalogu po/. Ale w przypadku plików zarządzanych
       przez po4a to nie działa. Największym ryzykiem tutaj jest to, że
       deweloper usunie istniejące tłumaczenia jego programu wraz z
       tłumaczeniami dokumentacji. (Oba nie mogą być przechowywane w jednym
       pliku PO, ponieważ program wymaga instalacji pliku tłumaczeń jako pliku
       mo, podczas gdy dokumentacja używa tłumaczeń w czasie kompilacji).
       Dlatego pliki PO tworzone przez moduł po-debiandoc zawierają poniższy
       nagłówek:

        #
        #  RADY DLA DEWELOPERÓW:
        #    - nie trzeba ręcznie edytować plików POT i PO.
        #    - ten plik zawiera tłumaczenie Twoich szablonów confiteor.
        #      Nie zastępuj tłumaczeń Twojego programu tym plikiem !!
        #        (albo tłumacze będą na Ciebie wściekli)
        #
        #  RADY DLA TŁUMACZY:
        #    Jeśli nie jesteś zaznajomiony z formatem PO, warto przeczytać
        #    dokumentację pakietu gettext, zwłaszcza sekcje poświęcone
        #    temu formatowi. Na przykład uruchom:
        #         info -n "(gettext)PO Files"
        #         info -n "(gettext)Heder Centry"
        #
        #    Informacje specyficzne po-debconf są dostępne w
        #            /usr/share/doc/po-debconf/README-trans
        #        lub http://www.debian.org/intl/l10n/po-debconf/README-trans
        #

   PODSUMOWANIE plusów i minusów rozwiązania opartego na gettext
       · Tłumaczenia nie są trzymane wraz z oryginałem, co pozwala w prosty
         sposób wykryć, czy tłumaczenia nie są przestarzałe.

       · Tłumaczenia są przechowywane w oddzielnych plikach, dzięki czemu
         tłumacze różnych języków sobie nie przeszkadzają, zarówno kiedy
         podsyłają swoje tłumaczenia, jak i kiedy zmieniają kodowanie znaków
         pliku.

       · Wewnętrznie jest oparty na pakiecie gettext (ale po4a oferuje bardzo
         prosty interfejs, tak że nie ma potrzeby poznawania wewnętrznych
         mechanizmów, aby go użyć). W ten sposób, nie musimy ponownie wymyślać
         koła, a ponieważ gettext jest szeroko używany, mamy nadzieję, że w
         większym lub mniejszym stopniu jest wolny od błędów.

       · Z punktu widzenia końcowego użytkownika nic się nie zmieniło (poza
         tym, że tłumaczenia są lepiej zarządzane). Wynikowe pliki z
         dokumentacją są tak samo dystrybuowane.

       · Tłumacze nie muszą uczyć się składni nowego pliku i mogą po prostu
         użyć swojego ulubionego edytora plików PO (jak tryb PO Emasca,
         Lokalize lub Gtranslator).

       · gettext udostępnia prosty sposób otrzymania statystyk o tym, co
         zostało zrobione, co powinno być przejrzane i zaktualizowane, a co
         jeszcze jest do zrobienia. Przykłady można znaleźć POD tymi adresami:

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

       Nie wszystko złoto, co się świeci - to podejście ma także kilka
       minusów, z którymi musimy sobie poradzić.

       · Na pierwszy rzut oka załączniki są... dziwne.

       · Nie można dostosowywać tłumaczonego tekstu do własnych upodobań, na
         przykład przez podzielenie w danym miejscu na akapity, połączenie
         dwóch innych akapitów w jeden. Jednak w pewnym sensie, jeżeli jest
         jakiś problem z oryginałem, powinno to zostać zgłoszone jako błąd.

       · Nawet mając łatwy interfejs, wciąż pozostaje nowym narzędziem,
         którego trzeba się uczyć.

         Jednym z moich marzeń jest zintegrowanie w jakiś sposób po4a z
         programami Gtranslator lub Lokalize. Kiedy plik SGML jest otwierany,
         komunikaty zostają automatycznie wyciągane. Kiedy jest zamykany,
         przetłumaczony plik jest zapisywany na dysk. Jeśli uda nam się zrobić
         moduł MS Word (TM) (a przynajmniej RFT), to będą mogli go nawet
         używać profesjonalni tłumacze.

AUTORZY

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