Provided by: po4a_0.55-1_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
           This chapter groups the Frequently Asked Questions. In fact, most of the questions for
           now could be formulated that way: "Why is it designed this way, and not that one?" If
           you think po4a isn't the right answer to documentation translation, you should
           consider reading this section. If it does not answer your question, please contact us
           on the <devel@lists.po4a.org> mailing list. We love feedback.

       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.

       But the situation is rather different when it comes to documentation. Too often, the
       translated documentation is not visible enough (not distributed as a part of the program),
       only partial, or not up to date. This last situation is by far the worst possible one.
       Outdated translation can turn out to be worse than no translation at all to the users by
       describing old program behavior which are not in use anymore.

   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 zarządzania. 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 can also handle some more rare or specialized formats, such as the documentation of
       compilation options for the 2.4+ Linux kernels or the diagrams produced by the dia tool.
       Adding a new one is often very easy and the main task is to come up with a parser of your
       target format. See Locale::Po4a::TransTractor(3pm) for more information about this.

   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 cały proces. Po skonwertowaniu projektu do po4a, istotna będzie tylko prawa część
       schematu.

       Note that master.doc is taken as an example for the documentation to be translated and
       translation.doc is the corresponding translated text.  The suffix could be .pod, .xml, or
       .sgml depending on its format.  Each part of the picture will be detailed in the next
       sections.

                                          master.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
       {translation}    |         { update of master.doc }             :
            :           |                     |                        :
          XX.doc        |                     V                        V
        (optional)      |                 master.doc ->-------->------>+
            :           |                   (new)                      |
            V           V                     |                        |
         [po4a-gettextize]   doc.XX.po -->+   |                        |
                 |            (old)       |   |                        |
                 |              ^         V   V                        |
                 |              |     [po4a-updatepo]                  |
                 V              |           |                          V
          translation.pot       ^           V                          |
                 |              |        doc.XX.po                     |
                 |              |         (fuzzy)                      |
          { translation }       |           |                          |
                 |              ^           V                          V
                 |              |     {manual editing}                 |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
             (initial)                 (up-to-date)  (optional)   (up-to-date)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                                  [po4a-translate]
                                                         |
                                                         V
                                                       XX.doc
                                                    (up-to-date)

       On the left part, the conversion of a translation not using po4a to this system is shown.
       On the top of the right part, the action of the original author is depicted (updating the
       documentation).  The middle of the right part is where the automatic actions of po4a are
       depicted. The new material are extracted, and compared against the exiting translation.
       Parts which didn't change are found, and previous translation is used. Parts which were
       partially modified are also connected to the previous translation, but with a specific
       marker indicating that the translation must be updated. The bottom of the figure shows how
       a formatted document is built.

       Actually, as a translator, the only manual operation you have to do is the part marked
       {manual editing}. Yeah, I'm sorry, but po4a helps you translate.  It does not translate
       anything for you…

   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 <tłumaczenie.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 tłumaczenie.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 ISO 639-1 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 lub Vi, program Lokalize (oparty na
         KDE), Gtranslator (oparty na GNOME) lub jakikolwiek inny program, w zależności od
         upodobań tłumacza (np. Virtaal).

         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 tłumaczenie.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.

       -   Sometimes, the paragraph content does match, but their types don't. Fixing it is
           rather format-dependent. In POD and man, it often comes from the fact that one of the
           two contains a line beginning with a white space where the other doesn't. In those
           formats, such paragraph cannot be wrapped and thus become a different type. Just
           remove the space and you are fine. It may also be a typo in the tag name.

           Likewise, two paragraphs may get merged together in POD when the separating line
           contains some spaces, or when there is no empty line between the =item line and the
           content of the item.

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

       -   Sometimes, you get the strong feeling that po4a ate some parts of the text, either the
           original or the translation. gettextization.failed.po indicates that both of them were
           gently matching, and then the gettextization fails because it tried to match one
           paragraph with the one after (or before) the right one, as if the right one
           disappeared. Curse po4a as I did when it first happened to me. Generously.

           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.

           So, when the same paragraph appears twice in the original but both are not translated
           in the exact same way each time, you will get the feeling that a paragraph of the
           original disappeared. Just kill the new translation. If you prefer to kill the first
           translation instead when the second one was actually better, replace the first one
           with the second.

           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.

       The header line which specify context has a pretty rigid syntax: It must begin with the
       string PO4A-HEADER:, followed by a semi-colon (;) separated list of key=value fields.
       White spaces ARE important. Note that you cannot use the semi-colon char (;) in the value,
       and that quoting it doesn't help.  Optionally, spaces ( ) may be inserted before key for
       readability.

       Although this context search may be considered to operate roughly on each line of the
       translated document, it actually operates on the internal data string of the translated
       document.  This internal data string may be a text spanning a paragraph containing
       multiple lines or may be a XML tag itself alone.  The exact insertion point of the
       addendum must be before or after the internal data string and can not be within the
       internal data string.

       The actual internal data string of the translated document can be visualized by executing
       po4a in debug mode.

       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:

       mode (obowiązkowe)
           It can be either the string before or after.

           If mode=before, the insertion point is determined by one step regex match specified by
           the position argument regex.  The insertion point is immediately before the uniquely
           matched internal data string of the translated document.

           If mode=after, the insertion point is determined by two step regex matches specified
           by the position argument regex; and by the beginboundary or endboundary argument
           regex.

           Since there may be multiple sections for the assumed case, let's use 2 step approach.

                mode=after

       position (obowiązkowe)
           A Perl regexp for specifying the context.

           If more than one internal data strings match this expression (or none), the search for
           the insertion point and addition of the addendum will fail. It is indeed better to
           report an error than inserting the addendum at the wrong location.

           If mode=before, the insertion point is specified to be immediately before the internal
           data string uniquely matching the position argument regex.

           If mode=after, the search for the insertion point is narrowed down to the data after
           the internal data string uniquely matching the position argument regex.  The exact
           insertion point is further specified by the beginboundary or endboundary.

           In our case, we need to skip several preceding sections by narrowing down search using
           the section title string.

                position=About this document

           (In reality, you need to use the translated section title string here, instead.)

       beginboundary (używany, gdy mode=after i obowiązkowy w tym wypadku)
       endboundary (jak wyżej)
           A second Perl regexp required only when mode=after. The addendum will be placed
           immediately before or after the first internal data string matching the beginboundary
           or endboundary argument regexp, respectively.

           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>

           In both cases, our addendum will be placed after the </section> and before the
           <section>. The first one is better since it will work even if the document gets
           reorganized.

           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ć końcowi sekcji, tak że punkt wstawienia następuje po niej. W drugim
           przypadku boundary powinno pasować do początku następnej 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"

         You should select two step approach by setting mode=after.  Then you should narrow down
         search to the line after AUTHORS with the position argument regex.  Then, you should
         match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument
         regex. That is to say:

          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=About this document;beginboundary=FakePo4aBoundary

       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 szczegółowy przykład

       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

       This works because the next line matching the beginboundary /^=head1/ after the section
       "NAME" (translated to "NOM" in French), is the one declaring the authors. So, the addendum
       will be put between both sections. Note that if another section is added between NAME and
       AUTHOR sections later, po4a will wrongfully put the addenda before the new section.

       To avoid this you may accomplish the same using mode=before:

        PO4A-HEADER:mode=before;position=^=head1 AUTEUR

   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.

       Then, calling po4a(1) on this file ensures that the PO files are synchronized against the
       original document, and that the translated document are generated properly. Of course, you
       will want to call this program twice: once before editing the PO files to update them and
       once afterward to get a completely updated translated document. But you only need to
       remember one command line.

   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.

       You can also edit the source code of the existing modules or even write your own modules.
       To make them visible to po4a, copy your modules into a path called
       "/bli/blah/blu/lib/Locale/Po4a/" and then adding the path "/bli/blah/blu" in the "PERLIB"
       or "PERL5LIB" environment variable. For example:

          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)

       This little bone is the core of all the po4a architecture. If you omit the input PO and
       the output document, you get po4a-gettextize. If you provide both input and disregard the
       output PO, you get po4a-translate.  The po4a calls TransTractor twice and calls msgmerge
       -U between these TransTractor invocations to provide one-stop solution with a single
       configuration file.

       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 }

       On line 6 and 7, we encounter "shiftline()" and "unshiftline()".  These help you to read
       and unread the head of internal input data stream of master document into the line string
       and its reference.  Here, the reference is provided by a string "$filename:$linenum".
       Please remember Perl only has one dimensional array data structure.  So codes handling the
       internal input data stream line are a bit cryptic.

       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.

       Isn't that cool? It is possible to build a complete po4a module in less than 20 lines when
       the format is simple enough…

       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

       This chapter groups the Frequently Asked Questions. In fact, most of the questions for now
       could be formulated that way: "Why is it designed this way, and not that one?" If you
       think po4a isn't the right answer to documentation translation, you should consider
       reading this section. If it does not answer your question, please contact us on the
       <devel@lists.po4a.org> mailing list. We love feedback.

   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.

       In the po4a project, translated documents are not source files anymore, in the sense that
       these files are not the preferred form of the work for making modifications to it. Since
       this is rather unconventional, that's a source of easy mistakes. That's why all files
       present this header:

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

          - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
          - 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ć.

       · Addenda are… strange at the first glance.

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

         One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a
         documentation file is opened, the strings are automatically extracted, and a translated
         file + po file can be written to disk. If we manage to do an MS Word (TM) module (or at
         least RTF) professional translators may even use it.

AUTORZY

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

TŁUMACZENIE

        Robert Luberda <robert@debian.org>