Rechercher une page de manuel
Locale::Po4a::TransTractor.3pm
Langue: pl
Version: 2010-06-01 (fedora - 01/12/10)
Section: 3 (Bibliothèques de fonctions)
Sommaire
NAZWA
Locale::Po4a::TransTractor - Ogólny moduÅ wyodrÄbniania tÅumaczeÅ.OPIS
Celem projektu po4a (``po for anything'') jest uÅatwienie tÅumaczeÅ (oraz, co ciekawsze, zarzÄ dzania tÅumaczeniami) przy użyciu narzÄdzi gettext w tych obszarach, gdzie nie byÅy używane, jak na przykÅad w obszarze dokumentacji.Ta klasa jest przodkiem wszystkich parserów po4a używanych do przetwarzania dokumentu w poszukiwaniu komunikatów do przetÅumaczenia, wyodrÄbniania ich do pliku po oraz zastÄpowania ich tÅumaczeniami w wyjÅciowym dokumencie.
Bardziej formalnie mówiÄ c, przyjmuje nastÄpujÄ ce argumenty jako wejÅcie:
- -
- dokument do przetÅumaczenia;
- -
- plik po zawierajÄ cy tÅumaczenia do użycia.
Jako wynik dostajemy:
- -
- inny plik po, czego wynikiem jest wyciÄ gniÄcie komunikatów możliwych do przetÅumaczenia z dokumentu wejÅciowego;
- -
- przetÅumaczony dokument o takiej samej strukturze, co dokument wejÅciowy, ale ze wszystkimi komunikatami możliwymi do przetÅumaczenia zamienionymi na tÅumaczenia znalezione w wejÅciowym pliku po.
Graficzna reprezentacja tego procesu:
Dokument wejÅciowy --\ /--> Dokument wyjÅciowy \ / (przetÅumaczony) +-> funkcja parse() ---+ / \ WejÅciowy po --------/ \--> WyjÅciowy po (wyodrÄbniony)
FUNKCJE, KTÃRE TWÃJ PARSER POWINIEN NADPISAÄ
- parse()
- Jest to miejsce, gdzie odbywa siÄ caÅa praca: parsowanie dokumentów wejÅciowych, generowanie wyjÅcia, wyodrÄbnianie komunikatów do przetÅumaczenia. Jest to bardzo proste, jeÅli użyje siÄ funkcji opisanych poniżej, w sekcji ``FUNKCJE WEWNÄTRZNE''. Patrz także sekcja ``SKÅADNIA'', zawierajÄ
ca przykÅad.
Ta funkcja jest wywoÅywana przez poniższÄ funkcjÄ proces(), ale jeżeli wybierze siÄ użycie funkcji new() i rÄczenie siÄ doda zawartoÅÄ do dokumentu, trzeba bÄdzie wywoÅaÄ tÄ funkcjÄ samemu.
- docheader()
- Funkcja zwraca nagÅówek, który powinien zostaÄ dodany do wygenerowanego dokumentu, odpowiednio przygotowany, tak żeby mógÅ byÄ komentarzem w jÄzyku docelowym. Aby dowiedzieÄ siÄ, do czego to sÅuży, proszÄ przeczytaÄ sekcjÄ ``Przekazywanie deweloperom wiedzy o tÅumaczeniu'' w po4a(7).
SKÅADNIA
NastÄpujÄ cy przykÅad przetwarza listÄ akapitów rozpoczynajÄ cych siÄ od ``<p>''. Dla uproszczenia, zakÅadamy, że dokument jest dobrze sformatowany, tj. wystÄpujÄ tylko elementy ``<p>'' i sÄ one umieszczone na samym poczÄ tku każdego 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>. # WÅóż z powrotem bieÅ¼Ä cÄ liniÄ do wejÅcia, # i dodaj zbudowany akapit do wyjÅcia $self->unshiftline($line,$lref); # Teraz, gdy dokument jest sformatowany, przetÅumaczmy go: # - UsuniÄcie poczÄ tkowych tagów $paragraph =~ s/^<p>//s; # - dodanie do wyjÅcia poczÄ tkowego elementu (nieprzetÅumaczonego) # i reszty akapitu (przetÅumaczonej) $self->pushline( "<p>" . $document->translate($paragraph,$pararef) ); next PARAGRAPH; } else { # Dodanie do akapitu $paragraph .= $line; $pararef = $lref unless(length($pararef)); } # Ponowna inicjacja pÄtli ($line,$lref)=$self->shiftline(); } # Nie dostaliÅmy zdefiniowanej linii? Koniec pliku wejÅciowego. return; } }
Po zaimplementowaniu funkcji parsujÄ cej, można użyÄ wÅasnych klas dokumentu, używajÄ c publicznego interfejsu zaprezentowanego w nastÄpnym rozdziale.
INTERFEJS PUBLICZNY dla skryptów używajÄ cych 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 okreÅlone w po_in_name
- b.
- Czyta wszystkie oryginalne dokumenty okreÅlone w file_in_name
- c.
- Przetwarza (parsuje) dokument
- d.
- Dodaje i stosuje wszystkie podane zaÅÄ czniki
- e.
- Zapisuje przetÅumaczony dokument do file_out_name (jeÅli podano)
- f.
- Zapisuje wygenerowany plik po do po_out_name (jeÅli podano)
ARGUMENTY, poza tymi akceptowanymi przez new() (z oczekiwanym typem):-
- file_in_name (@)
- Lista nazw plików, z których powinniÅmy odczytaÄ plik wejÅciowy.
- file_in_charset ($)
- Kodowanie znaków dokumentu wejÅciowego (jeÅli nie podano, nastÄ pi próba okreÅlenia kodowania z dokumentu wejÅciowego).
- file_out_name ($)
- Nazwa pliku, do którego należy zapisaÄ wynikowy dokument.
- file_out_charset ($)
- Kodowanie znaków wyjÅciowego dokumentu (jeÅli nie podano, bÄdzie użyte kodowanie znaków pliku po).
- po_in_name (@)
- Lista nazw plików, z których powinniÅmy odczytaÄ wejÅciowe pliki po zawierajÄ ce tÅumaczenia, które bÄdÄ użyte podczas tÅumaczenia dokumentu.
- po_out_name ($)
- Nazwa pliku, do którego powinien byÄ zapisany wynikowy plik po, zawierajÄ cy komunikaty wyciÄ gniÄte z dokumentu wejÅciowego.
- addendum (@)
- Lista nazw plików, z których powinniÅmy odczytaÄ pliki zaÅÄ czników.
- addendum_charset ($)
- Kodowanie znaków zaÅÄ czników.
-
- new(%)
- Tworzy nowy dokument Po4a. Akceptowane opcje (bÄdÄ
ce w hashu):
-
- verbose ($)
- Ustawia gadatliwoÅÄ.
- debug ($)
- Ustawia debugowanie.
-
Manipulowanie plikami z dokumentacjÄ
- read($)
- Dodaje kolejny dokument wejÅciowy na koniec istniejÄ
cego dokumentu. Argumentem jest nazwa pliku do odczytania.
ProszÄ zauważyÄ, że to niczego nie przetwarza. Należy użyÄ funkcji parse() po zakoÅczeniu pakowania plików wejÅciowych do dokumentu.
- write($)
- Zapisuje przetÅumaczony dokument do pliku o podanej nazwie.
Manipulowanie plikami po
- readpo($)
- Dodaje zawartoÅÄ pliku (którego nazwa jest podawana w argumencie) do istniejÄ cego pliku wejÅciowego po. Stara zawartoÅÄ nie jest tracona.
- writepo($)
- Zapisuje wygenerowany plik po do pliku o podanej nazwie.
- stats()
- Zwraca statystyki dotyczÄ
ce tÅumaczeÅ. ProszÄ zauważyÄ, że nie sÄ
to te same statystyki, które wypisuje msgfmt --statistic. Tutaj sÄ
to statystyki o obecnym wykorzystaniu pliku po, podczas gdy msgfmt wyÅwietla status tego pliku. Funkcja jest opakowaniem funkcji Locale::Po4a::Po::stats_get zastosowanej do wejÅciowego pliku po. PrzykÅad użycia:
[zwykÅe użycie dokumentu po4a ...] ($percent,$hit,$queries) = $document->stats(); print "ZnaleźliÅmy tÅumaczenia $percent\% ($hit z $queries) komunikatów.\n";
Manipulowanie zaÅÄ cznikami
- addendum($)
- WiÄcej informacji o tym, czym sÄ
zaÅÄ
czniki, i jak tÅumacze powinni je pisaÄ, można znaleÅºÄ w po4a(7). Aby dodaÄ zaÅÄ
cznik do przetÅumaczonego dokumentu, wystarczy po prostu tej funkcji przekazaÄ nazwÄ pliku, w którym siÄ znajduje, i gotowe ;)
Funkcja zwraca liczbÄ nie bÄdÄ cÄ nullem lub bÅÄ d.
FUNKCJE WEWNÄTRZNE, używane do pisania parserów
Pobieranie wejÅcia, dostarczanie wyjÅcia
Dostarczone sÄ cztery funkcje pobierania wejÅcia i zwracania wyjÅcia. SÄ one bardzo podobne do shift/unshift i push/pop. Pierwsza para dotyczy wejÅcia, a druga - wyjÅcia. Mnemonik: w wejÅciu interesuje CiÄ pierwsza linia, co daje shift, a w wyjÅciu chcesz dostaÄ wynik na koÅcu, tak jak do robi push.- shiftline()
- Funkcja zwraca kolejnÄ liniÄ z doc_in do przetworzenia oraz jej odnoÅnik (spakowany jako tablica).
- unshiftline($$)
- Zwraca z powrotem liniÄ dokumentu wejÅciowego i jej odnoÅnik.
- pushline($)
- Dodaje nowÄ liniÄ na koniec doc_out.
- popline()
- Pobiera ostatnio wstawionÄ liniÄ z doc_out.
Zaznaczanie ÅaÅcuchów znaków jako możliwych do przetÅumaczenia
Dostarczona jest jedna funkcja obsÅugujÄ ca tekst, który powinien byÄ przetÅumaczony.- translate($$$)
- Argumenty obowiÄ
zkowe:
-
- -
- ÅaÅcuch znaków do przetÅumaczenia
- -
- OdnoÅnik tego komunikatu (tj. pozycja w pliku wejÅciowym)
- -
- Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze; używany w Locale::Po4a::Po::gettextization(); patrz także po4a(7), sekcja Proces przeksztaÅcania do formatu gettext: jak to dziaÅa?)
Funkcja przyjmuje także kilka dodatkowych argumentów. MuszÄ byÄ zorganizowane jako hash. Na przykÅad:-
$self->translate("string","ref","type", 'wrap' => 1);
- wrap
- flaga logiczna okreÅlajÄ ca, czy traktujemy biaÅe znaki w komunikacie jako nieistotne. JeÅli tak, to funkcja przed wyszukaniem lub wyciÄ gniÄciem tÅumaczenia kanonizuje komunikat, a nastÄpnie zawija tekst tÅumaczenia.
- wrapcol
- Kolumna, w której tekst powinien byÄ zawijany (domyÅlnie: 76).
- comment
- Dodatkowy komentarz do dodania do wpisu.
Akcje:-
- -
- Dodaje nowy komunikat, odnoÅnik i typ do po_out.
- -
- Zwraca tÅumaczenie tekstu (znalezione w po_in), tak że parser może zbudowaÄ doc_out.
- -
- ObsÅuguje kodowania znaków, aby zmieniÄ kodowanie komunikatów przed wysÅaniem do po_out i przed zwróceniem tÅumaczeÅ.
-
Różne funkcje
- verbose()
- Zwraca informacjÄ, czy podczas uruchomienia TransTractora, podano opcjÄ verbose.
- debug()
- Zwraca informacjÄ, czy podczas uruchomienia TransTractora podano opcjÄ debug.
- detected_charset($)
- Mówi TransTractorowi, że w dokumencie źródÅowym wykryto nowe kodowanie znaków (podane jako pierwszy argument wywoÅania). Zwykle kodowanie może byÄ odczytane z nagÅówka dokumentu. Pozostawione bÄdzie tylko pierwsze kodowanie znaków, pochodzÄ ce albo z argumentów funkcji process(), albo z dokumentu.
- get_out_charset()
- Funkcja zwraca kodowanie znaków, które powinno byÄ użyte w dokumencie wyjÅciowym (zazwyczaj użyteczne do zamienienia wykrytego kodowania znaków dokumentu wejÅciowego, tam gdzie zostaÅ znaleziony).
Użyje wyjÅciowego kodowania znaków podanego w linii poleceÅ. JeÅli go nie podano, użyje kodowania znaków wejÅciowego pliku po, a jeżeli jako to kodowanie w pliku byÅ ustawiony domyÅlny tekst ``CHARSET'', to zwróci kodowanie znaków wejÅciowego dokumentu, tak że nie zostanie przeprowadzona żadna konwersja kodowaÅ.
- recode_skipped_text($)
- Funkcja zwraca tekst przekazany jako argument przekodowany z kodowania znaków dokumentu wejÅciowego na kodowanie znaków dokumentu wyjÅciowego. Nie jest to potrzebne podczas tÅumaczenia komunikatu (translate() wszystko przekodowuje samodzielnie), ale wtedy, gdy pominiÄto komunikat z dokumentu wejÅciowego, a dokument wyjÅciowy powinien mieÄ spójne kodowanie znaków.
DALSZE WSKAZÃWKI
Mankamentem obecnego TransTractora jest brak obsÅugi dokumentów zawierajÄ cych wszystkie jÄzyki naraz, jak na przykÅad szablony debconf lub pliki .desktop.Aby rozwiÄ zaÄ ten problem, jedynymi potrzebnymi zmianami w interfejsie sÄ :
- -
- pobieranie hasha jak po_in_name (lista dla jÄzyka)
- -
- dodawanie argumentu do przetÅumaczenia, wskazujÄ c jÄzyk docelowy
- -
- stworzenie funkcjÄ pushline_all, która robiÅaby pushline jej zawartoÅci dla wszystkich jÄzyków, używajÄ
c skÅadni podobnej do skÅadni 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>
TÅUMACZENIE
Robert Luberda <robert@debian.org>
Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre