". Dla uproszczenia, zakladamy, ze dokument jest dobrze sformatowany, tj. wystepuja tylko elementy "
" i sa one umieszczone na samym poczatku kazdego 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/
/ && !$first--; ) { # Not the first time we see
. # Reput the current line in input, # and put the built paragraph to output $self->unshiftline($line,$lref); # Now that the document is formed, translate it: # - Remove the leading tag $paragraph =~ s/^
//s; # - push to output the leading tag (untranslated) and the # rest of the paragraph (translated) $self->pushline( "
"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Append to the paragraph
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinit the loop
($line,$lref)=$self->shiftline();
}
# Did not get a defined line? End of input file.
return;
}
}
Po zaimplementowaniu funkcji parsujacej, mozna uzyc wlasnych klas
dokumentu, uzywajac publicznego interfejsu zaprezentowanego w nastepnym
rozdziale.
INTERFEJS PUBLICZNY dla skryptow uzywajacych Twojego parsera
Konstruktor
process(%)
Funkcja zrobi w jednym uruchomieniu wszystko, co tylko trzeba
zrobic z dokumentem po4a. Jej argumenty musza byc umieszczone w
hashu. AKCJE:
a. Czyta wszystkie pliki okreslone w po_in_name
b. Czyta wszystkie oryginalne dokumenty okreslone w file_in_name
c. Przetwarza (parsuje) dokument
d. Dodaje i stosuje wszystkie podane zalaczniki
e. Zapisuje przetlumaczony dokument do file_out_name (jesli podano)
f. Zapisuje wygenerowany plik PO do po_out_name (jesli podano)
ARGUMENTY, poza tymi akceptowanymi przez new() (z oczekiwanym
typem):
file_in_name (@)
Lista nazw plikow, z ktorych powinnismy odczytac plik
wejsciowy.
file_in_charset ($)
Charset used in the input document (if it isn't specified, use
UTF-8).
file_out_name ($)
Nazwa pliku, do ktorego nalezy zapisac wynikowy dokument.
file_out_charset ($)
Charset used in the output document (if it isn't specified, use
UTF-8).
po_in_name (@)
Lista nazw plikow, z ktorych powinnismy odczytac wejsciowe
pliki PO zawierajace tlumaczenia, ktore beda uzyte podczas
tlumaczenia dokumentu.
po_out_name ($)
Nazwa pliku, do ktorego powinien byc zapisany wynikowy plik PO,
zawierajacy komunikaty wyciagniete z dokumentu wejsciowego.
addendum (@)
Lista nazw plikow, z ktorych powinnismy odczytac pliki
zalacznikow.
addendum_charset ($)
Kodowanie znakow zalacznikow.
new(%)
Create a new po4a document. Accepted options (in the hash passed as
a parameter):
verbose ($)
Ustawia gadatliwosc.
debug ($)
Ustawia debugowanie.
wrapcol ($)
The column at which we should wrap text in output document
(default: 76).
The negative value means not to wrap lines at all.
Also it accepts next options for underlying Po-files: porefs,
copyright-holder, msgid-bugs-address, package-name,
package-version, wrap-po.
Manipulowanie plikami z dokumentacja
read($$$)
Add another input document data at the end of the existing array
"@{$self->{TT}{doc_in}}".
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the
PO file;
* The charset to use to read that file (UTF-8 by default)
This array "@{$self->{TT}{doc_in}}" holds this input document data
as an array of strings with alternating meanings.
* The string $textline holding each line of the input text data.
* The string "$filename:$linenum" holding its location and called
as
"reference" ("linenum" starts with 1).
Prosze zauwazyc, ze to niczego nie przetwarza. Nalezy uzyc funkcji
parse() po zakonczeniu pakowania plikow wejsciowych do dokumentu.
write($)
Zapisuje przetlumaczony dokument do pliku o podanej nazwie.
This translated document data are provided by:
* "$self->docheader()" holding the header text for the plugin, and
* "@{$self->{TT}{doc_out}}" holding each line of the main
translated text in the array.
Manipulowanie plikami PO
readpo($)
Dodaje zawartosc pliku (ktorego nazwa jest podawana w argumencie)
do istniejacego pliku wejsciowego PO. Stara zawartosc nie jest
tracona.
writepo($)
Zapisuje wygenerowany plik PO do pliku o podanej nazwie.
stats()
Zwraca statystyki dotyczace tlumaczen. Prosze zauwazyc, ze nie sa
to te same statystyki, ktore wypisuje msgfmt --statistic. Tutaj sa
to statystyki o obecnym wykorzystaniu pliku PO, podczas gdy msgfmt
wyswietla status tego pliku. Funkcja jest opakowaniem funkcji
Locale::Po4a::Po::stats_get zastosowanej do wejsciowego pliku PO.
Przyklad uzycia:
[normal use of the po4a document...]
($percent,$hit,$queries) = $document->stats();
print "We found translations for $percent\% ($hit from $queries) of strings.\n";
Manipulowanie zalacznikami
addendum($)
Wiecej informacji o tym, czym sa zalaczniki, i jak tlumacze powinni
je pisac, mozna znalezc w po4a(7). Aby dodac zalacznik do
przetlumaczonego dokumentu, wystarczy po prostu tej funkcji
przekazac nazwe pliku, w ktorym sie znajduje, i gotowe ;)
Funkcja zwraca liczbe nie bedaca nullem lub blad.
FUNKCJE WEWNETRZNE, uzywane do pisania parserow
Pobieranie wejscia, dostarczanie wyjscia
Dostarczone sa cztery funkcje pobierania wejscia i zwracania wyjscia.
Sa one bardzo podobne do shift/unshift i push/pop w Perlu.
* Perl shift returns the first array item and drop it from the array.
* Perl unshift prepends an item to the array as the first array item.
* Perl pop returns the last array item and drop it from the array.
* Perl push appends an item to the array as the last array item.
Pierwsza para dotyczy wejscia, a druga - wyjscia. Mnemonik: w wejsciu
interesuje Cie pierwsza linia, co daje shift, a w wyjsciu chcesz dostac
wynik na koncu, tak jak do robi push.
shiftline()
This function returns the first line to be parsed and its
corresponding reference (packed as an array) from the array
"@{$self->{TT}{doc_in}}" and drop these first 2 array items. Here,
the reference is provided by a string "$filename:$linenum".
unshiftline($$)
Unshifts the last shifted line of the input document and its
corresponding reference back to the head of
"{$self->{TT}{doc_in}}".
pushline($)
Push a new line to the end of "{$self->{TT}{doc_out}}".
popline()
Pop the last pushed line from the end of "{$self->{TT}{doc_out}}".
Zaznaczanie lancuchow znakow jako mozliwych do przetlumaczenia
Dostarczona jest jedna funkcja obslugujaca tekst, ktory powinien byc
przetlumaczony.
translate($$$)
Argumenty obowiazkowe:
- Lancuch znakow do przetlumaczenia
- Odnosnik tego komunikatu (tj. pozycja w pliku wejsciowym)
- Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze;
uzywany w Locale::Po4a::Po::gettextization(); patrz takze
po4a(7), sekcja Proces przeksztalcania do formatu gettext: jak to
dziala?)
Funkcja przyjmuje takze kilka dodatkowych argumentow. Musza byc
zorganizowane jako hash. Na przyklad:
$self->translate("string","ref","type",
'wrap' => 1);
wrap
flaga logiczna okreslajaca, czy traktujemy biale znaki w
komunikacie jako nieistotne. Jesli tak, to funkcja przed
wyszukaniem lub wyciagnieciem tlumaczenia kanonizuje komunikat,
a nastepnie zawija tekst tlumaczenia.
wrapcol
the column at which we should wrap (default: the value of
wrapcol specified during creation of the TransTractor or 76).
The negative value will be substracted from the default.
comment
dodatkowy komentarz do dodania do wpisu.
Akcje:
- Dodaje nowy komunikat, odnosnik i typ do po_out.
- Zwraca tlumaczenie tekstu (znalezione w po_in), tak ze parser
moze zbudowac doc_out.
- Obsluguje kodowania znakow, aby zmienic kodowanie komunikatow
przed wyslaniem do po_out i przed zwroceniem tlumaczen.
Rozne funkcje
verbose()
Zwraca informacje, czy podczas uruchomienia TransTractora, podano
opcje verbose.
debug()
Zwraca informacje, czy podczas uruchomienia TransTractora podano
opcje debug.
get_in_charset()
This function return the charset that was provided as master
charset
get_out_charset()
Funkcja zwraca kodowanie znakow, ktore powinno byc uzyte w
dokumencie wyjsciowym (zazwyczaj uzyteczne do zamienienia wykrytego
kodowania znakow dokumentu wejsciowego, tam gdzie zostal
znaleziony).
Uzyje wyjsciowego kodowania znakow podanego w linii polecen. Jesli
go nie podano, uzyje kodowania znakow wejsciowego pliku PO, a
jezeli jako to kodowanie w pliku byl ustawiony domyslny tekst
"CHARSET", to zwroci kodowanie znakow wejsciowego dokumentu, tak ze
nie zostanie przeprowadzona zadna konwersja kodowan.
DALSZE WSKAZOWKI
Mankamentem obecnego TransTractora jest brak obslugi dokumentow
zawierajacych wszystkie jezyki naraz, jak na przyklad szablony debconf
lub pliki .desktop.
Aby rozwiazac ten problem, jedynymi potrzebnymi zmianami w interfejsie
sa:
- pobieranie hasha jak po_in_name (lista dla jezyka)
- dodawanie argumentu do przetlumaczenia, wskazujac jezyk docelowy
- make a pushline_all function, which would make pushline of its
content for all languages, using a map-like syntax:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Zobaczymy, czy to wystarczy ;)
AUTORZY
Denis Barbier