PO4A.7(7)

NAZWA
po4a - narzedzia do tXumaczen~ dokumentacji i innych materiaXow

Wstep
Celem projektu po4a ("po for anything") jest uXatwienie tXumaczen~ (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzedzi gettext w tych obszarach, gdzie nie byXy uXywane, jak na przykXad w obszarze dokumentacji.

Spis treXci
Dokument jest zorganizowany nastepujXco:

1. Dlaczego powinno sie uXywaae po4a? Jakie sX jego zalety?
    Ten rozdziaX wprowadzenia wyjaXnia motywy i filozofie projektu. JeXeli rozwaXasz uXycie po4a do Twoich tXumaczen~, powinieneX najpierw przeczytaae ten rozdziaX.

2. Jak uXywaae po4a?
    RozdziaX ten jest rodzajem podrecznika i probuje odpowiedzieae na pytania uXytkownikow, pozwalajXc lepiej zrozumieae caXy proces. Odpowiada, jak wykonaae roXne rzeczy w po4a, i sXuXy jako wprowadzenie do dokumentacji konkretnych narzedzi.

    JAK zaczXae nowe tXumaczenie?
    JAK zamieniae tXumaczenie z powrotem do pliku dokumentacji?
    JAK zaktualizowaae tXumaczenie programem po4a?
    JAK skonwertowaae istniejXce tXumaczenia do po4a?
    JAK dodaae dodatkowy tekst do tXumaczen~ (np. nazwisko tXumacza)?
    JAK to wszystko zrobiae, wywoXujXc tylko jeden program?
3 Jak to dziaXa?
    Ten rozdziaX zawiera krotki opis wewnetrznych mechanizmow po4a, tak Xe bedziesz miaX wiecej odwagi, aby pomoc nam w jego tworzeniu i udoskonalaniu. MoXe takXe Ci pomoc w zrozumieniu, dlaczego nie dziaXa tak, jak byX tego oczekiwaX, oraz jak rozwiXzaae napotkane problemy.

4 FAQ
    Ten rozdziaX zawiera odpowiedzi na czesto zadawane pytania. Tak naprawde, wiekszoXae tych pytan~ moXe byae sformuXowanych jako "Dlaczego po4a zostaXo zaprojektowane tak, a nie inaczej?". JeXli wydaje Ci sie, Xe po4a nie jest wXaXciwym narzedziem do tXumaczenia dokumentacji, powinieneX rozwaXyae przeczytanie tego rozdziaXu. JeXli nie znajdziesz w nim odpowiedzi na swoje pytanie, prosimy sie z nami skontaktowaae poprzez liste dyskusyjnX <po4a-devel@lists.alioth.debian.org>. Uwielbiamy znaae opinie uXytkownikow.

5 Specyficzne uwagi o moduXach
    Ten rozdziaX opisuje rzeczy specyficzne dla kaXdego moduXu, z punktu widzenia zarowno tXumacza, jak i autora oryginalnego dokumentu. CzytajXc ten rozdziaX, dowiesz sie, kiedy dany moduX wykonuje tXumaczenia oraz jakich zasad powinieneX przestrzegaae, piszXc oryginalny dokument, aby uproXciae Xycie tXumaczom.

    W zasadzie, ta sekcja nie jest czeXciX tego dokumentu. Zamiast tego jest umieszczana w dokumentacji kaXdego moduXu. Pomaga to w zapewnieniu aktualnoXci tych informacji, trzymajXc kod i dokumentacje razem.

6 Znane bXedy i XXdania nowych funkcjonalnoXci
    JuX kilka :(

Dlaczego uXywaae po4a? Do czego jest on przydatny?
Podoba mi sie idea wolnego oprogramowania, pozwalajXcego kaXdemu na dostep do programow i ich kodow XrodXowych. BedXc jednak Francuzem, jestem Xwiadomy tego, Xe licencja programu nie jest jedynym ograniczeniem otwartoXci oprogramowania: nieprzetXumaczone oprogramowanie jest bezuXyteczne dla ludzi nieznajXcych angielskiego, wiec ciXgle czeka na nas duXo pracy, Xeby udostepniae je kaXdej takiej osobie.

XwiadomoXae tego problemu wXrod osob zwiXzanych z oprogramowaniem open-source ostatnio znacznie wzrosXa. WygraliXmy, jako tXumacze, pierwszX bitwe i przekonaliXmy wszystkich o znaczeniu tXumaczen~. Niestety, to byXa ta Xatwiejsza czeXae. Teraz musimy wykonaae naszX prace i przetXumaczyae wszystkie te rzeczy.

WXaXciwie oprogramowanie typu open-source ma doXae przyzwoity poziom tXumaczen~, dzieki wspaniaXemu pakietowi gettext, ktory ma moXliwoXci wyodrebniania z programu komunikatow do przetXumaczenia, przekazywania tXumaczom plikow w jednolitym formacie i uXywania wynikow ich pracy do pokazywania uXytkownikowi przetXumaczonych komunikatow w czasie dziaXania programu.

W przypadku dokumentacji sytuacja jest troche inna. Zbyt czesto sie zdarza, Xe tXumaczony dokument nie jest dostatecznie widoczny (nie jest dystrybuowany jako czeXae programu), jest tylko czeXciowy lub nie jest aktualny. Ostatnia sytuacja jest najgorszX z moXliwych. PrzestarzaXe tXumaczenie, opisujXce stare, juX nieistniejXce zachowanie programu, moXe byae o wiele gorsze dla uXytkownika niX brak tXumaczenia w ogole.

  Problem do rozwiXzania
TXumaczenie dokumentacji samo w sobie nie jest zbyt trudne. Teksty sX duXo dXuXsze niX komunikaty wyXwietlane przez program, wiec ich tXumaczenie zajmuje troche wiecej czasu, nie wymaga przy tym jednak Xadnych umiejetnoXci technicznych. TrudniejszX czeXciX pracy jest zarzXdzanie tXumaczeniem. Wykrywanie czeXci, ktore sie zmieniXy i powinny byae zaktualizowane, jest bardzo trudne, podatne na bXedy i wysoce nieprzyjemne. Najprawdopodobniej wyjaXnia to, dlaczego tak wiele przetXumaczonej dokumentacji nie jest aktualne.

  Odpowiedzi po4a
Tak wiec, celem po4a jest uczynienie tXumaczen~ dokumentacji Xatwymi do zarzXdzania. IdeX jest wykorzystanie metodologii gettexta na tym nowym polu. Tak jak w programie gettext, teksty sX wyodrebniane z ich oryginalnych miejsc, aby mogXy w jednolitym formacie zostaae zaprezentowane tXumaczowi. Klasyczne narzedzia gettexta pomogX im uaktualniae ich prace, kiedy pojawi sie nowa wersja oryginalnego dokumentu. W przeciwien~stwie zaX do klasycznego modelu gettext, tXumaczenia sX wstawiane do struktury oryginalnego dokumentu, tak Xeby mogXy byae przetwarzane i dystrybuowane w dokXadnie taki sam sposob, co wersja angielska.

Dzieki temu staXo sie Xatwiejsze znalezienie do przetXumaczenia zmienionych czeXci dokumentu. Innym plusem jest to, Xe w wypadku zasadniczej reorganizacji struktury dokumentu, gdy rozdziaXy sX przesuwane, XXczone lub dzielone, narzedzia wykonajX prawie caXX brudnX robote. Wyodrebnianie ze struktury dokumentu tekstow do przetXumaczenia pozwala tXumaczom nie przejmowaae sie zXoXonoXciX struktury dokumentu i zmniejsza szanse otrzymania dokumentu o niepoprawnej strukturze (choae zawsze jest to moXliwe).

W sekcji FAQ poniXej opisano kompletnX liste plusow i minusow tego rozwiXzania.

  ObsXugiwane formaty
Obecnie rozwiXzanie to zaimplementowano z sukcesem dla kilku formatow tekstu:

nroff

Format starych, dobrych stron podrecznika ekranowego, uXywanego przez wiele programow. ObsXuga tego formatu w po4a jest mile widziana, poniewaX ten format jest raczej trudny w uXyciu i niezbyt przyjazny dla nowych uXytkownikow.

pod

Jest to format dokumentacji Perla. W ten sposob jest udokumentowany sam jezyk i jego rozszerzenia, a takXe wiekszoXae istniejXcych skryptow Perla. XXczenie dokumentacji i kodu w jednym pliku, pomaga utrzymywaae aktualnoXae dokumentacji. Upraszcza to Xycie programisty, ale niestety, nie tXumacza.

sgml

Nawet jeXli jest obecnie wypierany przez XML, ten format jest wciXX raczej czesto uXywany w dokumentach o dXugoXci wiekszej niX kilka ekranow. Pozwala tworzyae kompletne ksiXXki. Aktualizowane tXumaczen~ tak dXugich dokumentow moXe byae prawdziwym koszmarem. Program diff bardzo czesto okazuje sie bezuXyteczny, jeXli zmieni sie struktura oryginalnego tekstu. Na szczeXcie, z pomocX moXe przyjXae po4a.

Obecnie obsXugiwane sX tylko DTD debiandoc i docbook, ale dodanie obsXugi nowego typu jest bardzo proste. Jest nawet moXliwe uXycie po4a z nieznanym DTD SGML bez zmiany kodu - przez podanie wymaganych informacji w parametrach linii polecen~. SzczegoXy moXna znaleXae w Locale::Po4a::Sgml(3pm).

inne

Po4a moXe takXe obsXugiwaae kilka rzadszych lub bardziej specjalizowanych formatow, takich jak dokumentacja opcji kompilacji jXder 2.4 lub diagramow wyprodukowanych przez narzedzie dia. Dodanie nowego formatu jest czesto bardzo proste, a gXownym zadaniem jest napisanie parsera tego formatu. Wiecej informacji o tym moXna znaleXae w Locale::Po4a::TransTractor(3pm).

  Formaty niewspierane
Niestety, w po4a wciXX brakuje obsXugi kilku wiekszych formatow dokumentacji. NajwaXniejszym moXe byae XML, ktory jest coraz czeXciej uXywany w dokumentacji programow open-source. ModuX sgml moXe dostarczyae ograniczonego wsparcia (dziaXajXcego gXownie wtedy, gdy w dokumencie XML nie uXywa sie rzeczy specyficznych dla tego formatu). Pracujemy obecnie nad jego lepszX obsXugX i wszystko moXe zmieniae w najbliXszej przyszXoXci. Tymczasem, jeXli po4a naprawde nie odpowiada Twoim wymaganiom, moXesz wyprobowaae narzedzi z projektu poxml, podobnego do po4a i przyzwoicie radzXcego sobie z dokumentacjX w formacie docbook xml. Niestety, nie radzi sobie z Xadnym innym formatem. I oczywiXcie nie jest tak bardzo cool jak po4a ;)

InnX powaXnX wadX po4a jest brak Texinfo. CaXa dokumentacja GNU jest napisana w tym formacie (jest to nawet jednym z wymagan~, aby projekt staX sie oficjalnym projektem GNU). Brak obsXugi tego w po4a pozostawia tXumaczy GNU samymi sobie wobec przeciwnoXci losu. ChcielibyXmy pospieszyae z pomocX, ale format jest tak poteXny i skomplikowany, Xe nie stanie sie to tak szybko, jak byXmy chcieli. JeXli chcesz pomoc, to Twoja pomoc jest zawsze mile widziana ;)

Poza tymi dwoma gXownymi formatami jest caXa masa innych, ktore byXmy chcieli obsXugiwaae w po4a. I nie sX to tylko formaty dokumentacji. W zasadzie, naszym celem jest wypeXnienie wszystkich dziur pozostawionych przez klasyczne narzedzia gettext. Obejmuje to dokumentacje pythona, opisy pakietow (deb i rpm), pytania skryptow instalacyjnych pakietow, logi zmian pakietow i wszystkie specjalizowane formaty uXywane przez programy, jak na przykXad scenariusze gier lub pliki zasobow wine.

Jak uXywaae po4a?
RozdziaX ten jest rodzajem podrecznika i probuje odpowiedzieae na pytania uXytkownikow, pozwalajXc lepiej zrozumieae caXy proces. Odpowiada, jak wykonaae roXne rzeczy w po4a, i sXuXy jako wprowadzenie do dokumentacji konkretnych narzedzi.

  Graficzne podsumowanie
NastepujXcy schemat pokazuje poglXdowo proces tXumaczenia dokumentacji z uXyciem po4a. Nie powinno sie przejmowaae jego pozornX zXoXonoXciX, ktora wzieXa sie stXd, Xe pokazaliXmy tutaj caXy proces. Po skonwertowaniu projektu do po4a, istotna bedzie tylko prawa czeXae schematu. Prosze zauwaXyae, Xe sgml wystepuje tu jako przykXad i caXy schemat jest dokXadnie taki sam dla wszystkich moduXow. KaXdX czeXae rysunku omowimy szczegoXowo w nastepnych sekcjach.

  fr.sgml  oryginalny.sgml ---->------+------>----------->-------+
     |         |                      |                          |
     V         V           { aktualizacja oryginaXu }            |
     |         |                      |                          |
     +--<---<--+                      V                          |
     |         |              oryginalny.nowy.sgml ---->---->----+
     V         V                      |                          |
  [po4a-gettextize]      +--->---->---+                          |
     |         |         |            V                          |
     |         |         |     [po4a-updatepo]                   |
     |         V         ^            |                          V
     V    oryginalny.pot |            V                          |
     |         |         |          fr.po                        |
     |         |         |      (niepewny - fuzzy)               |
     |  { tXumaczenie }  |            |                          |
     |         |         ^            V                          V
     |         |         |     {reczna edycja}                   |
     V         V         |            |                          |
     |         |         |            V                          V
     |         |         +--<---    fr.po     zaXXcznik   oryginalny.sgml
     +---->----+---->------->---> (aktualny) (opcjonalny)    (aktualny)
                                      |            |             |
                                      v            v             v
                                      +------>-----+------<------+
                                                   |
                                                   v
                                           [po4a-translate]
                                                   |
                                                   V
                                                fr.sgml
                                              (aktualny)

Lewa czeXae pokazuje konwersje tXumaczenia nie uXywajXcego jeszcze po4a do tego systemu. Gora prawej czeXci pokazuje akcje autora oryginaXu (aktualizowanie dokumentacji). Xrodek prawej czeXci obrazuje automatyczne akcje po4a. Nowy materiaX jest wyodrebniany i porownywany z istniejXcymi tXumaczeniami. Znajdowane sX czeXci, ktore sie nie zmieniXy, i dla nich uXywane jest poprzednie tXumaczenie. CzeXci zmodyfikowane tylko w nieznacznym stopniu sX takXe XXczone z poprzednimi tXumaczeniami, ale dodawany jest specjalny znacznik, mowiXcy, Xe tXumaczenie musi byae uaktualnione. DoX rysunku pokazuje sposob, w jaki jest budowany sformatowany dokument.

WXaXciwie, jedynX recznX operacjX, ktorX musi wykonaae tXumacz jest czeXae oznaczona {reczna edycja}. Przykro nam, po4a tylko pomaga tXumaczyae, ale niestety niczego za Ciebie nie przetXumaczy...

  JAK zaczXae nowe tXumaczenie?
Ta sekcja opisuje kroki niezbedne do rozpoczecia nowego tXumaczenia z uXyciem po4a. Konwertowanie istniejXcego projektu do tego systemu opisano w szczegoXach w odpowiedniej sekcji.

Aby zaczXae nowe tXumaczenie, uXywajXc po4a, naleXy wykonaae nastepujXce kroki:

-   WyciXgnXae tekst do przetXumaczenia z oryginalnego dokumentu do nowego pliku pot (format programu gettext). Aby to zrobiae, naleXy wywoXaae program po4a-gettextize w nastepujXcy sposob:

      $ po4a-gettextize -f <format> -m <master.doc> -p <tXumaczenie.pot>

    <format> jest oczywiXcie formatem uXywanym w dokumencie <master.doc>. Jak moXna oczekiwaae, plikiem wyjXciowym jest <tXumaczenie.pot>. Wiecej szczegoXow o dostepnych opcjach moXna znaleXae w po4a-gettextize(1).

-   PrzetXumaczyae to, co jest do przetXumaczenia. W tym celu naleXy zmieniae nazwe pliku pot na przykXad na doc.XX.po (gdzie XX jest kodem ISO639 jezyka, na ktory sie tXumaczy, np. "fr" dla jezyka francuskiego) i edytowaae powstaXy plik. Zazwyczaj dobrym pomysXem jest nienazywanie tego pliku XX.po, aby uniknXae pomylenia z tXumaczeniem komunikatow programu, ale wybor naleXy do Ciebie. Prosze nie zapominaae o uaktualnieniu nagXowkow pliku po; sX one bardzo waXne.

    Do tXumaczenia moXna wykorzystaae tryb po Emacsa, program kbabel (oparty na KDE) lub gtranslator (oparty na GNOME) lub jakikolwiek inny program, w zaleXnoXci od upodoban~ tXumacza. MoXna nawet uXyae dobrego starego edytora vi, mimo Xe nie ma on specjalnego trybu uXatwiajXcego tXumaczenia.

    Aby dowiedzieae sie czegoX wiecej, stanowczo powinno sie przeczytaae dokumentacje programu gettext, dostepnX w pakiecie gettext-doc.

  JAK zamieniae tXumaczenie z powrotem do pliku dokumentacji?
Po zakon~czeniu tXumaczenia zapewne naleXaXoby wygenerowaae przetXumaczone dokumenty i rozdystrybuowaae je wXrod uXytkownikow, razem z oryginalnymi dokumentami. Aby to zrobiae, naleXy uXyae programu po4a-translate(1) w ten sposob (XX jest kodem jezyka):

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

Jak wczeXniej, <format> jest formatem dokumentu <master.doc>. Jednak tym razem plik po, przekazany w opcji -p, jest czeXciX wejXcia - jest to Twoje tXumaczenie. WyjXcie jest zapisywane w <XX.doc>.

Wiecej szczegoXow moXna znaleXae w <po4a-translate(1)>.

  JAK zaktualizowaae tXumaczenie programem po4a?
Aby zaktualizowaae tXumaczenie, gdy zmieni sie oryginalny plik, naleXy uXyae po4a-updatepo(1) w nastepujXcy sposob:

  $ po4a-updatepo -f <format> -m <nowy_oryginalny.doc> -p <istniejXcy.XX.po>

(Wiecej szczegoXow moXna znaleXae w <po4a-updatepo(1)>).

OczywiXcie ta operacja nie spowoduje automagicznego przetXumaczenia nowych akapitow oryginalnego dokumentu. NaleXy recznie uaktualniae plik "po". Podobnie naleXy zaktualizowaae tXumaczenie akapitow, ktore sie choae troche zmieniXy. Aby mieae pewnoXae, Xe Xadnego z nich nie ominiesz, zostaXy one zaznaczone jako "fuzzy" (niepewne) i zanim po4a-translate bedzie mogX ich uXyae, to zaznaczenie musi zostaae usuniete. Tak jak w przypadku pierwszego tXumaczenia najlepiej jest uXyae ulubionego edytora.

Kiedy plik "po" bedzie znowu aktualny, bez Xadnych wpisow nieprzetXumaczonych lub niepewnych ("fuzzy"), moXna wygenerowaae przetXumaczony plik dokumentacji, tak jak to opisano w poprzedniej sekcji.

  JAK skonwertowaae istniejXce tXumaczenia do po4a?
Czesto sie zdarzaXo, Xe tXumaczyXeX dokument recznie dopoty, dopoki nie nastXpiXa wieksza reorganizacja oryginalnego dokumentu. W tej sytuacji, po kilku nieprzyjemnych probach z diffem lub podobnymi narzedziami, moXesz zechcieae skonwertowaae dokument do po4a. OczywiXcie naleXy go skonwertowaae tak, aby nie utraciae istniejXcych tXumaczen~. Nie naleXy sie obawiaae, ten przypadek takXe jest obsXugiwany przez po4a i jest nazywany procesem przechodzenia do formatu gettext.

KluczowX kwestiX jest to, aby struktura tXumaczonego dokumentu byXa taka sama jak oryginaXu, tak Xeby narzedzia mogXy odpowiednio dopasowaae zawartoXae.

JeXli masz szczeXcie (tj. struktura obu dokumentow dokXadnie do siebie pasuje), wszystko zadziaXa bez Xadnego problemu i bedzie gotowe w ciXgu paru sekund. W przeciwnym razie moXesz zrozumieae dlaczego ten proces ma takX brzydkX nazwe i przygotuj sie na doXae nieprzyjemnX prace. W kaXdym razie, pamietaj, Xe jest to cena za komfort, ktory poXniej dostarczy po4a. Dobre w tym wszystkim jest to, Xe trzeba to zrobiae tylko raz.

Nie bede sie dXugo nad tym rozwodziX. Aby uXatwiae proces, waXne jest znalezienie dokXadnie tej wersji oryginaXu, ktora byXa przetXumaczona. Najlepiej, jeXli zanotowaXeX sobie wersje z CVS-u dokumentu uXytego do tXumaczenia i jej nie modyfikowaXeX w procesie tXumaczenia, tak Xe moXesz jej teraz uXyae.

Nie zadziaXa to dobrze, jeXli uXyje sie uaktualnionego tekstu oryginaXu ze starym tXumaczeniem. Pozostaje to moXliwe, ale jest to trudniejsze i naprawde powinno sie tego unikaae, gdy tylko jest to moXliwe. JeXeli nie udaXo Ci sie znaleXae ponownie starego oryginaXu, to najlepszym rozwiXzaniem jest znalezienie kogoX, kto przeprowadzi za Ciebie proces przechodzenia na format gettext (ale, prosze, niech nie bede to ja ;).

Byae moXe zbytnio w tym momencie dramatyzuje. Jednak nawet, gdy proces sie nie udaje, pozostaje mimo wszystko szybszX drogX niX tXumaczenie wszystkiego od nowa. UdaXo mi sie przepuXciae przez ten proces francuskie tXumaczenie dokumentacji Perla w ciXgu jednego dnia, nawet wtedy, gdy wszystko szXo Xle. ByXo to ponad dwa megabajty tekstu, ktorego tXumaczenie od nowa trwaXoby miesiXcami lub dXuXej.

Prosze najpierw pozwoliae mi wyjaXniae podstawy tej procedury, a potem powroce do wskazowek, co zrobiae, gdy proces sie nie udaje. Dla lepszego zrozumienia, weXmy jako przykXad ponownie moduX sgml, jednak tak naprawde uXyty format nie ma Xadnego znaczenia.

Kiedy juX zdobedziesz stary oryginaX dokumentu, proces przechodzenia na gettext moXe byae tak Xatwy, jak:

 $ po4a-gettextize -f <format> -m <stary.oryginaX> -l <stare.tXumaczenie> -p <doc-XX.po>

JeXli masz szczeXcie, to to wszystko. Stare tXumaczenia zostaXy skonwertowane do po4a i moXna od razu zaczXae ich aktualizowanie. NaleXy tylko trzymajXc sie procedury opisanej kilka sekcji wczeXniej, zsynchronizowaae plik po z najnowszym oryginalnym dokumentem i odpowiednio zaktualizowaae tXumaczenia.

Prosze zauwaXyae, Xe nawet jeXli wydaje sie, Xe wszystko zadziaXaXo poprawnie, moXe sie okazaae, Xe jednak wystXpiXy bXedy podczas tego procesu. Po4a nie rozumie przetwarzanych tekstow, wiec nie moXe byae byae pewne, Xe tXumaczenia sX poprawnie przypisane do oryginaXow. Dlatego wszystkie komunikaty sX oznaczone jako "fuzzy" (niepewne). Przed usunieciem tych znacznikow, prosze uwaXnie sprawdziae kaXde tXumaczenie.

Bardzo czesto struktury dokumentow nie pasujX dokXadnie do siebie, przez co po4a-gettextize nie moXe poprawnie wykonaae swojego zadania. W tym punkcie gra toczy sie o to, aby tak pozmieniaae pliki, aby ich cholerne struktury sobie odpowiadaXy.

Pomocne moXe byae przeczytanie poniXej sekcji "Proces przeksztaXcania do formatu gettext: jak to dziaXa?". Zrozumienie wewnetrznych procesow pomoXe wykonaae zadanie. Plusem jest to, Xe w razie niepowodzenia, po4a-gettextize gXoXno powie, co poszXo Xle, umoXliwiajXc poznanie komunikatow, ktore do siebie nie pasowaXy, ich pozycje w tekXcie i typ kaXdego z nich. Co wiecej, plik po wygenerowany do tej pory, bedzie zachowany jako /tmp/gettextization.failed.po.

-   NaleXy usunXae wszystkie dodatkowe czeXci tXumaczenia, takie jak sekcja, w ktorej podano nazwisko tXumacza i podziekowania dla wszystkich ludzi, ktorzy pomagali przy tXumaczeniu. PoXniej takie czeXci bedzie moXna z powrotem dodaae, uXywajXc zaXXcznikow, opisanych w nastepnym rozdziale.

-   Nie wahaj sie edytowaae zarowno pliku oryginalnego, jak i jego tXumaczenia. NajwaXniejszX rzeczX jest otrzymanie pliku po. Potem bedzie moXna go zaktualizowaae. Edytowanie tXumaczen~ powinno byae jednak preferowane, poniewaX uproXci to pewne rzeczy po zakon~czeniu sie procesu przeksztaXcania na format gettext.

-   JeXli jest taka potrzeba, naleXy usunXae kilka czeXci oryginalnego dokumentu, ktore nie sX przetXumaczone. PoXniej podczas synchronizowania po z dokumentem czeXci te sie pojawiX same.

-   JeXli w niewielkim stopniu zmieniXeX strukture dokumentu (poXXczenie dwoch akapitow, albo podzielenie innego akapitu), wycofaj te zmiany. JeXli te zmiany miaXy zwiXzek z problemami wystepujXcym w oryginalnym dokumencie, powinieneX poinformowaae o nich jego autora. KorzyXci z poprawienie ich tylko w Twoim tXumaczeniu bedzie miaXa tyko czeXae spoXecznoXci. Co wiecej, takie poprawki nie sX moXliwe, gdy sie uXywa po4a.

-   Czasami zawartoXci akapitow sie zgadzajX, ale ich typy nie. Poprawienie tego zaleXy od formatu. W formatach pod i nroff, czesto bierze sie to z tego, Xe jeden z tych dwoch akapitow zawiera linie zaczynajXcX sie od biaXego znaku, a drugi - nie. W tych formatach tekst takich akapitow nie moXe byae zawijany i dlatego wystepuje niezgodnoXae typow. RozwiXzaniem jest usuniecie spacji. MoXe to byae takXe literowka w nazwie elementu.

    Podobnie, dwa akapity mogX zostaae scalone razem w formacie pod, jeXeli rozdzielajXca linia zawiera spacje lub kiedy brakuje pustej linii przed liniX ==item i zawartoXciX tego elementu.

-   Czasami wystepuje rozsynchronizowanie miedzy plikami i tXumaczenie jest przypisane do zXego akapitu oryginaXu. Jest to oznaka, Xe w rzeczywistoXci problem leXy w plikach. Prosze znaleXae w /tmp/gettextization.failed.po miejsce, gdzie zaczyna sie rozsynchronizowanie, a nastepnie poprawiae w tym miejscu pliki wejXciowe.

-   Czasami moXe sie wydawaae, Xe po4a zjadXo jakXX czeXae tekstu albo z oryginaXu, albo z tXumaczenia. /tmp/gettextization.failed.po wskazuje, Xe oba pliki dokXadnie do siebie pasowaXy, a przetwarzanie kon~czy sie bXedem poniewaX nastXpiXa proba dopasowania jakiegoX akapitu do akapitu po (lub przed) tym wXaXciwym, tak jakby ten wXaXciwy sie ulotniX. MoXna tylko klXae na po4a, tak jak ja klXXem, gdy mi sie to zdarzyXo po raz pierwszy. Serio.

    Ta nieszczeXliwa sytuacja zdarza sie, kiedy ten sam akapit jest powtorzony w dokumencie. W tym przypadku nie jest tworzony nowy wpis w pliku po, ale dodawane jest tylko nowe odwoXanie do juX istniejXcego wpisu.

    Tak wiec, kiedy ten sam akapit pojawia sie dwa razy w oryginalnym dokumencie, ale nie jest przetXumaczony w dokXadnie ten sam sposob, moXna mieae wraXenie, Xe ten akapit oryginaXu zniknXX. Wystarczy usunXae nowe tXumaczenie. JeXli preferowaXbyX usuniecie pierwszego z tych tXumaczen~, bo drugie jest lepsze, po prostu przenieX drugie tXumaczenie w miejsce pierwszego.

    Odwrotnie, jeXli dwa podobne, ale jednak roXne, akapity byXy przetXumaczone dokXadnie tak samo, to jeden akapit tXumaczenia zniknie. RozwiXzaniem jest dodanie gXupiego tekstu do oryginalnego akapitu (takiego jak "roXnie sie"). Nie trzeba sie tego baae, takie rzeczy zniknX podczas synchronizacji, a kiedy taki tekst jest wystarczajXco krotki, gettext dopasuje Twoje tXumaczenie do istniejXcego tekstu (oznaczajXc je jako niepewne ["fuzzy"], czym nie powinno sie przejmowaae, gdyX wszystkie komunikaty sX tak oznaczone zaraz po procesie przeksztaXcania na format gettext).

Mamy nadzieje, Xe te porady pomogX w procesie przeksztaXcania do formatu gettext i w otrzymaniu pliku po. MoXna teraz ten plik zsynchronizowaae i zaczXae go tXumaczyae. Prosze zauwaXyae, Xe w wypadku dXugich plikow, pierwsza synchronizacja moXe zajXae duXo czasu.

Na przykXad, pierwsze wykonanie po4a-updatepo na francuskim tXumaczeniu dokumentacji Perla (plik po o rozmiarze 5.5 Mb) zajeXo okoXo dwoch dni na komputerze 1Ghz G5. Tak, 48 godzin. Ale kolejne zajmujX tylko kilkanaXcie sekund na moim starym laptopie. Dzieje sie tak, poniewaX na samym poczXtku wiekszoXae msgid pliku po nie pasuje do Xadnego msgid w pliku pot. Wymusza to na programie gettext wyszukiwanie najbardziej zbliXonego msgid, uXywajXc kosztownego algorytmu bliskoXci Xan~cuchow znakow.

  JAK dodaae dodatkowy tekst do tXumaczen~ (np. nazwisko tXumacza)?
Z powodu rozwiXzan~ stosowanych przez gettext, zrobienie tego moXe byae trudniejsze w po4a niX byXo wczeXniej, kiedy to plik byX po prostu recznie edytowany. Jednak pozostaje to moXliwe, dzieki tak zwanym zaXXcznikom.

Dla lepszego zrozumienia moXna przyjXae, Xe zaXXczniki sX rodzajem Xat (patch) aplikowanych do przetXumaczonego dokumentu po zakon~czeniu przetwarzania. RoXniX sie one od zwykXych Xat (majX tylko jednX linie kontekstu, ktora moXe zawieraae wyraXenie regularne Perla, i mogX tylko dodawaae nowy tekst bez usuwania czegokolwiek), ale funkcjonalnoXae jest taka sama.

Celem jest danie tXumaczowi moXliwoXci doXXczenie do dokumentu dodatkowej zawartoXci, ktora nie jest tXumaczeniem oryginalnego dokumentu. NajczeXciej uXywany jest do dodawania sekcji dotyczXcej samego tXumaczenia, wypisania wspoXpracownikow lub podania sposobu zgXaszania bXedow znalezionych w tXumaczeniu.

ZaXXcznik musi byae podany jako osobny plik, ktorego pierwsza linia zawiera nagXowek okreXlajXcy, gdzie naleXy umieXciae tekst zaXXcznika. Reszta pliku zaXXcznika bedzie umieszczona bez zmian w okreXlonej pozycji wynikowego dokumentu.

SkXadnia nagXowka jest caXkiem sztywna: musi zaczynaae sie od tekstu "PO4A-HEADER:" poprzedzajXcego rozdzielonX Xrednikami (;) liste pol "klucz=wartoXae". Spacje SX istotne. Prosze zauwaXyae, Xe nie moXna uXyae Xrednikow (;) w wartoXci, a ich cytowanie za pomocX odwrotnego ukoXnika nie pomaga.

Tak, brzmi to strasznie, ale poniXsze przykXady powinny pomoc w napisaniu odpowiedniej linii nagXowka. Aby zilustrowaae dyskusje, zaXoXmy, Xe chcemy dodaae sekcje "O tXumaczeniu" zaraz po sekcji "O dokumencie".

Kilka moXliwych kluczy nagXowka:

position (obowiXzkowe)
    wyraXenie regularne. ZaXXcznik bedzie umieszczony w pobliXu linii pasujXcej do wyraXenia regularnego. Prosze zauwaXyae, Xe mowimy tutaj o dokumencie przetXumaczonym, a nie o oryginale. JeXli wiecej niX jedna linia pasuje do tego wyraXenia, dodawanie zaXXcznika sie nie powiedzie. Istotnie, lepiej jest zgXosiae bXXd niX wstawiae zaXXcznik w nieodpowiednie miejsc.

    Te linie bedziemy dalej nazywaae punktem pozycji. Punkt, w ktorym zaXXcznik jest dodawany nazwiemy punktem wstawienia. Te dwa punkty sX blisko siebie, ale nie sX sobie rowne. Na przykXad, aby dodaae nowX sekcje Xatwiej zaczepiae punkt pozycji na tytule poprzedniej sekcji i wytXumaczyae programowi po4a, gdzie ta sekcja sie kon~czy (naleXy pamietaae, Xe punkt pozycji jest podany przez wyraXenie regularne, ktore powinno dopasowywaae sie do pojedynczej linii).

    ZaleXnoXae miejsca punktu wstawienia w stosunku do punkty pozycji jest okreXlana przez pola "mode", "beginboundary" i "endboundary", opisane poniXej.

    W naszym przypadku byXoby to:

         position=<title>O dokumencie</title>

mode (obowiXzkowe)
    MoXe byae to jeden z nastepujXcych Xan~cuchow znakow: "before" (= przed) lub "after" (= po), okreXlajXcych pozycje dodatku w stosunku do punktu pozycji.

    PoniewaX chcemy nowX sekcje umieXciae pod tX, ktorX wyszukaliXmy, mamy:

         mode=after

beginboundary (uXywany, gdy mode=after i obowiXzkowy w tym wypadku)
endboundary (jak wyXej)
    wyraXenie regularne pasujXce do kon~ca sekcji, po ktorej jest dodawany zaXXcznik.

    W trybie "after" punkt wstawienia jest za punktem pozycji, ale nie bezpoXrednio za! Jest on umieszczony na kon~cu sekcji zaczynajXcej sie w punkcie pozycji, czyli za albo przed liniX pasujXcX do argumentu "???boundary" w zaleXnoXci od tego, czy byXo uXyte "beginboundary", czy "endboundary".

    W rozpatrywanym przypadku moXemy wybraae wskazanie kon~ca dopasowywanej sekcji, dodajXc:

       endboundary=</section>

    albo moXemy wskazaae poczXtek kolejnej sekcji w nastepujXcy sposob:

       beginboundary=<section>

    W obu wypadkach zaXXcznik bedzie umieszczony po </section>, a przed <section>. Ten pierwszy sposob dziaXa lepiej, poniewaX zadziaXa nawet wtedy, gdy dokument zostanie zreorganizowany.

    Obie formy istniejX poniewaX formaty dokumentacji sX roXne. Niektore z nich zawierajX znacznik kon~ca sekcji (tak jak "</section>", ktorej wXaXnie uXyliXmy), a inne (np. nroff) tego kon~ca nie oznaczajX w Xaden szczegolny sposob. W pierwszym przypadku boundary powinno odpowiadaae kon~cowi sekcji, tak Xe punkt wstawienia nastepuje po niej. W drugim przypadku boundary powinno pasowaae do poczXtku nastepnej sekcji, a punkt wstawienia powinien byae umieszczony zaraz przed niX.

MoXe sie to wydawaae niejasne, nastepne przykXady powinny co nieco wyklarowaae.

PodsumowujXc przykXady podane do tej pory: aby dodaae sekcje "O tXumaczeniu" po sekcji "O dokumencie" w dokumencie sgml, naleXy uXyae jednej z poniXszych linii nagXowka:
     PO4A-HEADER: mode=after; position=O dokumencie; endboundary=</section>
     PO4A-HEADER: mode=after; position=O dokumencie; beginboundary=<section>

Aby dodaae coX po nastepujXcej sekcji nroff:
      .SH "AUTORZY"

    powinno sie ustawiae "positon" pasujXce do tej linii oraz "beginboundary" pasujXce do poczXtku nastepnej sekcji (tj. "^\.SH"). ZaXXcznik zostanie dodany po punkcie pozycji i zaraz przed pierwszX liniX pasujXcX do "beginboundary". Czyli:

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

Aby zamiast dodawaae caXX sekcje, dodaae coX do jakiejX sekcji (np. po "Copyright Big Dude"), trzeba podaae "position" pasujXce do tej linii i "beginboundary" pasujXce do jakiejkolwiek linii.
     PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

Aby dodaae coX na kon~cu dokumentu, naleXy podaae "position" pasujXce do jakiejkolwiek linii pliku (ale tylko jednej linii. Po4a nie przetworzy tego, jeXli linia nie bedzie unikatowa) i podaae "endboundary" nie pasujXce do niczego. Nie naleXy uXywaae tutaj prostych tekstow jak ""EOF"", tylko takich, ktore majX maXe szanse pojawienia sie w dokumencie.
     PO4A-HEADER:mode=after;position=<title>O dokumencie</title>;beginboundary=NieistniejXaLiniaPo4a

W kaXdym wypadku naleXy pamietaae, Xe sX to wyraXenia regularne. Na przykXad, aby dopasowaae koniec sekcji nroff, kon~czXcej sie liniX

  .fi

nie naleXy uXywaae ".fi" jako endboundary, poniewaX bedzie on pasowaX do "the[ fi]le" co raczej nie jest tym, czego moXna by oczekiwaae. Poprawnym endboundary w tym przypadku jest "^\.fi$".

JeXli zaXXcznik nie trafiX tam, gdzie powinien, sprobuj przekazaae narzedziom po4a argument -vv, ktory powinien pomoc wyjaXniae co sie dzieje podczas dodawania zaXXcznika.

Bardziej szczegoXowy przykXad

Oryginalny dokument (w formacie pod):

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

Wtedy nastepujXcy dodatek spowoduje dodanie sekcji (w jezyku francuskim) na koniec tego pliku (w jez. francuskim "TRADUCTEUR" oznacza "TXUMACZ", a "moi" znaczy "ja")

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

Aby umieXciae dodatek przed sekcjX AUTOR, naleXy uXyae nastepujXcego nagXowka:

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

To dziaXa, poniewaX nastepnX liniX pasujXcX do beginboundary /^head1/ po sekcji "NAZWA" (przetXumaczonej na francuskie "NOM") jest linia opisujXca autorow. Tak wiec zaXXcznik zostanie umieszczony pomiedzy obiema sekcjami.

  JAK to wszystko zrobiae, wywoXujXc tylko jeden program?
UXytkownicy udowodnili, Xe takie uXycie po4a jest naraXone na bXedy, poniewaX naleXy we wXaXciwym porzXdku wywoXaae dwa roXne programy (po4a-updatepo, a nastepnie po4a-translate), z ktorych kaXdy wymaga podania wiecej niX 3 argumentow. Co wiecej, w tym systemie byXo trudno uXyae tylko jednego pliku po dla wszystkich dokumentow, kiedy uXyto wiecej niX jednego formatu.

Program po4a(1) zaprojektowano, aby rozwiXzaae te trudnoXci. Kiedy tylko projekt zostanie skonwertowany do tego systemu, moXna napisaae prosty plik konfiguracyjny opisujXcy miejsce poXoXenia plikow tXumaczen~ (po i pot) i oryginalnych dokumentow, ich formaty oraz miejsce, gdzie powinny trafiaae przetXumaczone dokumenty.

Uruchomienie po4a(1) na tym pliku spowoduje zsynchronizowanie wszystkich plikow po z oryginalnym dokumentem, tak Xeby przetXumaczony dokument zostaX poprawnie wygenerowany. OczywiXcie naleXy ten program wywoXaae dwa razy: raz przed edytowaniem pliku po, Xeby go zaktualizowaae, i raz po jego edycji, aby otrzymaae caXkowicie aktualny przetXumaczony dokument . Tylko Xe potrzebujesz zapamietaae tylko jednX komende linii polecen~.

Jak to dziaXa?
Ten rozdziaX zawiera krotki opis wewnetrznych mechanizmow po4a, tak Xe bedziesz miaX wiecej odwagi, aby pomoc nam w jego tworzeniu i udoskonalaniu. MoXe takXe Ci pomoc w zrozumieniu, dlaczego nie dziaXa tak, jak byX tego oczekiwaX, oraz jak rozwiXzaae napotkane problemy.

  Jaki jest tu duXy obrazek?
Architektura po4a jest zorientowana obiektowo (w Perlu, czy to nie eleganckie?). Wspolny przodek wszystkich klas parserow zwie sie TransTractor. Ta dziwna nazwa wzieXa sie stXd, Xe jest on odpowiedzialny za tXumaczenie dokumentu i wydobywanie komunikatow.

Bardziej formalnie mowiXc, pobiera dokument do przetXumaczenia oraz plik po zawierajXcy tXumaczenia uXywany jako wejXcie podczas tworzenia dwoch oddzielnych plikow wyjXciowych: innego pliku po (wyniku wyodrebniania komunikatow z dokumentu wejXciowego) oraz przetXumaczonego dokumentu (majXcego takX samX strukture jak plik wejXciowy, ale ze wszystkimi komunikatami zamienionymi na zawartoXae wejXciowego pliku po). PoniXej jest graficzne przedstawienie tego procesu:

   Dokument wejXciowy -\                          /-> Dokument wyjXciowy
                        \      TransTractor::    /    (przetXumaczony)
                         +-->--   parse()  --- -+
                        /                        \
   WejXciowy po -------/                          \---> WyjXciowy po
                                                        (wyodrebniony)

Ta maXa koXae jest podstawX caXej architektury po4a. JeXli pominiesz wejXciowy plik po i dokument wyjXciowy, otrzymasz po4a-gettextize. JeXli podasz oba pliki wejXciowe i zlekcewaXysz wyjXciowy plik po, otrzymasz po4a-translate.

TransTractor::parse() jest wirtualnX funkcjX zaimplementowanX w kaXdym module. Tutaj podano prosty przykXad, Xeby zobrazowaae jej dziaXanie. Przetwarza liste akapitow, z ktorych kaXdy zaczyna sie 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 wejXciowego.
 19   }
 20 }

W linii 6. po raz drugi napotkaliXmy <p>. Oznacza to kolejny akapit. PowinniXmy dlatego zwrociae otrzymanX linie do oryginalnego dokumentu (linia 7.), a na wyjXcie doXoXyae akapit zbudowany do tej pory. Po usunieciu z niego poczXtkowego <p> w linii 9., dokXadamy ten element poXXczony z tXumaczeniem reszty akapitu.

Funkcja translate() jest bardzo fajna (cool ;)). Dodaje swoje argumenty na koniec wynikowego pliku po (ekstrakcja) i zwraca ich tXumaczenie, znalezione w wejXciowym pliku po (tXumaczenie). PoniewaX jest uXywana jako czeXae argumentu pushline(), tXumaczenie lXduje w wynikowym dokumencie.

Czy to nie jest fajne? Jest moXliwe zbudowanie kompletnego moduXu po4a w mniej niX 20 liniach, jeXeli tylko format jest wystarczajXco prosty...

Wiecej informacji o tym moXna znaleXae w Locale::Po4a::TransTractor(3pm).

  Proces przeksztaXcania do formatu gettext: jak to dziaXa?
Idea jest nastepujXca: pobranie oryginalnego dokumentu i jego tXumaczenia i powiedzenie, Xe n-ty komunikat wyodrebniony z tXumaczenia jest tXumaczeniem n-tego komunikatu wyodrebnionego z oryginaXu. Aby to zadziaXaXo, oba pliki muszX mieae dokXadnie takX samX strukture. Na przykXad, jeXeli pliki majX poniXszX strukture, to jest raczej niemoXliwe, by 4. komunikat tXumaczenia (typu "rozdziaX") byX tXumaczeniem 4. komunikatu oryginaXu (typu "akapit").

   OryginaX         TXumaczenie

   rozdziaX          rozdziaX
      akapit            akapit
      akapit            akapit
      akapit         rozdziaX
   rozdziaX             akapit
      akapit            akapit

Aby to osiXgnXae, parsery po4a sX uXywane zarowno na pliku oryginaXu, jak i tXumaczenia, Xeby utworzyae pliki po, a nastepnie jest budowany z nich trzeci plik po zawierajXcy komunikaty z drugiego pliku jako tXumaczenia komunikatow z pierwszego. Aby sprawdziae, Xe komunikaty, ktore ze sobX XXczymy, sX rzeczywiXcie odpowiadajXcymi sobie tXumaczeniami, parsesy dokumentow w po4a powinny umieszczaae informacje o typach skXadniowych komunikatow wyodrebnionych z dokumentu (wszystkie istniejXce to robiX, Twoj teX powinien). Nastepnie te informacje sX uXywane do sprawdzenia, Xe oba dokumenty majX te samX skXadnie. W poprzednim przykXadzie pozwoliXo nam to wykryae, Xe 4. komunikat jest w jednym przypadku akapitem, a w drugim - tytuXem rozdziaXu i zgXosiae problem.

Teoretycznie byXoby moXliwe zsynchronizowanie plikow po wykryciu problemu (tak, jak to robi diff). Niestety, nie jest jasne, co zrobiae z komunikatami, ktore nie wystepujXc w jednym z plikow, byXy przyczynX rozsynchronizowania. Dlatego obecna implementacja nie stara sie synchronizowaae plikow i zgXasza bXXd, kiedy coX poszXo Xle, wymagajXc od uXytkownika recznego zmodyfikowania plikow w celu rozwiXzania problemu.

Nawet z tymi zabezpieczeniami, rzeczy mogX Xle sie potoczyae. WXaXnie dlatego wszystkie tXumaczenia odgadniete w ten sposob sX zaznaczane jako niepewne ("fuzzy"), aby tXumacz je przejrzaX i sprawdziX.

  ZaXXcznik: Jak to dziaXa?
Hmm, to caXkiem proste. TXumaczony dokument nie jest bezpoXrednio zapisywany na dysk, ale trzymany w pamieci, dopoki wszystkie zaXXczniki nie zostanX dodane. Wykorzystane algorytmy sX raczej proste. Szukamy linii pasujXcej do wyraXenia regularnego okreXlajXcego pozycje i dodajemy zaXXcznik przed tX linX, jeXli tryb = before. JeXli nie jesteXmy w tym trybie, to szukamy nastepnej linii pasujXcej do ograniczenia i wstawiamy zaXXcznik po tej linii, jeXli jest to "endboundary", lub przed niX, jeXli jest to "beginboundary".

FAQ
Ten rozdziaX zawiera odpowiedzi na czesto zadawane pytania. Tak naprawde, wiekszoXae tych pytan~ moXe byae sformuXowanych jako "Dlaczego po4a zostaXo zaprojektowane tak, a nie inaczej?". JeXli wydaje Ci sie, Xe po4a nie jest wXaXciwym narzedziem do tXumaczenia dokumentacji, powinieneX rozwaXyae przeczytanie tego rozdziaXu. JeXli nie znajdziesz w nim odpowiedzi na swoje pytanie, prosimy sie z nami skontaktowaae poprzez liste dyskusyjnX <po4a-devel@lists.alioth.debian.org>. Uwielbiamy znaae opinie uXytkownikow.

  Dlaczego trzeba tXumaczyae kaXdy akapit osobno?
Tak, w po4a, kaXdy akapit jest tXumaczony osobno (w zasadzie, to kaXdy moduX o tym decyduje, ale wszystkie istniejXce moduXy tak robiX i Twoj takXe powinien). SX dwie gXowne przyczyny takiego rozwiXzania:

•   Kiedy techniczne czeXci dokumentu sX ukryte, tXumacz nie moXe w nich zrobiae baXaganu. Im mniej znacznikow pokazujemy tXumaczowi, tym mniej bXedow moXe popeXniae.

•   Przycinanie dokumentu pomaga odizolowaae zmiany w oryginalnym dokumencie. Kiedy oryginaX zostanie zmieniony, ten proces uproXci wyszukanie czeXci tXumaczen~ potrzebujXcych aktualizacji.

Nawet biorXc pod uwage te plusy, niektorym ludziom nie podoba sie osobne tXumaczenie kaXdego akapitu. Postaram sie odpowiedzieae na ich obawy:

•   Takie podejXcie sprawdziXo sie w projekcie KDE, pozwalajXc temu zespoXowi na wyprodukowanie znacznej iloXci przetXumaczonej i aktualnej dokumentacji.

•   TXumacze mogX wciXX uXywaae kontekstu tXumaczenia, poniewaX wszystkie komunikaty w pliku po sX w takiej samej kolejnoXci jak w oryginalnym dokumencie. TXumaczenie sekwencyjne jest podobne, niezaleXnie, czy uXywa sie po4a czy nie. I w kaXdym wypadku najlepszym sposobem otrzymania kontekstu pozostaje skonwertowanie dokumentu do formatu dokumentu drukowanego, poniewaX formaty XrodXowe tekstu mogX nie byae zbyt czytelne.

•   Takie podejXcie jest uXywany przez profesjonalnych tXumaczy. Zgadzam sie, majX oni troche inne cele niX tXumacze oprogramowania open-source. Na przykXad moXliwoXae Xatwego zarzXdzania tXumaczeniem jest czesto dla nich mniej istotna, poniewaX zawartoXae rzadko sie zmienia.

  Dlaczego nie podzieliae na zdania (lub mniejsze czeXci)?
Profesjonalne narzedzie tXumaczy czasami dzielX dokument na poszczegolne zdania, aby zmaksymalizowaae wykorzystanie wczeXniejszych tXumaczen~ i zwiekszyae szybkoXae tXumaczenia. Problemem jest jednak to, Xe w zaleXnoXci od kontekstu to samo zdanie moXe mieae kilka tXumaczen~.

Akapity sX z definicji dXuXsze niX zdania. JeXeli w dwoch dokumentach ten sam akapit wystepuje, to moXemy zaXoXyae, Xe jego znaczenie (i tXumaczenie) jest takie samo, niezaleXnie od kontekstu.

Dzielenie na czeXci mniejsze niX zdania byXoby czymX bardzo niedobrym. Za duXo miejsca by zajeXo napisanie tu wyjaXnienie dlaczego, ale zainteresowany czytelnik moXe na przykXad przeczytaae strone podrecznika Locale::Maketext::TPJ13(3pm) (pochodzXcX z dokumentacji Perla). W skrocie, kaXdy jezyk ma okreXlone zasady skXadniowe i nie istnieje taki sposob budowania zdan~ przez XXczenie ich czeXci, ktory by dziaXaX dla wszystkich istniejXcych jezykow (lub nawet dla tylko 5 czy 10 najpopularniejszych).

  Dlaczego nie umieXciae oryginaXu jako komentarza do tXumaczenia (lub w inny sposob)?
Na pierwszy rzut oka gettext nie wydaje sie byae przeznaczony do wszystkich rodzajow tXumaczen~. Na przykXad nie wydawaX sie on byae przystosowany do debconfa, interfejsu wszystkich pakietow Debiana uXywanego do interakcji z uXytkownikiem podczas instalacji. W tym przypadku teksty do tXumaczenia byXy caXkiem krotkie (tuzin linii dla kaXdego pakietu) i byXo trudno umieXciae tXumaczenie w specjalnym pliku poniewaX musiaXo byae dostepne jeszcze przed zainstalowaniem pakietu.

To dlatego opiekun debconfa zdecydowaX zaimplementowaae inne rozwiXzanie, w ktorym tXumaczenia sX umieszczane w tym samym pliku, co oryginaX. Jest to pociXgajXce. KtoX mogXby nawet chcieae coX takiego zrobiae dla XML-a na przykXad. MogXby on wyglXdaae 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 byXo to na tyle problematyczne, Xe obecnie jest uXywane rozwiXzanie oparte na plikach po. Tylko oryginalny tekst moXe byae edytowany w pliku, a tXumaczenia muszX sie pojawiae w plikach po, wyciXgnietych z gXownego szablonu (XXczonych z powrotem w czasie kompilacji pakietu). Ten stary system jest potepiany z kilku powodow:

•   problemy w zarzXdzaniu

    JeXeli kilku tXumaczy dostarczy Xate w tym samym czasie, bedzie trudno poXXczyae te Xaty wszystkie razem.

    Jak wykryae te zmiany w oryginale, ktore muszX byae zastosowane w tXumaczeniach? Aby uXyae programu diff, trzeba byXo zanotowaae wersje oryginaXu, ktora zostaXa przetXumaczone. Tj. potrzebujesz pliku po w Twoim pliku.

•   problemy z kodowaniem znakow

    RozwiXzanie to jest dobre tylko dla europejskich jezykow, jednak wprowadzenie korean~skiego, rosyjskiego lub arabskiego bardzo wszystko komplikuje. RozwiXzaniem mogXby byae UTF, jednak wciXX jest z nim kilka problemow.

    Co wiecej takie problemy sX trudne do wychwycenia (tj. tylko Korean~czycy zauwaXX Xe kodowanie znakow w korean~skim tekXcie jest zepsute [bo tXumacz byX Rosjaninem]).

gettext rozwiXzuje wszystkie te problemy razem.

  Ale gettext nie zostaX zaprojektowany do takiego uXycia!
To prawda, ale do tej pory nikt nie znalazX lepszego rozwiXzania. JedynX znanX alternatywX jest reczne tXumaczenie ze wszystkimi problemami w jego zarzXdzaniu.

  Co z innymi narzedziami do tXumaczen~ dokumentacji wykorzystujXcymi gettext?
O ile mi wiadomo, sX tylko dwa takie:

poxml
    Jest to narzedzie rozwijane przez ludzi z KDE obsXugujXce format DocBook XML. O ile mi wiadomo, byX to pierwszy program wyciXgajXcy Xan~cuchy znakow do przetXumaczenia z dokumentacji do plikow po i wstawiajXcy je z powrotem po przetXumaczeniu.

    MoXe on obsXugiwaae tylko XML i czeXciowo DTD. Jestem bardzo niezadowolony z obsXugi list, ktore zostajX umieszczone w jednym wielkim msgid. Kiedy lista staje sie dXuga, sprawa sie komplikuje.

po-debiandoc
    Program utworzony przez Denisa Barbiera jest poprzednikiem moduXu sgml po4a, ktory w mniejszym bXdX wiekszym stopniu go zastepuje, czyniXc przestarzaXym. Zgodnie ze swX nazwX obsXuguje tylko debiandoc DTD, ktory jest DTD mniej lub bardziej przestarzaXym.

NajwiekszX zaletX po4a nad nimi jest XatwoXae umieszczania dodatkowej zawartoXci (co jest nawet gorsze tutaj) i przejXcia na format gettext.

  Przekazywanie deweloperom wiedzy o tXumaczeniu
ProbujXc tXumaczyae dokumentacje lub programy moXna napotkaae trzy rodzaje problemow: lingwistyczne (nie kaXdy mowi dwoma jezykami), techniczne (to dlatego istnieje po4a) i ludzkie. Nie wszyscy deweloperzy rozumiejX potrzebe tXumaczen~. Nawet majXc dobre checi, mogX ignorowaae potrzebe upraszczania pracy tXumaczy. Aby w tym pomoc, po4a dostarcza wiele dokumentacji, do ktorej moXna sie odnosiae.

Innym waXnym punktem jest to, Xe kaXdy plik z tXumaczeniem zaczyna sie od krotkiego komentarza okreXlajXcego, czym jest ten plik i jak go uXyae. Powinno to pomoc deweloperom, zalanym tonami plikow w roXnych jezykach, ktorych nie znajX, pomoc w poprawnym obsXuXeniu tego.

W projekcie po4a przetXumaczone dokumenty nie sX plikami XrodXowymi. PoniewaX jesteXmy przyzwyczajeni do tego, Xe pliki sgml sX plikami XrodXowymi, Xatwo jest o pomyXke. Dlatego wszystkie pliki zawierajX taki nagXowek:

 |       ****************************************************
 |       *         PLIK WYGENEROWANY, NIE EDYTOWAAE          *
 |       * TO NIE JEST PLIK XRODXOWY, ALE WYNIK KOMPILACJI  *
 |       ****************************************************
 |
 | Ten plik zostaX wygenerowany przez po4a-translate(2). Nie przechowuj go
 | (na przykXad w CVS-iie), ale przechowuj plik po, uXyty jako plik XrodXowy
 | przez polecenie po4a-translate.
 |
 | Tak naprawde, potraktuj ten plik jako plik binarny, a plik po jako zwykXy
 | plik XrodXowy: jeXli plik po zaginie, to bedzie trudniej zachowaae aktualnoXae
 | tego tXumaczenia. ;)

Podobnie, to co naleXy zrobiae ze zwykXymi plikami po programu gettext, to skopiowaae je do katalogu po/. Ale w przypadku plikow zarzXdzanych przez po4a to nie dziaXa. Najwiekszym ryzykiem tutaj jest to, Xe deweloper usunie istniejXce tXumaczenia jego programu wraz z tXumaczeniami dokumentacji. (Oba nie mogX byae przechowywane w jednym pliku po, poniewaX program wymaga instalacji pliku tXumaczen~ jako pliku mo, podczas gdy dokumentacja uXywa tXumaczen~ w czasie kompilacji). Dlatego pliki po tworzone przez moduX po-debiandoc zawierajX poniXszy nagXowek:

 #
 #  RADY DLA DEWELOPEROW:
 #    - nie trzeba recznie edytowaae plikow POT i PO.
 #    - ten plik zawiera tXumaczenie Twoich szablonow confiteor.
 #      Nie zastepuj tXumaczen~ Twojego programu tym plikiem !!
 #        (albo tXumacze bedX na Ciebie wXciekli)
 #
 #  RADY DLA TXUMACZY:
 #    JeXli nie jesteX zaznajomiony z formatem PO, warto przeczytaae
 #    dokumentacje pakietu gettext, zwXaszcza sekcje poXwiecone
 #    temu formatowi. Na przykXad uruchom:
 #         info -n '(gettext)PO Files'
 #         info -n '(gettext)Heder Centry'
 #
 #    Informacje specyficzne po-debconf sX dostepne w
 #            /usr/share/doc/po-debconf/README-trans
 #        lub http://www.debian.org/intl/l10n/po-debconf/README-trans
 #

  PODSUMOWANIE plusow i minusow rozwiXzania opartego na gettext

•   TXumaczenia nie sX trzymane wraz z oryginaXem, co pozwala w prosty sposob wykryae, czy tXumaczenia nie sX przestarzaXe.

•   TXumaczenia sX przechowywane w oddzielnych plikach, dzieki czemu tXumacze roXnych jezykow sobie nie przeszkadzajX, zarowno kiedy podsyXajX swoje tXumaczenia, jak i kiedy zmieniajX kodowanie znakow pliku.

•   Wewnetrznie jest oparty na pakiecie "gettext" (ale "po4a" oferuje bardzo prosty interfejs, tak Xe nie ma potrzeby poznawania wewnetrznych mechanizmow, aby go uXyae). W ten sposob, nie musimy ponownie wymyXlaae koXa, a poniewaX gettext jest szeroko uXywany, mamy nadzieje, Xe w wiekszym lub mniejszym stopniu jest wolny od bXedow.

•   Z punktu widzenia kon~cowego uXytkownika nic sie nie zmieniXo (poza tym, Xe tXumaczenia sX lepiej zarzXdzane). Wynikowe pliki z dokumentacjX sX tak samo dystrybuowane.

•   TXumacze nie muszX uczyae sie skXadni nowego pliku i mogX po prostu uXyae swojego ulubionego edytora plikow po (jak tryb po emasca, kbabel lub gtranslator).

•   Gettext udostepnia prosty sposob otrzymania statystyk o tym, co zostaXo zrobione, co powinno byae przejrzane i zaktualizowane, a co jeszcze jest do zrobienia. PrzykXady moXna znaleXae pod tymi adresami:

     - http://i18n.kde.org/tools/kbabel/img/previewKonq.png
     - http://www.debian.org/intl/l10n

Nie wszystko zXoto, co sie Xwieci - to podejXcie ma takXe kilka minusow, z ktorymi musimy sobie poradziae.

•   Na pierwszy rzut oka zaXXczniki sX... dziwne.

•   Nie moXna dostosowywaae tXumaczonego tekstu do wXasnych upodoban~, na przykXad przed podzielenie w danym miejscu na akapity, poXXczenie dwoch innych akapitow w jeden. Jednak w pewnym sensie, jeXeli jest jakiX problem z oryginaXem, powinno to zostaae zgXoszone jako bXXd.

•   Nawet majXc Xatwy interfejs, wciXX pozostaje nowym narzedziem, ktorego trzeba sie uczyae.

    Jednym z moich marzen~ jest zintegrowanie w jakiX sposob po4a z programami gtranslator lub kbabel. Kiedy plik sgml jest otwierany, komunikaty zostajX automatycznie wyciXgane. Kiedy jest zamykany, przetXumaczony plik jest zapisywany na dysk. JeXli uda nam sie zrobiae moduX MS Word (TM) (a przynajmniej RFT), to bedX mogli go nawet uXywaae profesjonalni tXumacze.

Znane bXedy i i XXdania nowych funkcjonalnoXci
NajwaXniejszX sprawX (oprocz brakujXcych moduXow) jest obsXuga kodowania znakow. RozwiXzaniem mogXoby byae dodanie pragmy Perla UTF-8 i rekodowanie komunikatow na wyjXciu, ale nie jest to jeszcze zrobione.

ChcielibyXmy wydzieliae czeXae kodu (dotyczXcego wstawiania plikow) moduXu sgml z powrotem do TransTractora, tak Xeby pozostaXe moduXy mogXy z niego korzystaae, ale to nie bedzie zmiana widoczna dla uXytkownika.

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

TXUMACZENIE
 Robert Luberda <robert@debian.org>