Provided by: po4a_0.52-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
           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.

       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)

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

       - Actually  translate what should be translated. For that, you have to rename the POT file for example to
         doc.XX.po (where XX is the ISO 639-1 code of the language you are translating to, e.g. fr for  French),
         and edit the resulting file. It is often a good idea to not name the file XX.po to avoid confusion with
         the  translation  of  the  program  messages,  but  this your call.  Don't forget to update the PO file
         headers, they are important.

         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>

       As before, <format> is the format used in the master.doc document.  But this time, the PO  file  provided
       with the -p flag is part of the input.  This is your translation. The output goes into 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.

       I cannot emphasize this too much. In order to ease the process, it is thus important that  you  find  the
       exact  version  which  were used to do the translation. The best situation is when you noted down the VCS
       revision used for the translation and you didn't modify it in the translation process, so  that  you  can
       use it.

       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.

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

           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.

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

           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.

       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)
           a  Perl  regexp.  The  addendum  will  be placed near the line matching this regexp.  Note that we're
           speaking about the translated document here, not the  original.  If  more  than  a  line  match  this
           expression  (or  none), the addition will fail. It is indeed better to report an error than inserting
           the addendum at the wrong location.

           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)
           It can be either the string before or after, specifying the position of the addendum, relative to the
           position  point.  In case before is given the insertion point will placed exactly before the position
           point. The after behaviour is detailed bellow.

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

         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 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 later some other section will be added between NAME and AUTHOR sections, it
       will break this example making the addenda to be added before this newly added 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)

       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; # Did not got a defined line? End of input file.
        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).

   Why not put the original as comment along with translation (or the other way around)?
       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:

        |       *****************************************************
        |       *           GENERATED FILE, DO NOT EDIT             *
        |       * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        |       *****************************************************
        |
        | This file was generated by po4a-translate(1). Do not store it (in VCS,
        | for example), but store the PO file used as source file by po4a-translate.
        |
        | In fact, consider this as a binary, and the PO file as a regular source file:
        | If the PO gets lost, keeping this translation up-to-date will be harder ;)

       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:

        #
        #  ADVISES TO DEVELOPERS:
        #    - you do not need to manually edit POT or PO files.
        #    - this file contains the translation of your debconf templates.
        #      Do not replace the translation of your program with this !!
        #        (or your translators will get very upset)
        #
        #  ADVISES TO TRANSLATORS:
        #    If you are not familiar with the PO format, gettext documentation
        #     is worth reading, especially sections dedicated to this format.
        #    For example, run:
        #         info -n '(gettext)PO Files'
        #         info -n '(gettext)Header Entry'
        #
        #    Some information specific to po-debconf are available at
        #            /usr/share/doc/po-debconf/README-trans
        #         or 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ć.

         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>

Narzędzia po4a                                     2017-08-26                                            PO4A(7)