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

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ą <devel@lists.po4a.org>. Uwielbiamy znać opinie
użytkowników.

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

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

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

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

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

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

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

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

Odpowiedzi po4a
Tak więc, celem po4a jest uczynienie tłumaczeń dokumentacji łatwymi do 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 może także obsługiwać kilka rzadszych lub bardziej specjalizowanych formatów, takich jak
dokumentacja opcji kompilacji jąder Linuksa 2.4+ lub diagramów wyprodukowanych przez narzędzie dia.
Dodanie nowego formatu jest często bardzo proste, a głównym zadaniem jest napisanie parsera tego formatu.
Więcej informacji o tym można znaleźć w Locale::Po4a::TransTractor(3pm).

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

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

Jak używać po4a?

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

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

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

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

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

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

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

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

- Wyciągnąć tekst do przetłumaczenia z oryginalnego dokumentu <master.doc> do nowego szablonu pliku
<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 ;)

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

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

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

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

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

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

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

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

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

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

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

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

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

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=O dokumencie

(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=O dokumencie;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):

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

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.

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

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

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.

       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ą <devel@lists.po4a.org>. Uwielbiamy znać opinie użytkowników.

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

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

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

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

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

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

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

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

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

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

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

To dlatego opiekun debconfa zdecydował zaimplementować inne rozwiązanie, w którym tłumaczenia są
umieszczane w tym samym pliku, co oryginał. Jest to pociągające. Ktoś mógłby nawet chcieć coś takiego
zrobić dla XML-a na przykład. Mógłby on wyglądać tak:

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

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

Jednak było to na tyle problematyczne, że obecnie jest używane rozwiązanie oparte na plikach PO. Tylko
oryginalny tekst może być edytowany w pliku, a tłumaczenia muszą się pojawić w plikach PO, wyciągniętych
z głównego szablonu (łączonych z powrotem w czasie kompilacji pakietu). Ten stary system jest potępiany z
kilku powodów:

• problemy w zarządzaniu

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

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

• problemy z kodowaniem znaków

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

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

gettext rozwiązuje wszystkie te problemy razem.

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

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

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

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

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

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

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

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

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

• 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                                     2020-04-15                                            PO4A(7)