blib::man::TransTractor(3pm)

NAZWA
Po4a TransTractor - Ogolny moduX wyodrebniania tXumaczen~.

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

Ta klasa jest przodkiem wszystkich parserow po4a uXywanych do przetwarzania dokumentu w poszukiwaniu komunikatow do przetXumaczenia, wyodrebniania ich do pliku po oraz zastepowania ich tXumaczeniami w wyjXciowym dokumencie.

Bardziej formalnie mowiXc, przyjmuje nastepujXce argumenty jako wejXcie:

-   dokument do przetXumaczenia;

-   plik po zawierajXcy tXumaczenia do uXycia.

Jako wynik dostajemy:

-   inny plik po, czego wynikiem jest wyciXgniecie komunikatow moXliwych do przetXumaczenia z dokumentu wejXciowego;

-   przetXumaczony dokument o takiej samej strukturze, co dokument wejXciowy, ale ze wszystkimi komunikatami moXliwymi do przetXumaczenia zamienionymi na tXumaczenia znalezione w wejXciowym pliku po.

Graficzna reprezentacja tego procesu:

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

FUNKCJE, KTORE TWOJ PARSER POWINIEN NADPISAAE

parse()
    Jest to miejsce, gdzie odbywa sie caXa praca: parsowanie dokumentow wejXciowych, generowanie wyjXcia, wyodrebnianie komunikatow do przetXumaczenia. Jest to bardzo proste, jeXli uXyje sie funkcji opisanych poniXej, w sekcji "FUNKCJE WEWNETRZNE". Patrz takXe sekcja "SKXADNIA", zawierajXca przykXad.

    Ta funkcja jest wywoXywana przez poniXszX funkcje proces(), ale jeXeli wybierze sie uXycie funkcji new() i reczenie sie doda zawartoXae do dokumentu, trzeba bedzie wywoXaae te funkcje samemu.

docheader()
    Funkcja zwraca nagXowek, ktory powinien zostaae dodany do wygenerowanego dokumentu, odpowiednio przygotowany, tak Xeby mogX byae komentarzem w jezyku docelowym. Aby dowiedzieae sie, do czego to sXuXy, prosze przeczytaae sekcje "Przekazywanie deweloperom wiedzy o tXumaczeniu" w po4a(7).

SKXADNIA
NastepujXcy przykXad przetwarza liste akapitow rozpoczynajXcych sie od "<p>". Dla uproszczenia, zakXadamy, Xe dokument jest dobrze sformatowany, tj. wystepujX tylko elementy "<p>" i sX one umieszczone na samym poczXtku kaXdego akapitu.

 sub parse {
   my $self = shift;

   PARAGRAPH: while (1) {
       my ($paragraph,$pararef)=("","");
       my $first=1;
       my ($line,$lref)=$self->shiftline();
       while (defined($line)) {
           if ($line =~ m/<p>/ && !$first--; ) {
               # Nie po raz pierwszy widzimy <p>.
               # WXoX z powrotem bieXXcX linie do wejXcia,
               #  i dodaj zbudowany akapit do wyjXcia
               $self->unshiftline($line,$lref);

               # Teraz, gdy dokument jest sformatowany, przetXumaczmy go:
               #   - Usuniecie poczXtkowych tagow
               $paragraph =~ s/^<p>//s;

               #   - dodanie do wyjXcia poczXtkowego elementu (nieprzetXumaczonego)
               #     i reszty akapitu (przetXumaczonej)
               $self->pushline(  "<p>"
                               . $document->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Dodanie do akapitu
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Ponowna inicjacja petli
           ($line,$lref)=$self->shiftline();
       }
       # Nie dostaliXmy zdefiniowanej linii? Koniec pliku wejXciowego.
       return;
   }
 }

Po zaimplementowaniu funkcji parsujXcej, moXna uXyae wXasnych klas dokumentu, uXywajXc publicznego interfejsu zaprezentowanego w nastepnym rozdziale.

INTERFEJS PUBLICZNY dla skryptow uXywajXcych Twojego parsera

  Konstruktor

process(%)
    Funkcja zrobi w jednym uruchomieniu wszystko, co tylko trzeba zrobiae z dokumentem po4a. Jej argumenty muszX byae umieszczone w hashu. AKCJE:

    a.  Czyta wszystkie pliki okreXlone w po_in_name

    b.  Czyta wszystkie oryginalne dokumenty okreXlone w file_in_name

    c.  Przetwarza (parsuje) dokument

    d.  Dodaje i stosuje wszystkie podane zaXXczniki

    e.  Zapisuje przetXumaczony dokument do file_out_name (jeXli podano)

    f.  Zapisuje wygenerowany plik po do po_out_name (jeXli podano)

    ARGUMENTY, poza tymi akceptowanymi przez new() (z oczekiwanym typem):

    file_in_name (@)
        Lista nazw plikow, z ktorych powinniXmy odczytaae plik wejXciowy.

    file_in_charset ($)
        Kodowanie znakow dokumentu wejXciowego (jeXli nie podano, nastXpi proba okreXlenia kodowania z dokumentu wejXciowego).

    file_out_name ($)
        Nazwa pliku, do ktorego naleXy zapisaae wynikowy dokument.

    file_out_charset ($)
        Kodowanie znakow wyjXciowego dokumentu (jeXli nie podano, bedzie uXyte kodowanie znakow pliku po).

    po_in_name (@)
        Lista nazw plikow, z ktorych powinniXmy odczytaae wejXciowe pliki po zawierajXce tXumaczenia, ktore bedX uXyte podczas tXumaczenia dokumentu.

    po_out_name ($)
        Nazwa pliku, do ktorego powinien byae zapisany wynikowy plik po, zawierajXcy komunikaty wyciXgniete z dokumentu wejXciowego.

    addendum (@)
        Lista nazw plikow, z ktorych powinniXmy odczytaae pliki zaXXcznikow.

    addendum_charset ($)
        Kodowanie znakow zaXXcznikow.

new(%)
    Tworzy nowy dokument Po4a. Akceptowane opcje (bedXce w hashu):

    verbose ($)
        Ustawia gadatliwoXae.

    debug ($)
        Ustawia debugowanie.

  Manipulowanie plikami z dokumentacjX

read($)
    Dodaje kolejny dokument wejXciowy na koniec istniejXcego dokumentu. Argumentem jest nazwa pliku do odczytania.

    Prosze zauwaXyae, Xe to niczego nie przetwarza. NaleXy uXyae funkcji parse() po zakon~czeniu pakowania plikow wejXciowych do dokumentu.

write($)
    Zapisuje przetXumaczony dokument do pliku o podanej nazwie.

  Manipulowanie plikami po

readpo($)
    Dodaje zawartoXae pliku (ktorego nazwa jest podawana w argumencie) do istniejXcego pliku wejXciowego po. Stara zawartoXae nie jest tracona.

writepo($)
    Zapisuje wygenerowany plik po do pliku o podanej nazwie.

stats()
    Zwraca statystyki dotyczXce tXumaczen~. Prosze zauwaXyae, Xe nie sX to te same statystyki, ktore wypisuje msgfmt --statistic. Tutaj sX to statystyki o obecnym wykorzystaniu pliku po, podczas gdy msgfmt wyXwietla status tego pliku. Funkcja jest opakowaniem funkcji Locale::Po4a::Po::stats_get zastosowanej do wejXciowego pliku po. PrzykXad uXycia:

        [zwykXe uXycie dokumentu po4a ...]

        ($percent,$hit,$queries) = $document->stats();
        print "ZnaleXliXmy tXumaczenia $percent\% ($hit z $queries) komunikatow.\n";

  Manipulowanie zaXXcznikami

addendum($)
    Wiecej informacji o tym, czym sX zaXXczniki, i jak tXumacze powinni je pisaae, moXna znaleXae w po4a(7). Aby dodaae zaXXcznik do przetXumaczonego dokumentu, wystarczy po prostu tej funkcji przekazaae nazwe pliku, w ktorym sie znajduje, i gotowe ;)

    Funkcja zwraca liczbe nie bedXcX nullem lub bXXd.

FUNKCJE WEWNETRZNE, uXywane do pisania parserow

  Pobieranie wejXcia, dostarczanie wyjXcia
Dostarczone sX cztery funkcje pobierania wejXcia i zwracania wyjXcia. SX one bardzo podobne do shift/unshift i push/pop. Pierwsza para dotyczy wejXcia, a druga - wyjXcia. Mnemonik: w wejXciu interesuje Cie pierwsza linia, co daje shift, a w wyjXciu chcesz dostaae wynik na kon~cu, tak jak do robi push.

shiftline()
    Funkcja zwraca kolejnX linie z doc_in do przetworzenia oraz jej odnoXnik (spakowany jako tablica).

unshiftline($$)
    Zwraca z powrotem linie dokumentu wejXciowego i jej odnoXnik.

pushline($)
    Dodaje nowX linie na koniec doc_out.

popline()
    Pobiera ostatnio wstawionX linie z doc_out.

  Zaznaczanie Xan~cuchow znakow jako moXliwych do przetXumaczenia
Dostarczona jest jedna funkcja obsXugujXca tekst, ktory powinien byae przetXumaczony.

translate($$$)
    Argumenty obowiXzkowe:

    -   Xan~cuch znakow do przetXumaczenia

    -   OdnoXnik tego komunikatu (tj. pozycja w pliku wejXciowym)

    -   Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze; uXywany w Locale::Po4a::Po::gettextization(); patrz takXe po4a(7), sekcja Proces przeksztaXcania do formatu gettext: jak to dziaXa?)

    Funkcja przyjmuje takXe kilka dodatkowych argumentow. MuszX byae zorganizowane jako hash. Na przykXad:

      $self->translate("string","ref","type",
            \t   'wrap' => 1);

    wrap
        flaga logiczna okreXlajXca, czy traktujemy biaXe znaki w komunikacie jako nieistotne. JeXli tak, to funkcja przed wyszukaniem lub wyciXgnieciem tXumaczenia kanonizuje komunikat, a nastepnie zawija tekst tXumaczenia.

    wrapcol
        Kolumna, w ktorej tekst powinien byae zawijany (domyXlnie: 76).

    comment
        Dodatkowy komentarz do dodania do wpisu.

    Akcje:

    -   Dodaje nowy komunikat, odnoXnik i typ do po_out.

    -   Zwraca tXumaczenie tekstu (znalezione w po_in), tak Xe parser moXe zbudowaae doc_out.

    -   ObsXuguje kodowania znakow, aby zmieniae kodowanie komunikatow przed wysXaniem do po_out i przed zwroceniem tXumaczen~.

  RoXne funkcje

verbose()
    Zwraca informacje, czy podczas uruchomienia TransTractora, podano opcje verbose.

debug()
    Zwraca informacje, czy podczas uruchomienia TransTractora podano opcje debug.

detected_charset($)
    Mowi TransTractorowi, Xe w dokumencie XrodXowym wykryto nowe kodowanie znakow (podane jako pierwszy argument wywoXania). Zwykle kodowanie moXe byae odczytane z nagXowka dokumentu. Pozostawione bedzie tylko pierwsze kodowanie znakow, pochodzXce albo z argumentow funkcji process(), albo z dokumentu.

get_out_charset()
    Funkcja zwraca kodowanie znakow, ktore powinno byae uXyte w dokumencie wyjXciowym (zazwyczaj uXyteczne do zamienienia wykrytego kodowania znakow dokumentu wejXciowego, tam gdzie zostaX znaleziony).

    UXyje wyjXciowego kodowania znakow podanego w linii polecen~. JeXli go nie podano, uXyje kodowania znakow wejXciowego pliku po, a jeXeli jako to kodowanie w pliku byX ustawiony domyXlny tekst "CHARSET", to zwroci kodowanie znakow wejXciowego dokumentu, tak Xe nie zostanie przeprowadzona Xadna konwersja kodowan~.

recode_skipped_text($)
    Funkcja zwraca tekst przekazany jako argument przekodowany z kodowania znakow dokumentu wejXciowego na kodowanie znakow dokumentu wyjXciowego. Nie jest to potrzebne podczas tXumaczenia komunikatu (translate() wszystko przekodowuje samodzielnie), ale wtedy, gdy pominieto komunikat z dokumentu wejXciowego, a dokument wyjXciowy powinien mieae spojne kodowanie znakow.

DALSZE WSKAZOWKI
Mankamentem obecnego TransTractora jest brak obsXugi dokumentow zawierajXcych wszystkie jezyki naraz, jak na przykXad szablony debconf lub pliki .desktop.

Aby rozwiXzaae ten problem, jedynymi potrzebnymi zmianami w interfejsie sX:

-   pobieranie hasha jak po_in_name (lista dla jezyka)

-   dodawanie argumentu do przetXumaczenia, wskazujXc jezyk docelowy

-   stworzenie funkcje pushline_all, ktora robiXaby pushline jej zawartoXci dla wszystkich jezykow, uXywajXc skXadni podobnej do skXadni map:

        $self->pushline_all({ "Description[".$langcode."]=".
            \t        $self->translate($line,$ref,$langcode)
            \t        });

Zobaczymy, czy to wystarczy ;)

AUTORZY
 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>

TXUMACZENIE
 Robert Luberda <robert@debian.org>