Linux Certif

Toute la documentation sur la certification Linux LPI

po4a

NAZWA

po4a - narzXdzia do tXumaczeX dokumentacji i innych materiaXow

WstXp

Celem projektu po4a (``po for anything'') jest uXatwienie tXumaczeX (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzXdzi gettext w tych obszarach, gdzie nie byXy uXywane, jak na przykXad w obszarze dokumentacji.

Spis treXci

Dokument jest zorganizowany nastXpujXco:

1. Dlaczego powinno siX uXywaX po4a? Jakie sX jego zalety?

Ten rozdziaX wprowadzenia wyjaXnia motywy i filozofiX projektu. JeXeli rozwaXasz uXycie po4a do Twoich tXumaczeX, powinieneX najpierw przeczytaX ten rozdziaX.

2. Jak uXywaX po4a?

RozdziaX ten jest rodzajem podrXcznika i probuje odpowiedzieX na pytania uXytkownikow, pozwalajXc lepiej zrozumieX caXy proces. Odpowiada, jak wykonaX roXne rzeczy w po4a, i sXuXy jako wprowadzenie do dokumentacji konkretnych narzXdzi.

JAK zaczXX nowe tXumaczenie?

JAK zamieniX tXumaczenie z powrotem do pliku dokumentacji?

JAK zaktualizowaX tXumaczenie programem po4a?

JAK skonwertowaX istniejXce tXumaczenia do po4a?

JAK dodaX dodatkowy tekst do tXumaczeX (np. nazwisko tXumacza)?

JAK to wszystko zrobiX, wywoXujXc tylko jeden program?

3. Jak to dziaXa?

Ten rozdziaX zawiera krotki opis wewnXtrznych mechanizmow po4a, tak Xe bXdziesz miaX wiXcej 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 rozwiXzaX napotkane problemy.

4. FAQ

Ten rozdziaX zawiera odpowiedzi na czXsto zadawane pytania. Tak naprawdX, wiXkszoXX tych pytaX moXe byX sformuXowanych jako ``Dlaczego po4a zostaXo zaprojektowane tak, a nie inaczej?''. JeXli wydaje Ci siX, Xe po4a nie jest wXaXciwym narzXdziem do tXumaczenia dokumentacji, powinieneX rozwaXyX przeczytanie tego rozdziaXu. JeXli nie znajdziesz w nim odpowiedzi na swoje pytanie, prosimy siX z nami skontaktowaX poprzez listX dyskusyjnX <po4a-devel@lists.alioth.debian.org>. Uwielbiamy znaX 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 siX, kiedy dany moduX wykonuje tXumaczenia oraz jakich zasad powinieneX przestrzegaX, piszXc oryginalny dokument, aby uproXciX Xycie tXumaczom.

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

6. Znane bXXdy i XXdania nowych funkcjonalnoXci

JuX kilka :(

Dlaczego uXywaX po4a? Do czego jest on przydatny?

Podoba mi siX idea wolnego oprogramowania, pozwalajXcego kaXdemu na dostXp do programow i ich kodow XrodXowych. BXdXc jednak Francuzem, jestem Xwiadomy tego, Xe licencja programu nie jest jedynym ograniczeniem otwartoXci oprogramowania: nieprzetXumaczone oprogramowanie jest bezuXyteczne dla ludzi nieznajXcych angielskiego, wiXc ciXgle czeka na nas duXo pracy, Xeby udostXpniX je kaXdej takiej osobie.

XwiadomoXX tego problemu wXrod osob zwiXzanych z oprogramowaniem open-source ostatnio znacznie wzrosXa. WygraliXmy, jako tXumacze, pierwszX bitwX i przekonaliXmy wszystkich o znaczeniu tXumaczeX. Niestety, to byXa ta Xatwiejsza czXXX. Teraz musimy wykonaX naszX pracX i przetXumaczyX wszystkie te rzeczy.

WXaXciwie oprogramowanie typu open-source ma doXX przyzwoity poziom tXumaczeX, dziXki wspaniaXemu pakietowi gettext, ktory ma moXliwoXci wyodrXbniania 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 trochX inna. Zbyt czXsto siX zdarza, Xe tXumaczony dokument nie jest dostatecznie widoczny (nie jest dystrybuowany jako czXXX programu), jest tylko czXXciowy lub nie jest aktualny. Ostatnia sytuacja jest najgorszX z moXliwych. PrzestarzaXe tXumaczenie, opisujXce stare, juX nieistniejXce zachowanie programu, moXe byX 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, wiXc ich tXumaczenie zajmuje trochX wiXcej czasu, nie wymaga przy tym jednak Xadnych umiejXtnoXci technicznych. TrudniejszX czXXciX pracy jest zarzXdzanie tXumaczeniem. Wykrywanie czXXci, ktore siX zmieniXy i powinny byX zaktualizowane, jest bardzo trudne, podatne na bXXdy i wysoce nieprzyjemne. Najprawdopodobniej wyjaXnia to, dlaczego tak wiele przetXumaczonej dokumentacji nie jest aktualne.

Odpowiedzi po4a

Tak wiXc, celem po4a jest uczynienie tXumaczeX dokumentacji Xatwymi do zarzXdzania. IdeX jest wykorzystanie metodologii gettexta na tym nowym polu. Tak jak w programie gettext, teksty sX wyodrXbniane z ich oryginalnych miejsc, aby mogXy w jednolitym formacie zostaX zaprezentowane tXumaczowi. Klasyczne narzXdzia gettexta pomogX im uaktualniX ich pracX, kiedy pojawi siX nowa wersja oryginalnego dokumentu. W przeciwieXstwie zaX do klasycznego modelu gettext, tXumaczenia sX wstawiane do struktury oryginalnego dokumentu, tak Xeby mogXy byX przetwarzane i dystrybuowane w dokXadnie taki sam sposob, co wersja angielska.

DziXki temu staXo siX Xatwiejsze znalezienie do przetXumaczenia zmienionych czXXci dokumentu. Innym plusem jest to, Xe w wypadku zasadniczej reorganizacji struktury dokumentu, gdy rozdziaXy sX przesuwane, XXczone lub dzielone, narzXdzia wykonajX prawie caXX brudnX robotX. WyodrXbnianie ze struktury dokumentu tekstow do przetXumaczenia pozwala tXumaczom nie przejmowaX siX zXoXonoXciX struktury dokumentu i zmniejsza szanse otrzymania dokumentu o niepoprawnej strukturze (choX zawsze jest to moXliwe).

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

ObsXugiwane formaty

Obecnie rozwiXzanie to zaimplementowano z sukcesem dla kilku formatow tekstu:

nroff

Format starych, dobrych stron podrXcznika 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. ModuX Locale::Po4a::Man(3pm) obsXuguje rownieX format mdoc,uXywany przez strony podrXcznika systemu BSD (caXkiem czXsto wystXpujXcych rownieX pod Linuksem).

pod

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

sgml

Nawet jeXli jest obecnie wypierany przez XML, ten format jest wciXX raczej czXsto uXywany w dokumentach o dXugoXci wiXkszej niX kilka ekranow. Pozwala tworzyX kompletne ksiXXki. Aktualizowane tXumaczeX tak dXugich dokumentow moXe byX prawdziwym koszmarem. Program diff bardzo czXsto okazuje siX bezuXyteczny, jeXli zmieni siX struktura oryginalnego tekstu. Na szczXXcie, z pomocX moXe przyjXX 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 poleceX. SzczegoXy moXna znaleXX w Locale::Po4a::Sgml(3pm).

TeX / LaTeX

Format LaTeX jest gXownym formatem dokumentacji uXywanym w publikacjach pisanych przez ludzi zwiXzanych ze Xwiatem wolnego oprogramowania. ModuX Locale::Po4a::LaTeX(3pm) byX testowany na dokumentacji Pythona, ksiXXce i kilku prezentacjach.

texinfo

CaXa dokumentacja GNU jest pisana w tym formacie (i jest to nawet jedno z wymagaX stawianych projektom , ktore chcX staX siX oficjalnymi projektami GNU). Wsparcie dla Locale::Po4a::Texinfo(3pm) jest wciXX w fazie poczXtkowej. Prosimy o zgXaszanie bXXdow i przesyXanie uwag dotyczXcych brakujXcych funkcjonalnoXci.

xml

XML jest formatem bazowym wielu innych formatow dokumentacji.

Obecnie po4a obsXuguje docbook DTD. SzczegoXy moXna znaleXX w Locale::Po4a::Docbook(3pm).

inne

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

Formaty niewspierane

Niestety, po4a ciXgle nie obsXuguje kilku formatow dokumentacji.

Istnieje caXa masa innych formatow, ktore byXmy chcieli obsXugiwaX w po4a, i nie sX to tylko formaty dokumentacji. W zasadzie, naszym celem jest wypeXnienie wszystkich dziur pozostawionych przez klasyczne narzXdzia gettext. Obejmuje to 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 uXywaX po4a?

RozdziaX ten jest rodzajem podrXcznika i probuje odpowiedzieX na pytania uXytkownikow, pozwalajXc lepiej zrozumieX caXy proces. Odpowiada, jak wykonaX roXne rzeczy w po4a, i sXuXy jako wprowadzenie do dokumentacji konkretnych narzXdzi.

Graficzne podsumowanie

NastXpujXcy schemat pokazuje poglXdowo proces tXumaczenia dokumentacji z uXyciem po4a. Nie powinno siX przejmowaX jego pozornX zXoXonoXciX, ktora wziXXa siX stXd, Xe pokazaliXmy tutaj caXy proces. Po skonwertowaniu projektu do po4a, istotna bXdzie tylko prawa czXXX schematu. ProszX zauwaXyX, Xe sgml wystXpuje tu jako przykXad i caXy schemat jest dokXadnie taki sam dla wszystkich moduXow. KaXdX czXXX rysunku omowimy szczegoXowo w nastXpnych 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
      |         |         |     {rXczna edycja}                   |
      V         V         |            |                          |
      |         |         |            V                          V
      |         |         +--<---    fr.po     zaXXcznik   oryginalny.sgml
      +---->----+---->------->---> (aktualny) (opcjonalny)    (aktualny)
                                       |            |             |
                                       v            v             v
                                       +------>-----+------<------+
                                                    |
                                                    v
                                            [po4a-translate]
                                                    |
                                                    V
                                                 fr.sgml
                                               (aktualny)
 
 

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

WXaXciwie, jedynX rXcznX operacjX, ktorX musi wykonaX tXumacz jest czXXX oznaczona {rXczna edycja}. Przykro nam, po4a tylko pomaga tXumaczyX, ale niestety niczego za Ciebie nie przetXumaczy...

JAK zaczXX nowe tXumaczenie?

Ta sekcja opisuje kroki niezbXdne do rozpoczXcia nowego tXumaczenia z uXyciem po4a. Konwertowanie istniejXcego projektu do tego systemu opisano w szczegoXach w odpowiedniej sekcji.

Aby zaczXX nowe tXumaczenie, uXywajXc po4a, naleXy wykonaX nastXpujXce kroki:

-

WyciXgnXX tekst do przetXumaczenia z oryginalnego dokumentu do nowego pliku pot (format programu gettext). Aby to zrobiX, naleXy wywoXaX program po4a-gettextize w nastXpujXcy sposob:

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

<format> jest oczywiXcie formatem uXywanym w dokumencie <master.doc>. Jak moXna oczekiwaX, plikiem wyjXciowym jest <tXumaczenie.pot>. WiXcej szczegoXow o dostXpnych opcjach moXna znaleXX w po4a-gettextize(1).

-

PrzetXumaczyX to, co jest do przetXumaczenia. W tym celu naleXy zmieniX nazwX pliku pot na przykXad na doc.XX.po (gdzie XX jest kodem ISO639 jXzyka, na ktory siX tXumaczy, np. ``fr'' dla jXzyka francuskiego) i edytowaX powstaXy plik. Zazwyczaj dobrym pomysXem jest nienazywanie tego pliku XX.po, aby uniknXX pomylenia z tXumaczeniem komunikatow programu, ale wybor naleXy do Ciebie. ProszX nie zapominaX o uaktualnieniu nagXowkow pliku po; sX one bardzo waXne.

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

Aby dowiedzieX siX czegoX wiXcej, stanowczo powinno siX przeczytaX dokumentacjX programu gettext, dostXpnX w pakiecie gettext-doc.

JAK zamieniX tXumaczenie z powrotem do pliku dokumentacji?

Po zakoXczeniu tXumaczenia zapewne naleXaXoby wygenerowaX przetXumaczone dokumenty i rozdystrybuowaX je wXrod uXytkownikow, razem z oryginalnymi dokumentami. Aby to zrobiX, naleXy uXyX programu po4a-translate(1) w ten sposob (XX jest kodem jXzyka):

   $ 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 czXXciX wejXcia - jest to Twoje tXumaczenie. WyjXcie jest zapisywane w <XX.doc>.

WiXcej szczegoXow moXna znaleXX w <po4a-translate(1)>.

JAK zaktualizowaX tXumaczenie programem po4a?

Aby zaktualizowaX tXumaczenie, gdy zmieni siX oryginalny plik, naleXy uXyX po4a-updatepo(1) w nastXpujXcy sposob:

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

(WiXcej szczegoXow moXna znaleXX w <po4a-updatepo(1)>).

OczywiXcie ta operacja nie spowoduje automagicznego przetXumaczenia nowych akapitow oryginalnego dokumentu. NaleXy rXcznie uaktualniX plik "po". Podobnie naleXy zaktualizowaX tXumaczenie akapitow, ktore siX choX trochX zmieniXy. Aby mieX pewnoXX, Xe Xadnego z nich nie ominiesz, zostaXy one zaznaczone jako ``fuzzy'' (niepewne) i zanim po4a-translate bXdzie mogX ich uXyX, to zaznaczenie musi zostaX usuniXte. Tak jak w przypadku pierwszego tXumaczenia najlepiej jest uXyX ulubionego edytora.

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

JAK skonwertowaX istniejXce tXumaczenia do po4a?

CzXsto siX zdarzaXo, Xe tXumaczyXeX dokument rXcznie dopoty, dopoki nie nastXpiXa wiXksza reorganizacja oryginalnego dokumentu. W tej sytuacji, po kilku nieprzyjemnych probach z diffem lub podobnymi narzXdziami, moXesz zechcieX skonwertowaX dokument do po4a. OczywiXcie naleXy go skonwertowaX tak, aby nie utraciX istniejXcych tXumaczeX. Nie naleXy siX obawiaX, 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 narzXdzia mogXy odpowiednio dopasowaX zawartoXX.

JeXli masz szczXXcie (tj. struktura obu dokumentow dokXadnie do siebie pasuje), wszystko zadziaXa bez Xadnego problemu i bXdzie gotowe w ciXgu paru sekund. W przeciwnym razie moXesz zrozumieX dlaczego ten proces ma takX brzydkX nazwX i przygotuj siX na doXX nieprzyjemnX pracX. W kaXdym razie, pamiXtaj, Xe jest to cena za komfort, ktory poXniej dostarczy po4a. Dobre w tym wszystkim jest to, Xe trzeba to zrobiX tylko raz.

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

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

ByX moXe zbytnio w tym momencie dramatyzujX. Jednak nawet, gdy proces siX nie udaje, pozostaje mimo wszystko szybszX drogX niX tXumaczenie wszystkiego od nowa. UdaXo mi siX przepuXciX 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.

ProszX najpierw pozwoliX mi wyjaXniX podstawy tej procedury, a potem powrocX do wskazowek, co zrobiX, gdy proces siX nie udaje. Dla lepszego zrozumienia, weXmy jako przykXad ponownie moduX sgml, jednak tak naprawdX uXyty format nie ma Xadnego znaczenia.

Kiedy juX zdobXdziesz stary oryginaX dokumentu, proces przechodzenia na gettext moXe byX tak Xatwy, jak:

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

JeXli masz szczXXcie, to to wszystko. Stare tXumaczenia zostaXy skonwertowane do po4a i moXna od razu zaczXX ich aktualizowanie. NaleXy tylko trzymajXc siX procedury opisanej kilka sekcji wczeXniej, zsynchronizowaX plik po z najnowszym oryginalnym dokumentem i odpowiednio zaktualizowaX tXumaczenia.

ProszX zauwaXyX, Xe nawet jeXli wydaje siX, Xe wszystko zadziaXaXo poprawnie, moXe siX okazaX, Xe jednak wystXpiXy bXXdy podczas tego procesu. Po4a nie rozumie przetwarzanych tekstow, wiXc nie moXe byX byX pewne, Xe tXumaczenia sX poprawnie przypisane do oryginaXow. Dlatego wszystkie komunikaty sX oznaczone jako ``fuzzy'' (niepewne). Przed usuniXciem tych znacznikow, proszX uwaXnie sprawdziX kaXde tXumaczenie.

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

Pomocne moXe byX przeczytanie poniXej sekcji ``Proces przeksztaXcania do formatu gettext: jak to dziaXa?''. Zrozumienie wewnXtrznych procesow pomoXe wykonaX zadanie. Plusem jest to, Xe w razie niepowodzenia, po4a-gettextize gXoXno powie, co poszXo Xle, umoXliwiajXc poznanie komunikatow, ktore do siebie nie pasowaXy, ich pozycjX w tekXcie i typ kaXdego z nich. Co wiXcej, plik po wygenerowany do tej pory, bXdzie zachowany jako gettextization.failed.po.

-

NaleXy usunXX wszystkie dodatkowe czXXci tXumaczenia, takie jak sekcja, w ktorej podano nazwisko tXumacza i podziXkowania dla wszystkich ludzi, ktorzy pomagali przy tXumaczeniu. PoXniej takie czXXci bXdzie moXna z powrotem dodaX, uXywajXc zaXXcznikow, opisanych w nastXpnym rozdziale.

-

Nie wahaj siX edytowaX zarowno pliku oryginalnego, jak i jego tXumaczenia. NajwaXniejszX rzeczX jest otrzymanie pliku po. Potem bXdzie moXna go zaktualizowaX. Edytowanie tXumaczeX powinno byX jednak preferowane, poniewaX uproXci to pewne rzeczy po zakoXczeniu siX procesu przeksztaXcania na format gettext.

-

JeXli jest taka potrzeba, naleXy usunXX kilka czXXci oryginalnego dokumentu, ktore nie sX przetXumaczone. PoXniej podczas synchronizowania po z dokumentem czXXci te siX pojawiX same.

-

JeXli w niewielkim stopniu zmieniXeX strukturX dokumentu (poXXczenie dwoch akapitow, albo podzielenie innego akapitu), wycofaj te zmiany. JeXli te zmiany miaXy zwiXzek z problemami wystXpujXcym w oryginalnym dokumencie, powinieneX poinformowaX o nich jego autora. KorzyXci z poprawienie ich tylko w Twoim tXumaczeniu bXdzie miaXa tyko czXXX spoXecznoXci. Co wiXcej, takie poprawki nie sX moXliwe, gdy siX uXywa po4a.

-

Czasami zawartoXci akapitow siX zgadzajX, ale ich typy nie. Poprawienie tego zaleXy od formatu. W formatach pod i nroff, czXsto bierze siX to z tego, Xe jeden z tych dwoch akapitow zawiera liniX zaczynajXcX siX od biaXego znaku, a drugi - nie. W tych formatach tekst takich akapitow nie moXe byX zawijany i dlatego wystXpuje niezgodnoXX typow. RozwiXzaniem jest usuniXcie spacji. MoXe to byX takXe literowka w nazwie elementu.

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

-

Czasami wystXpuje rozsynchronizowanie miXdzy plikami i tXumaczenie jest przypisane do zXego akapitu oryginaXu. Jest to oznaka, Xe w rzeczywistoXci problem leXy w plikach. ProszX znaleXX w gettextization.failed.po miejsce, gdzie zaczyna siX rozsynchronizowanie, a nastXpnie poprawiX w tym miejscu pliki wejXciowe.

-

Czasami moXe siX wydawaX, Xe po4a zjadXo jakXX czXXX tekstu albo z oryginaXu, albo z tXumaczenia. gettextization.failed.po wskazuje, Xe oba pliki dokXadnie do siebie pasowaXy, a przetwarzanie koXczy siX bXXdem poniewaX nastXpiXa proba dopasowania jakiegoX akapitu do akapitu po (lub przed) tym wXaXciwym, tak jakby ten wXaXciwy siX ulotniX. MoXna tylko klXX na po4a, tak jak ja klXXem, gdy mi siX to zdarzyXo po raz pierwszy. Serio.

Ta nieszczXXliwa sytuacja zdarza siX, 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 wiXc, kiedy ten sam akapit pojawia siX dwa razy w oryginalnym dokumencie, ale nie jest przetXumaczony w dokXadnie ten sam sposob, moXna mieX wraXenie, Xe ten akapit oryginaXu zniknXX. Wystarczy usunXX nowe tXumaczenie. JeXli preferowaXbyX usuniXcie pierwszego z tych tXumaczeX, 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 ``roXniX siX''). Nie trzeba siX tego baX, 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 siX przejmowaX, gdyX wszystkie komunikaty sX tak oznaczone zaraz po procesie przeksztaXcania na format gettext).

Mamy nadziejX, Xe te porady pomogX w procesie przeksztaXcania do formatu gettext i w otrzymaniu pliku po. MoXna teraz ten plik zsynchronizowaX i zaczXX go tXumaczyX. ProszX zauwaXyX, Xe w wypadku dXugich plikow, pierwsza synchronizacja moXe zajXX duXo czasu.

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

JAK dodaX dodatkowy tekst do tXumaczeX (np. nazwisko tXumacza)?

Z powodu rozwiXzaX stosowanych przez gettext, zrobienie tego moXe byX trudniejsze w po4a niX byXo wczeXniej, kiedy to plik byX po prostu rXcznie edytowany. Jednak pozostaje to moXliwe, dziXki tak zwanym zaXXcznikom.

Dla lepszego zrozumienia moXna przyjXX, Xe zaXXczniki sX rodzajem Xat (patch) aplikowanych do przetXumaczonego dokumentu po zakoXczeniu przetwarzania. RoXniX siX one od zwykXych Xat (majX tylko jednX liniX kontekstu, ktora moXe zawieraX wyraXenie regularne Perla, i mogX tylko dodawaX nowy tekst bez usuwania czegokolwiek), ale funkcjonalnoXX jest taka sama.

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

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

SkXadnia nagXowka jest caXkiem sztywna: musi zaczynaX siX od tekstu ``PO4A-HEADER:'' poprzedzajXcego rozdzielonX Xrednikami (;) listX pol ``klucz=wartoXX''. Spacje SX istotne. ProszX zauwaXyX, Xe nie moXna uXyX 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 zilustrowaX dyskusjX, zaXoXmy, Xe chcemy dodaX sekcjX ``O tXumaczeniu'' zaraz po sekcji ``O dokumencie''.

Kilka moXliwych kluczy nagXowka:

position (obowiXzkowe)

wyraXenie regularne. ZaXXcznik bXdzie umieszczony w pobliXu linii pasujXcej do wyraXenia regularnego. ProszX zauwaXyX, Xe mowimy tutaj o dokumencie przetXumaczonym, a nie o oryginale. JeXli wiXcej niX jedna linia pasuje do tego wyraXenia, dodawanie zaXXcznika siX nie powiedzie. Istotnie, lepiej jest zgXosiX bXXd niX wstawiX zaXXcznik w nieodpowiednie miejsc.

TX liniX bXdziemy dalej nazywaX 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 dodaX nowX sekcjX Xatwiej zaczepiX punkt pozycji na tytule poprzedniej sekcji i wytXumaczyX programowi po4a, gdzie ta sekcja siX koXczy (naleXy pamiXtaX, Xe punkt pozycji jest podany przez wyraXenie regularne, ktore powinno dopasowywaX siX do pojedynczej linii).

ZaleXnoXX 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 byX to jeden z nastXpujXcych XaXcuchow znakow: ``before'' (= przed) lub ``after'' (= po), okreXlajXcych pozycjX dodatku w stosunku do punktu pozycji.

PoniewaX chcemy nowX sekcjX umieXciX pod tX, ktorX wyszukaliXmy, mamy:

      mode=after
 
 

beginboundary (uXywany, gdy mode=after i obowiXzkowy w tym wypadku)

endboundary (jak wyXej)

wyraXenie regularne pasujXce do koXca sekcji, po ktorej jest dodawany zaXXcznik.

W trybie ``after'' punkt wstawienia jest za punktem pozycji, ale nie bezpoXrednio za! Jest on umieszczony na koXcu sekcji zaczynajXcej siX 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 wybraX wskazanie koXca dopasowywanej sekcji, dodajXc:

    endboundary=</section>
 
 

albo moXemy wskazaX poczXtek kolejnej sekcji w nastXpujXcy sposob:

    beginboundary=<section>
 
 

W obu wypadkach zaXXcznik bXdzie 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 koXca sekcji (tak jak "</section>", ktorej wXaXnie uXyliXmy), a inne (np. nroff) tego koXca nie oznaczajX w Xaden szczegolny sposob. W pierwszym przypadku boundary powinno odpowiadaX koXcowi sekcji, tak Xe punkt wstawienia nastXpuje po niej. W drugim przypadku boundary powinno pasowaX do poczXtku nastXpnej sekcji, a punkt wstawienia powinien byX umieszczony zaraz przed niX.

MoXe siX to wydawaX niejasne, nastXpne przykXady powinny co nieco wyklarowaX.

PodsumowujXc przykXady podane do tej pory: aby dodaX sekcjX "O tXumaczeniu" po sekcji "O dokumencie" w dokumencie sgml, naleXy uXyX jednej z poniXszych linii nagXowka:

  PO4A-HEADER: mode=after; position=O dokumencie; endboundary=</section>
  PO4A-HEADER: mode=after; position=O dokumencie; beginboundary=<section>
 
 

Aby dodaX coX po nastXpujXcej sekcji nroff:

   .SH "AUTORZY"
 
 

powinno siX ustawiX "positon" pasujXce do tej linii oraz "beginboundary" pasujXce do poczXtku nastXpnej 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 dodawaX caXX sekcjX, dodaX coX do jakiejX sekcji (np. po "Copyright Big Dude"), trzeba podaX "position" pasujXce do tej linii i "beginboundary" pasujXce do jakiejkolwiek linii.

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

Aby dodaX coX na koXcu dokumentu, naleXy podaX "position" pasujXce do jakiejkolwiek linii pliku (ale tylko jednej linii. Po4a nie przetworzy tego, jeXli linia nie bXdzie unikatowa) i podaX "endboundary" nie pasujXce do niczego. Nie naleXy uXywaX tutaj prostych tekstow jak ""EOF"", tylko takich, ktore majX maXe szanse pojawienia siX w dokumencie.

  PO4A-HEADER:mode=after;position=<title>O dokumencie</title>;beginboundary=NieistniejXaLiniaPo4a
 
 

W kaXdym wypadku naleXy pamiXtaX, Xe sX to wyraXenia regularne. Na przykXad, aby dopasowaX koniec sekcji nroff, koXczXcej siX liniX

   .fi
 
 

nie naleXy uXywaX ".fi" jako endboundary, poniewaX bXdzie on pasowaX do ``the[ fi]le'' co raczej nie jest tym, czego moXna by oczekiwaX. Poprawnym endboundary w tym przypadku jest "^\.fi$".

JeXli zaXXcznik nie trafiX tam, gdzie powinien, sprobuj przekazaX narzXdziom po4a argument -vv, ktory powinien pomoc wyjaXniX co siX dzieje podczas dodawania zaXXcznika.

Bardziej szczegoXowy przykXad

Oryginalny dokument (w formacie pod):

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

Wtedy nastXpujXcy dodatek spowoduje dodanie sekcji (w jXzyku francuskim) na koniec tego pliku (w jXz. francuskim ``TRADUCTEUR'' oznacza ``TXUMACZ'', a ``moi'' znaczy ``ja'')

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

Aby umieXciX dodatek przed sekcjX AUTOR, naleXy uXyX nastXpujXcego nagXowka:

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

To dziaXa, poniewaX nastXpnX liniX pasujXcX do beginboundary /^=head1/ po sekcji ``NAZWA'' (przetXumaczonej na francuskie ``NOM'') jest linia opisujXca autorow. Tak wiXc zaXXcznik zostanie umieszczony pomiXdzy obiema sekcjami.

JAK to wszystko zrobiX, wywoXujXc tylko jeden program?

UXytkownicy udowodnili, Xe takie uXycie po4a jest naraXone na bXXdy, poniewaX naleXy we wXaXciwym porzXdku wywoXaX dwa roXne programy (po4a-updatepo, a nastXpnie po4a-translate), z ktorych kaXdy wymaga podania wiXcej niX 3 argumentow. Co wiXcej, w tym systemie byXo trudno uXyX tylko jednego pliku po dla wszystkich dokumentow, kiedy uXyto wiXcej niX jednego formatu.

Program po4a(1) zaprojektowano, aby rozwiXzaX te trudnoXci. Kiedy tylko projekt zostanie skonwertowany do tego systemu, moXna napisaX prosty plik konfiguracyjny opisujXcy miejsce poXoXenia plikow tXumaczeX (po i pot) i oryginalnych dokumentow, ich formaty oraz miejsce, gdzie powinny trafiaX 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 wywoXaX dwa razy: raz przed edytowaniem pliku po, Xeby go zaktualizowaX, i raz po jego edycji, aby otrzymaX caXkowicie aktualny przetXumaczony dokument . Tylko Xe potrzebujesz zapamiXtaX tylko jednX komendX linii poleceX.

Jak to dziaXa?

Ten rozdziaX zawiera krotki opis wewnXtrznych mechanizmow po4a, tak Xe bXdziesz miaX wiXcej 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 rozwiXzaX napotkane problemy.

Jaki jest tu duXy obrazek?

Architektura po4a jest zorientowana obiektowo (w Perlu, czy to nie eleganckie?). Wspolny przodek wszystkich klas parserow zwie siX TransTractor. Ta dziwna nazwa wziXXa siX 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 wyodrXbniania komunikatow z dokumentu wejXciowego) oraz przetXumaczonego dokumentu (majXcego takX samX strukturX jak plik wejXciowy, ale ze wszystkimi komunikatami zamienionymi na zawartoXX wejXciowego pliku po). PoniXej jest graficzne przedstawienie tego procesu:

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

Ta maXa koXX 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 zobrazowaX jej dziaXanie. Przetwarza listX akapitow, z ktorych kaXdy zaczyna siX 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 zwrociX otrzymanX liniX do oryginalnego dokumentu (linia 7.), a na wyjXcie doXoXyX akapit zbudowany do tej pory. Po usuniXciu 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 czXXX 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...

WiXcej informacji o tym moXna znaleXX w Locale::Po4a::TransTractor(3pm).

Proces przeksztaXcania do formatu gettext: jak to dziaXa?

Idea jest nastXpujXca: pobranie oryginalnego dokumentu i jego tXumaczenia i powiedzenie, Xe n-ty komunikat wyodrXbniony z tXumaczenia jest tXumaczeniem n-tego komunikatu wyodrXbnionego z oryginaXu. Aby to zadziaXaXo, oba pliki muszX mieX dokXadnie takX samX strukturX. Na przykXad, jeXeli pliki majX poniXszX strukturX, 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 osiXgnXX, parsery po4a sX uXywane zarowno na pliku oryginaXu, jak i tXumaczenia, Xeby utworzyX pliki po, a nastXpnie jest budowany z nich trzeci plik po zawierajXcy komunikaty z drugiego pliku jako tXumaczenia komunikatow z pierwszego. Aby sprawdziX, Xe komunikaty, ktore ze sobX XXczymy, sX rzeczywiXcie odpowiadajXcymi sobie tXumaczeniami, parsesy dokumentow w po4a powinny umieszczaX informacje o typach skXadniowych komunikatow wyodrXbnionych z dokumentu (wszystkie istniejXce to robiX, Twoj teX powinien). NastXpnie te informacje sX uXywane do sprawdzenia, Xe oba dokumenty majX tX samX skXadniX. W poprzednim przykXadzie pozwoliXo nam to wykryX, Xe 4. komunikat jest w jednym przypadku akapitem, a w drugim - tytuXem rozdziaXu i zgXosiX problem.

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

Nawet z tymi zabezpieczeniami, rzeczy mogX Xle siX potoczyX. WXaXnie dlatego wszystkie tXumaczenia odgadniXte 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 pamiXci, dopoki wszystkie zaXXczniki nie zostanX dodane. Wykorzystane algorytmy sX raczej proste. Szukamy linii pasujXcej do wyraXenia regularnego okreXlajXcego pozycjX i dodajemy zaXXcznik przed tX linX, jeXli tryb = before. JeXli nie jesteXmy w tym trybie, to szukamy nastXpnej 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 czXsto zadawane pytania. Tak naprawdX, wiXkszoXX tych pytaX moXe byX sformuXowanych jako ``Dlaczego po4a zostaXo zaprojektowane tak, a nie inaczej?''. JeXli wydaje Ci siX, Xe po4a nie jest wXaXciwym narzXdziem do tXumaczenia dokumentacji, powinieneX rozwaXyX przeczytanie tego rozdziaXu. JeXli nie znajdziesz w nim odpowiedzi na swoje pytanie, prosimy siX z nami skontaktowaX poprzez listX dyskusyjnX <po4a-devel@lists.alioth.debian.org>. Uwielbiamy znaX opinie uXytkownikow.

Dlaczego trzeba tXumaczyX 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 czXXci dokumentu sX ukryte, tXumacz nie moXe w nich zrobiX baXaganu. Im mniej znacznikow pokazujemy tXumaczowi, tym mniej bXXdow moXe popeXniX.

•

Przycinanie dokumentu pomaga odizolowaX zmiany w oryginalnym dokumencie. Kiedy oryginaX zostanie zmieniony, ten proces uproXci wyszukanie czXXci tXumaczeX potrzebujXcych aktualizacji.

Nawet biorXc pod uwagX te plusy, niektorym ludziom nie podoba siX osobne tXumaczenie kaXdego akapitu. Postaram siX odpowiedzieX na ich obawy:

•

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

•

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

•

Takie podejXcie jest uXywany przez profesjonalnych tXumaczy. Zgadzam siX, majX oni trochX inne cele niX tXumacze oprogramowania open-source. Na przykXad moXliwoXX Xatwego zarzXdzania tXumaczeniem jest czXsto dla nich mniej istotna, poniewaX zawartoXX rzadko siX zmienia.

Dlaczego nie podzieliX na zdania (lub mniejsze czXXci)?

Profesjonalne narzXdzie tXumaczy czasami dzielX dokument na poszczegolne zdania, aby zmaksymalizowaX wykorzystanie wczeXniejszych tXumaczeX i zwiXkszyX szybkoXX tXumaczenia. Problemem jest jednak to, Xe w zaleXnoXci od kontekstu to samo zdanie moXe mieX kilka tXumaczeX.

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

Dzielenie na czXXci mniejsze niX zdania byXoby czymX bardzo niedobrym. Za duXo miejsca by zajXXo napisanie tu wyjaXnienie dlaczego, ale zainteresowany czytelnik moXe na przykXad przeczytaX stronX podrXcznika Locale::Maketext::TPJ13(3pm) (pochodzXcX z dokumentacji Perla). W skrocie, kaXdy jXzyk ma okreXlone zasady skXadniowe i nie istnieje taki sposob budowania zdaX przez XXczenie ich czXXci, ktory by dziaXaX dla wszystkich istniejXcych jXzykow (lub nawet dla tylko 5 czy 10 najpopularniejszych).

Dlaczego nie umieXciX oryginaXu jako komentarza do tXumaczenia (lub w inny sposob)?

Na pierwszy rzut oka gettext nie wydaje siX byX przeznaczony do wszystkich rodzajow tXumaczeX. Na przykXad nie wydawaX siX on byX 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 umieXciX tXumaczenie w specjalnym pliku poniewaX musiaXo byX dostXpne jeszcze przed zainstalowaniem pakietu.

To dlatego opiekun debconfa zdecydowaX zaimplementowaX inne rozwiXzanie, w ktorym tXumaczenia sX umieszczane w tym samym pliku, co oryginaX. Jest to pociXgajXce. KtoX mogXby nawet chcieX coX takiego zrobiX dla XML-a na przykXad. MogXby on wyglXdaX 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 byX edytowany w pliku, a tXumaczenia muszX siX pojawiX w plikach po, wyciXgniXtych z gXownego szablonu (XXczonych z powrotem w czasie kompilacji pakietu). Ten stary system jest potXpiany z kilku powodow:

•

problemy w zarzXdzaniu

JeXeli kilku tXumaczy dostarczy XatX w tym samym czasie, bXdzie trudno poXXczyX te Xaty wszystkie razem.

Jak wykryX te zmiany w oryginale, ktore muszX byX zastosowane w tXumaczeniach? Aby uXyX programu diff, trzeba byXo zanotowaX wersjX oryginaXu, ktora zostaXa przetXumaczone. Tj. potrzebujesz pliku po w Twoim pliku.

•

problemy z kodowaniem znakow

RozwiXzanie to jest dobre tylko dla europejskich jXzykow, jednak wprowadzenie koreaXskiego, rosyjskiego lub arabskiego bardzo wszystko komplikuje. RozwiXzaniem mogXby byX UTF, jednak wciXX jest z nim kilka problemow.

Co wiXcej takie problemy sX trudne do wychwycenia (tj. tylko KoreaXczycy zauwaXX Xe kodowanie znakow w koreaXskim 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 rXczne tXumaczenie ze wszystkimi problemami w jego zarzXdzaniu.

Co z innymi narzXdziami do tXumaczeX dokumentacji wykorzystujXcymi gettext?

O ile mi wiadomo, sX tylko dwa takie:

poxml

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

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

po-debiandoc

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

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

Przekazywanie deweloperom wiedzy o tXumaczeniu

ProbujXc tXumaczyX dokumentacjX lub programy moXna napotkaX trzy rodzaje problemow: lingwistyczne (nie kaXdy mowi dwoma jXzykami), techniczne (to dlatego istnieje po4a) i ludzkie. Nie wszyscy deweloperzy rozumiejX potrzebX tXumaczeX. Nawet majXc dobre chXci, mogX ignorowaX potrzebX upraszczania pracy tXumaczy. Aby w tym pomoc, po4a dostarcza wiele dokumentacji, do ktorej moXna siX odnosiX.

Innym waXnym punktem jest to, Xe kaXdy plik z tXumaczeniem zaczyna siX od krotkiego komentarza okreXlajXcego, czym jest ten plik i jak go uXyX. Powinno to pomoc deweloperom, zalanym tonami plikow w roXnych jXzykach, 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 pomyXkX. Dlatego wszystkie pliki zawierajX taki nagXowek:

  |       ****************************************************
  |       *         PLIK WYGENEROWANY, NIE EDYTOWAX          *
  |       * TO NIE JEST PLIK XRODXOWY, ALE WYNIK KOMPILACJI  *
  |       ****************************************************
  |
  | Ten plik zostaX wygenerowany przez po4a-translate(1). Nie przechowuj go
  | (na przykXad w CVS-ie), ale przechowuj plik po, uXyty jako plik XrodXowy
  | przez polecenie po4a-translate.
  |
  | Tak naprawdX, potraktuj ten plik jako plik binarny, a plik po jako zwykXy
  | plik XrodXowy: jeXli plik po zaginie, to bXdzie trudniej zachowaX aktualnoXX
  | tego tXumaczenia ;)
 
 

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

  #
  #  RADY DLA DEWELOPEROW:
  #    - nie trzeba rXcznie edytowaX plikow POT i PO.
  #    - ten plik zawiera tXumaczenie Twoich szablonow confiteor.
  #      Nie zastXpuj tXumaczeX Twojego programu tym plikiem !!
  #        (albo tXumacze bXdX na Ciebie wXciekli)
  #
  #  RADY DLA TXUMACZY:
  #    JeXli nie jesteX zaznajomiony z formatem PO, warto przeczytaX
  #    dokumentacjX pakietu gettext, zwXaszcza sekcje poXwiXcone
  #    temu formatowi. Na przykXad uruchom:
  #         info -n "(gettext)PO Files"
  #         info -n "(gettext)Heder Centry"
  #
  #    Informacje specyficzne po-debconf sX dostXpne 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 wykryX, czy tXumaczenia nie sX przestarzaXe.

•

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

•

WewnXtrznie jest oparty na pakiecie "gettext" (ale "po4a" oferuje bardzo prosty interfejs, tak Xe nie ma potrzeby poznawania wewnXtrznych mechanizmow, aby go uXyX). W ten sposob, nie musimy ponownie wymyXlaX koXa, a poniewaX gettext jest szeroko uXywany, mamy nadziejX, Xe w wiXkszym lub mniejszym stopniu jest wolny od bXXdow.

•

Z punktu widzenia koXcowego uXytkownika nic siX nie zmieniXo (poza tym, Xe tXumaczenia sX lepiej zarzXdzane). Wynikowe pliki z dokumentacjX sX tak samo dystrybuowane.

•

TXumacze nie muszX uczyX siX skXadni nowego pliku i mogX po prostu uXyX swojego ulubionego edytora plikow po (jak tryb po emasca, kbabel lub gtranslator).

•

Gettext udostXpnia prosty sposob otrzymania statystyk o tym, co zostaXo zrobione, co powinno byX przejrzane i zaktualizowane, a co jeszcze jest do zrobienia. PrzykXady moXna znaleXX pod tymi adresami:

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

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

•

Na pierwszy rzut oka zaXXczniki sX... dziwne.

•

Nie moXna dostosowywaX tXumaczonego tekstu do wXasnych upodobaX, na przykXad przez podzielenie w danym miejscu na akapity, poXXczenie dwoch innych akapitow w jeden. Jednak w pewnym sensie, jeXeli jest jakiX problem z oryginaXem, powinno to zostaX zgXoszone jako bXXd.

•

Nawet majXc Xatwy interfejs, wciXX pozostaje nowym narzXdziem, ktorego trzeba siX uczyX.

Jednym z moich marzeX 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 siX zrobiX moduX MS Word (TM) (a przynajmniej RFT), to bXdX mogli go nawet uXywaX profesjonalni tXumacze.

Znane bXXdy i i XXdania nowych funkcjonalnoXci

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

ChcielibyXmy wydzieliX czXXX kodu (dotyczXcego wstawiania plikow) moduXu sgml z powrotem do TransTractora, tak Xeby pozostaXe moduXy mogXy z niego korzystaX, ale to nie bXdzie zmiana widoczna dla uXytkownika.

AUTORZY

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

TXUMACZENIE

  Robert Luberda <robert@debian.org>