Provided by:
po4a_0.41-1_all 
NAZWA
Locale::Po4a::TransTractor - ogolny modul wyodrbniania tlumacze.
OPIS
Celem projektu po4a ("PO for anything") jest ulatwienie tlumacze (oraz,
co ciekawsze, zarzdzania tlumaczeniami) przy uyciu narzdzi gettext w
tych obszarach, gdzie nie byly uywane, jak na przyklad w obszarze
dokumentacji.
Ta klasa jest przodkiem wszystkich parserow po4a uywanych do
przetwarzania dokumentu w poszukiwaniu komunikatow do przetlumaczenia,
wyodrbniania ich do pliku PO oraz zastpowania ich tlumaczeniami w
wyjciowym dokumencie.
Bardziej formalnie mowic, przyjmuje nastpujce argumenty jako wejcie:
- dokument do przetlumaczenia;
- plik PO zawierajcy tlumaczenia do uycia.
Jako wynik dostajemy:
- inny plik PO, czego wynikiem jest wycignicie komunikatow moliwych do
przetlumaczenia z dokumentu wejciowego;
- przetlumaczony dokument o takiej samej strukturze, co dokument
wejciowy, ale ze wszystkimi komunikatami moliwymi do przetlumaczenia
zamienionymi na tlumaczenia znalezione w wejciowym pliku PO.
Graficzna reprezentacja tego procesu:
Dokument wejciowy --\ /--> Dokument wyjciowy
\ / (przetlumaczony)
+-> funkcja parse() ---+
/ \
Wejciowy PO --------/ \--> Wyjciowy PO
(wyodrbniony)
FUNKCJE, KT'ORE TW'OJ PARSER POWINIEN NADPISA
parse()
Jest to miejsce, gdzie odbywa si cala praca: parsowanie dokumentow
wejciowych, generowanie wyjcia, wyodrbnianie komunikatow do
przetlumaczenia. Jest to bardzo proste, jeli uyje si funkcji
opisanych poniej, w sekcji FUNKCJE WEWNTRZNE. Patrz take sekcja
SK/LADNIA, zawierajca przyklad.
Ta funkcja jest wywolywana przez ponisz funkcj proces(), ale jeeli
wybierze si uycie funkcji new() i rczenie si doda zawarto do
dokumentu, trzeba bdzie wywola t funkcj samemu.
docheader()
Funkcja zwraca naglowek, ktory powinien zosta dodany do
wygenerowanego dokumentu, odpowiednio przygotowany, tak eby mogl by
komentarzem w jzyku docelowym. Aby dowiedzie si, do czego to sluy,
prosz przeczyta sekcj Przekazywanie deweloperom wiedzy o
t/lumaczeniu w po4a(7).
SK/LADNIA
Nastpujcy przyklad przetwarza list akapitow rozpoczynajcych si od
"<p>". Dla uproszczenia, zakladamy, e dokument jest dobrze
sformatowany, tj. wystpuj tylko elementy "<p>" i s one umieszczone na
samym pocztku kadego 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>.
# Wlo z powrotem biec lini do wejcia,
# i dodaj zbudowany akapit do wyjcia
$self->unshiftline($line,$lref);
# Teraz, gdy dokument jest sformatowany, przetlumaczmy go:
# - Usunicie pocztkowych tagow
$paragraph =~ s/^<p>//s;
# - dodanie do wyjcia pocztkowego elementu (nieprzetlumaczonego)
# i reszty akapitu (przetlumaczonej)
$self->pushline( "<p>"
. $document->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Dodanie do akapitu
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Ponowna inicjacja ptli
($line,$lref)=$self->shiftline();
}
# Nie dostalimy zdefiniowanej linii? Koniec pliku wejciowego.
return;
}
}
Po zaimplementowaniu funkcji parsujcej, mona uy wlasnych klas
dokumentu, uywajc publicznego interfejsu zaprezentowanego w nastpnym
rozdziale.
INTERFEJS PUBLICZNY dla skrypt'ow uywajcych Twojego parsera
Konstruktor
process(%)
Funkcja zrobi w jednym uruchomieniu wszystko, co tylko trzeba
zrobi z dokumentem po4a. Jej argumenty musz by umieszczone w hashu.
AKCJE:
a. Czyta wszystkie pliki okrelone w po_in_name
b. Czyta wszystkie oryginalne dokumenty okrelone w file_in_name
c. Przetwarza (parsuje) dokument
d. Dodaje i stosuje wszystkie podane zalczniki
e. Zapisuje przetlumaczony dokument do file_out_name (jeli podano)
f. Zapisuje wygenerowany plik PO do po_out_name (jeli podano)
ARGUMENTY, poza tymi akceptowanymi przez new() (z oczekiwanym
typem):
file_in_name (@)
Lista nazw plikow, z ktorych powinnimy odczyta plik wejciowy.
file_in_charset ($)
Kodowanie znakow dokumentu wejciowego (jeli nie podano, nastpi
proba okrelenia kodowania z dokumentu wejciowego).
file_out_name ($)
Nazwa pliku, do ktorego naley zapisa wynikowy dokument.
file_out_charset ($)
Kodowanie znakow wyjciowego dokumentu (jeli nie podano, bdzie
uyte kodowanie znakow pliku PO).
po_in_name (@)
Lista nazw plikow, z ktorych powinnimy odczyta wejciowe pliki
PO zawierajce tlumaczenia, ktore bd uyte podczas tlumaczenia
dokumentu.
po_out_name ($)
Nazwa pliku, do ktorego powinien by zapisany wynikowy plik PO,
zawierajcy komunikaty wycignite z dokumentu wejciowego.
addendum (@)
Lista nazw plikow, z ktorych powinnimy odczyta pliki
zalcznikow.
addendum_charset ($)
Kodowanie znakow zalcznikow.
new(%)
Tworzy nowy dokument po4a. Akceptowane opcje (bdce w hashu):
verbose ($)
Ustawia gadatliwo.
debug ($)
Ustawia debugowanie.
Manipulowanie plikami z dokumentacj
read($)
Dodaje kolejny dokument wejciowy na koniec istniejcego dokumentu.
Argumentem jest nazwa pliku do odczytania.
Prosz zauway, e to niczego nie przetwarza. Naley uy funkcji parse()
po zakoczeniu pakowania plikow wejciowych do dokumentu.
write($)
Zapisuje przetlumaczony dokument do pliku o podanej nazwie.
Manipulowanie plikami PO
readpo($)
Dodaje zawarto pliku (ktorego nazwa jest podawana w argumencie) do
istniejcego pliku wejciowego PO. Stara zawarto nie jest tracona.
writepo($)
Zapisuje wygenerowany plik PO do pliku o podanej nazwie.
stats()
Zwraca statystyki dotyczce tlumacze. Prosz zauway, e nie s to te
same statystyki, ktore wypisuje msgfmt --statistic. Tutaj s to
statystyki o obecnym wykorzystaniu pliku PO, podczas gdy msgfmt
wywietla status tego pliku. Funkcja jest opakowaniem funkcji
Locale::Po4a::Po::stats_get zastosowanej do wejciowego pliku PO.
Przyklad uycia:
[zwykle uycie dokumentu po4a ...]
($percent,$hit,$queries) = $document->stats();
print "Znalelimy tlumaczenia $percent\% ($hit z $queries) komunikatow.\n";
Manipulowanie za/lcznikami
addendum($)
Wicej informacji o tym, czym s zalczniki, i jak tlumacze powinni je
pisa, mona znale w po4a(7). Aby doda zalcznik do przetlumaczonego
dokumentu, wystarczy po prostu tej funkcji przekaza nazw pliku, w
ktorym si znajduje, i gotowe ;)
Funkcja zwraca liczb nie bdc nullem lub bld.
FUNKCJE WEWNTRZNE, uywane do pisania parser'ow
Pobieranie wejcia, dostarczanie wyjcia
Dostarczone s cztery funkcje pobierania wejcia i zwracania wyjcia. S
one bardzo podobne do shift/unshift i push/pop. Pierwsza para dotyczy
wejcia, a druga - wyjcia. Mnemonik: w wejciu interesuje Ci pierwsza
linia, co daje shift, a w wyjciu chcesz dosta wynik na kocu, tak jak do
robi push.
shiftline()
Funkcja zwraca kolejn lini z doc_in do przetworzenia oraz jej
odnonik (spakowany jako tablica).
unshiftline($$)
Zwraca z powrotem lini dokumentu wejciowego i jej odnonik.
pushline($)
Dodaje now lini na koniec doc_out.
popline()
Pobiera ostatnio wstawion lini z doc_out.
Zaznaczanie /lacuch'ow znak'ow jako moliwych do przet/lumaczenia
Dostarczona jest jedna funkcja obslugujca tekst, ktory powinien by
przetlumaczony.
translate($$$)
Argumenty obowizkowe:
- Lacuch znakow do przetlumaczenia
- Odnonik tego komunikatu (tj. pozycja w pliku wejciowym)
- Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze;
uywany w Locale::Po4a::Po::gettextization(); patrz take po4a(7),
sekcja Proces przekszta/lcania do formatu gettext: jak to dzia/la?)
Funkcja przyjmuje take kilka dodatkowych argumentow. Musz by
zorganizowane jako hash. Na przyklad:
$self->translate("string","ref","type",
'wrap' => 1);
wrap
flaga logiczna okrelajca, czy traktujemy biale znaki w
komunikacie jako nieistotne. Jeli tak, to funkcja przed
wyszukaniem lub wycigniciem tlumaczenia kanonizuje komunikat, a
nastpnie zawija tekst tlumaczenia.
wrapcol
kolumna, w ktorej tekst powinien by zawijany (domylnie: 76).
comment
dodatkowy komentarz do dodania do wpisu.
Akcje:
- Dodaje nowy komunikat, odnonik i typ do po_out.
- Zwraca tlumaczenie tekstu (znalezione w po_in), tak e parser moe
zbudowa doc_out.
- Obsluguje kodowania znakow, aby zmieni kodowanie komunikatow
przed wyslaniem do po_out i przed zwroceniem tlumacze.
R'one funkcje
verbose()
Zwraca informacj, czy podczas uruchomienia TransTractora, podano
opcj verbose.
debug()
Zwraca informacj, czy podczas uruchomienia TransTractora podano
opcj debug.
detected_charset($)
Mowi TransTractorowi, e w dokumencie rodlowym wykryto nowe
kodowanie znakow (podane jako pierwszy argument wywolania). Zwykle
kodowanie moe by odczytane z naglowka dokumentu. Pozostawione bdzie
tylko pierwsze kodowanie znakow, pochodzce albo z argumentow
funkcji process(), albo z dokumentu.
get_out_charset()
Funkcja zwraca kodowanie znakow, ktore powinno by uyte w dokumencie
wyjciowym (zazwyczaj uyteczne do zamienienia wykrytego kodowania
znakow dokumentu wejciowego, tam gdzie zostal znaleziony).
Uyje wyjciowego kodowania znakow podanego w linii polece. Jeli go
nie podano, uyje kodowania znakow wejciowego pliku PO, a jeeli jako
to kodowanie w pliku byl ustawiony domylny tekst "CHARSET", to
zwroci kodowanie znakow wejciowego dokumentu, tak e nie zostanie
przeprowadzona adna konwersja kodowa.
recode_skipped_text($)
Funkcja zwraca tekst przekazany jako argument przekodowany z
kodowania znakow dokumentu wejciowego na kodowanie znakow dokumentu
wyjciowego. Nie jest to potrzebne podczas tlumaczenia komunikatu
(translate() wszystko przekodowuje samodzielnie), ale wtedy, gdy
pominito komunikat z dokumentu wejciowego, a dokument wyjciowy
powinien mie spojne kodowanie znakow.
DALSZE WSKAZ'OWKI
Mankamentem obecnego TransTractora jest brak obslugi dokumentow
zawierajcych wszystkie jzyki naraz, jak na przyklad szablony debconf
lub pliki .desktop.
Aby rozwiza ten problem, jedynymi potrzebnymi zmianami w interfejsie s:
- pobieranie hasha jak po_in_name (lista dla jzyka)
- dodawanie argumentu do przetlumaczenia, wskazujc jzyk docelowy
- stworzenie funkcj pushline_all, ktora robilaby pushline jej zawartoci
dla wszystkich jzykow, uywajc skladni podobnej do skladni map:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Zobaczymy, czy to wystarczy ;)
AUTORZY
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>