
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             * 
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in cvs, for example),
but store the po file used as source file by pod-translate. 

In fact, consider this as a binary, and the po file as a regular .c file:
If the po get lost, keeping this translation up-to-date will be harder.

=head1 NAZWA

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

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

=head1 Spis treści

Dokument jest zorganizowany następująco:

=over 

=item 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ł.

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

=over 

=item JAK zacząć nowe tłumaczenie?

=item JAK zamienić tłumaczenie z powrotem do pliku dokumentacji?

=item JAK zaktualizować tłumaczenie programem po4a?

=item JAK skonwertować istniejące tłumaczenia do po4a?

=item JAK dodać dodatkowy tekst do tłumaczeń (np. nazwisko tłumacza)?

=item JAK to wszystko zrobić, wywołując tylko jeden program?

=back

 


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

=item 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ą E<lt>po4a-devel@lists.alioth.debian.orgE<gt>. Uwielbiamy
znać opinie użytkowników.

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

=item 6 Znane błędy i żądania nowych funkcjonalności

Już kilka :(

=back

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

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

=head2 Odpowiedzi po4a

Tak więc, celem po4a jest uczynienie tłumaczeń dokumentacji I<ł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 L<FAQ> poniżej opisano kompletną listę plusów i minusów tego
rozwiązania.

=head2 Obsługiwane formaty

Obecnie rozwiązanie to zaimplementowano z sukcesem dla kilku formatów
tekstu:

=head3 nroff

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.

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

=head3 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 L<Locale::Po4a::Sgml(3pm)>.

=head3 inne

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

=head2 Formaty niewspierane

Niestety, w po4a wciąż brakuje obsługi kilku większych formatów
dokumentacji. Najważniejszym może być XML, który jest coraz częściej
używany w dokumentacji programów open-source. Moduł sgml może
dostarczyć ograniczonego wsparcia (działającego głównie wtedy, gdy w
dokumencie XML nie używa się rzeczy specyficznych dla tego
formatu). Pracujemy obecnie nad jego lepszą obsługą i wszystko może
zmienić w najbliższej przyszłości. Tymczasem, jeśli po4a naprawdę nie
odpowiada Twoim wymaganiom, możesz wypróbować narzędzi z projektu poxml,
podobnego do po4a i przyzwoicie radzącego sobie z dokumentacją w formacie
docbook xml. Niestety, nie radzi sobie z żadnym innym formatem. I
oczywiście nie jest tak bardzo cool jak po4a ;)

Inną poważną wadą po4a jest brak Texinfo. Cała dokumentacja GNU jest
napisana w tym formacie (jest to nawet jednym z wymagań, aby projekt stał
się oficjalnym projektem GNU). Brak obsługi tego w po4a pozostawia
tłumaczy GNU samymi sobie wobec przeciwności losu. Chcielibyśmy
pospieszyć z pomocą, ale format jest tak potężny i skomplikowany, że
nie stanie się to tak szybko, jak byśmy chcieli. Jeśli chcesz pomóc, to
Twoja pomoc jest zawsze mile widziana ;)

Poza tymi dwoma głównymi formatami jest cała masa innych, 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 dokumentację pythona, 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.

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

=head2 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 I<cały> proces. Po
skonwertowaniu projektu do po4a, istotna będzie tylko prawa część
schematu. Proszę zauważyć, że sgml występuje tu jako przykład i cały
schemat jest dokładnie taki sam dla wszystkich modułów. Każdą część
rysunku omówimy szczegółowo w następnych sekcjach.

  fr.sgml  oryginalny.sgml ---->------+------>----------->-------+
     |         |                      |                          |
     V         V           { aktualizacja oryginału }            |
     |         |                      |                          |
     +--<---<--+                      V                          |
     |         |              oryginalny.nowy.sgml ---->---->----+
     V         V                      |                          |
  [po4a-gettextize]      +--->---->---+                          |
     |         |         |            V                          |
     |         |         |     [po4a-updatepo]                   |
     |         V         ^            |                          V
     V    oryginalny.pot |            V                          |
     |         |         |          fr.po                        |
     |         |         |      (niepewny - fuzzy)               |
     |  { tłumaczenie }  |            |                          |
     |         |         ^            V                          V
     |         |         |     {ręczna edycja}                   |
     V         V         |            |                          |
     |         |         |            V                          V
     |         |         +--<---    fr.po     załącznik   oryginalny.sgml
     +---->----+---->------->---> (aktualny) (opcjonalny)    (aktualny)
                                      |            |             |
                                      v            v             v
                                      +------>-----+------<------+
                                                   |
                                                   v
                                           [po4a-translate]
                                                   |
                                                   V
                                                fr.sgml
                                              (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...

=head2 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:

=over 2

=item -

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

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

E<lt>formatE<gt> jest oczywiście formatem używanym w dokumencie
E<lt>master.docE<gt>. Jak można oczekiwać, plikiem wyjściowym jest
E<lt>tłumaczenie.potE<gt>. Więcej szczegółów o dostępnych opcjach
można znaleźć w L<po4a-gettextize(1)>.

=item -

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

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

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

=back

=head2 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
L<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, E<lt>formatE<gt> jest formatem dokumentu
E<lt>master.docE<gt>. Jednak tym razem plik po, przekazany w opcji -p, jest
częścią wejścia - jest to Twoje tłumaczenie. Wyjście jest zapisywane w
E<lt>XX.docE<gt>.

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

=head2 JAK zaktualizować tłumaczenie programem po4a?

Aby zaktualizować tłumaczenie, gdy zmieni się oryginalny plik, należy
użyć L<po4a-updatepo(1)> w następujący sposób:

  $ po4a-updatepo -f <format> -m <nowy_oryginalny.doc> -p <istniejący.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
C<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 C<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.



=head2 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. 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
B<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, weźmy jako przykład ponownie moduł sgml, jednak tak
naprawdę użyty format nie ma żadnego znaczenia.

Kiedy już zdobędziesz stary oryginał dokumentu, proces przechodzenia na
gettext może być tak łatwy, jak:

 $ po4a-gettextize -f <format> -m <stary.oryginał> -l <stare.tłumaczenie> -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 L<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 /tmp/gettextization.failed.po.

=over 

=item -

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.

=item -

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.

=item -

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.

=item -

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.

=item -

Czasami zawartości akapitów się zgadzają, ale ich typy nie. Poprawienie
tego zależy od formatu. W formatach pod i nroff, 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.

=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
/tmp/gettextization.failed.po miejsce, gdzie zaczyna się
rozsynchronizowanie, a następnie poprawić w tym miejscu pliki wejściowe.

=item -

Czasami może się wydawać, że po4a zjadło jakąś część tekstu albo z
oryginału, albo z tłumaczenia. /tmp/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).

=back

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.

=head2 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
B<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:

=over 4

=item position (obowiązkowe)

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

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

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

W naszym przypadku byłoby to:

     position=<title>O dokumencie</title>



=item mode (obowiązkowe)

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

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

     mode=after

=item beginboundary (używany, gdy mode=after i obowiązkowy w tym wypadku)

=item endboundary (jak wyżej)

wyrażenie regularne pasujące do końca sekcji, po której jest dodawany
załącznik.

W trybie "after" I<punkt wstawienia> jest za I<punktem pozycji>, ale nie
bezpośrednio za! Jest on umieszczony na końcu sekcji zaczynającej się w
I<punkcie pozycji>, czyli za albo przed linią pasującą do argumentu
C<???boundary> w zależności od tego, czy było użyte C<beginboundary>,
czy C<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 E<lt>/sectionE<gt>, a
przed E<lt>sectionE<gt>. 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 C<E<lt>/sectionE<gt>>,
której właśnie użyliśmy), a inne (np. nroff) tego końca nie oznaczają
w żaden szczególny sposób. W pierwszym przypadku I<boundary> powinno
odpowiadać I<końcowi sekcji>, tak że I<punkt wstawienia> następuje po
niej. W drugim przypadku I<boundary> powinno pasować do I<początku
następnej sekcji>, a I<punkt wstawienia> powinien być umieszczony zaraz
przed nią.

=back

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

=over 2

=item 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>



=item Aby dodać coś po następującej sekcji nroff:

  .SH "AUTORZY"

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

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

=item Aby zamiast dodawać całą sekcję, dodać coś do jakiejś sekcji (np. po 
"Copyright Big Dude"), trzeba podać C<position> pasujące do tej linii i 
C<beginboundary> pasujące do jakiejkolwiek linii.

 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

=item Aby dodać coś na końcu dokumentu, należy podać C<position> pasujące do 
jakiejkolwiek linii pliku (ale tylko jednej linii. Po4a nie przetworzy tego, 
jeśli linia nie będzie unikatowa) i podać C<endboundary> nie pasujące do 
niczego. Nie należy używać tutaj prostych tekstów jak "C<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

=back

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ć C<.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 C<^\.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.

=head3 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

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

=head2 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 L<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ń.

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

=head2 Jaki jest tu duży obrazek?

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

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

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



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

TransTractor::parse() jest wirtualną funkcją zaimplementowaną w każdym
module. Tutaj podano prosty przykład, żeby zobrazować jej
działanie. Przetwarza listę akapitów, z których każdy zaczyna się od
<p>.

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

W linii 6. po raz drugi napotkaliśmy E<lt>pE<gt>. 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 E<lt>pE<gt> 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
L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor(3pm)>.

=head2 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ł.

=head2 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 C<endboundary>, lub przed
nią, jeśli jest to C<beginboundary>.

=head1 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ą E<lt>po4a-devel@lists.alioth.debian.orgE<gt>. Uwielbiamy
znać opinie użytkowników.

=head2 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:

=over 2

=item *

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

=item *

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

=back

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:

=over 2

=item *

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

=item *

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.

=item *

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.

=back

=head2 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ś B<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 L<Locale::Maketext::TPJ13(3pm)|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).

=head2 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:

=over 

=item * 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.

=item * 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]).

=back

gettext rozwiązuje wszystkie te problemy razem.

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

=head2 Co z innymi narzędziami do tłumaczeń dokumentacji wykorzystującymi 
gettext?

O ile mi wiadomo, są tylko dwa takie:

=over 

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

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

=back

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

=head2 Przekazywanie deweloperom wiedzy o tłumaczeniu

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

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

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



 |       ****************************************************
 |       *         PLIK WYGENEROWANY, NIE EDYTOWAĆ          *
 |       * TO NIE JEST PLIK ŹRÓDŁOWY, ALE WYNIK KOMPILACJI  *
 |       ****************************************************
 |
 | Ten plik został wygenerowany przez po4a-translate(2). Nie przechowuj go
 | (na przykład w CVS-iie), 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 B<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
 #

=head2 PODSUMOWANIE plusów i minusów rozwiązania opartego na gettext

=over 2

=item *

Tłumaczenia nie są trzymane wraz z oryginałem, co pozwala w prosty
sposób wykryć, czy tłumaczenia nie są przestarzałe.

=item *

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.

=item *

Wewnętrznie jest oparty na pakiecie C<gettext> (ale C<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.

=item *

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.

=item *

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, kbabel lub
gtranslator).

=item *

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://i18n.kde.org/tools/kbabel/img/previewKonq.png
 - http://www.debian.org/intl/l10n

=back

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

=over 2

=item *

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

=item *

Nie można dostosowywać tłumaczonego tekstu do własnych upodobań, na
przykład przed 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.

=item *

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

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

=back

=head1 Znane błędy i i żądania nowych funkcjonalności

Najważniejszą sprawą (oprócz brakujących modułów) jest obsługa
kodowania znaków. Rozwiązaniem mogłoby być dodanie pragmy Perla UTF-8 i
rekodowanie komunikatów na wyjściu, ale nie jest to jeszcze zrobione.

Chcielibyśmy wydzielić część kodu (dotyczącego wstawiania plików)
modułu sgml z powrotem do TransTractora, tak żeby pozostałe moduły
mogły z niego korzystać, ale to nie będzie zmiana widoczna dla
użytkownika.

=head1 AUTORZY

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


=head1 TŁUMACZENIE

 Robert Luberda <robert@debian.org>

