Provided by:
po4a_0.41-1_all 
NAZWA
Locale::Po4a::Xml - konwersja dokumentow XML i pochodnych z/do plikow
PO
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.
Locale::Po4a::XML jest modulem ulatwiajcym tlumaczenie dokumentow XML
do innych jzykow [uywanych przez ludzi].
T/LUMACZENIE Z POMOC PO4A::XML
Tego modulu mona uy bezporednio do obslugi ogolnych dokumentow w
formacie XML. Wycignie on zawarto wszystkich elementow, bez adnych
atrybutow, poniewa to wlanie w elementach jest zapisywany tekst w
wikszoci dokumentow opartych na XML-u.
Istnieje kilka opcji (opisanych w nastpnej sekcji), ktore mog dostosowa
zachowanie do Twoich wymaga. Jeli nie pasuje ono do formatu Twojego
dokumentu, zachcamy do napisania wlasnego modulu dziedziczcego z tego,
opisujcego szczegoly formatu. Szczegoly mona znale w sekcji PRACA
ZMODU/LAMI POCHODNYMI poniej.
OPCJE AKCEPTOWANE PRZEZ MODU/L
Globalna opcja debug powoduje, e ten modul pokae wylczone komunikaty,
aby moc sprawdzi, czy przypadkiem nie pomija czego istotnego.
Opcje tego modulu:
nostrip
Uniemoliwia usuwanie spacji otaczajcych wyodrbnione komunikaty.
wrap
Kanonizuje komunikaty do przetlumaczenia, przyjmujc, e spacje nie s
wanie i tylko slu do zawijania przetlumaczonego dokumentu. T opcj
mona nadpisa opcjami dotyczcymi wlasnych elementow. Patrz opis
opcji "tags" poniej.
caseinsensitive
Powoduje, e elementy i atrybuty s wyszukiwane z pominiciem
rozpoznawania wielkoci liter. Jeli jest to zdefiniowane, to
<BooK>laNG i <BOOK>Lang zostan potraktowane tak samo jak
<book>lang.
includeexternal
Jeeli zdefiniowano, zewntrzne encje s dolczane do wygenerowanego
(przetlumaczonego) dokumentu oraz do wyodrbnionych lacuchow znakow.
Jeeli nie zdefiniowano, bdzie trzeba przetlumaczy zewntrzne encje
jako niezalene dokumenty.
ontagerror
Ta opcja okrela zachowanie modulu, kiedy wykryje bld skladni XML
(element zamykany, ktory nie odpowiada elementowi ostatnio
otwieranemu lub brak jest wartoci atrybutu elementu). Moe przyjmowa
nastpujce wartoci:
fail
Jest to domylna warto. Dzialanie modulu zakoczy si bldem.
warn
Modul wywietli ostrzeenie i bdzie kontynuowal dzialanie,
silent
Modul bdzie kontynuowal bez wypisywania adnych ostrzee.
Prosz zachowa ostrono, uywajc tej opcji. Rekomendowanym zachowaniem
jest poprawienie pliku wejciowego.
tagsonly
Wyodrbnia tylko elementy podane w opcji "tags". W przeciwnym
wypadku wyodrbni wszystkie elementy poza podanymi w tej opcji.
Uwaga: Opcja ta jest przestarzala.
doctype
Lacuch znakow, ktory bdziemy probowali dopasowa do pierwszej linii
typu dokumentu (doctype; jeli zdefiniowany). Jeli nie pasuje, to
zostanie wypisane ostrzeenie, e dokument moe mie niepoprawny typ.
addlang
Lacuch znakow oznaczajcy ciek (np. <bbb><aaa>)) znacznika, do
ktorego powinien zosta dodany atrybut lang="..." . Jzyk jest
zdefiniowany jako nazwa bazowa pliku PO z usunitym rozszerzeniem
.po.
tags
Rozdzielona spacjami lista elementow, ktore maj by przetlumaczone
lub opuszczone. Domylnie podane elementy bd opuszczone, ale uycie
opcji "tagsonly" oznacza, e podane elementy bd jedynymi elementami
wlczonymi. Elementy musz mie posta <aaa>, jednak mona polczy kilka
z nich (<bbb><aaa>), aby okreli, e zawarto elementu <aaa> bdzie
przetlumaczona tylko wtedy, gdy sam element jest zawarty w
elemencie <bbb>.
Mona poda take kilka opcji elementow dodajc pewne znaki na pocztku
hierarchii elementow. Na przyklad mona doda "w" (zawijaj tekst) lub
"W" (nie zawijaj), aby nadpisa domylne zachowanie okrelone przez
globaln opcj "wrap".
Przyklad: W<chapter><title>
Uwaga: Opcja ta jest przestarzala. Prosimy zamiast niej uywa opcji
translated i untranslated.
attributes
Rozdzielona spacjami lista atrybutow elementow, ktore naley
tlumaczy. Mona poda atrybuty, uywajc ich nazwy (na przyklad
"lang"), ale take mona poprzedzi je hierarchi elementow, aby
powiedzie, e ten atrybut bdzie tlumaczony tylko wtedy. gdy jest
zawarty w okrelonym elemencie. Na przyklad <bbb><aaa>lang mowi, e
atrybut lang zostanie przetlumaczony, tylko jeeli jest zawarty w
elemencie <aaa>, ktory jest w elemencie <bbb>.
foldattributes
Nie tlumaczy atrybutow elementow wlczanych. Zamiast tego zastpuje
wszystkie atrybuty elementu przez po4a-id=<id>.
Jest to uyteczne w przypadku atrybutow, ktore nie powinny by
tlumaczone - upraszcza komunikaty do tlumaczenia i zapobiega
pomylkom tlumaczy.
customtag
Rozdzielona spacjami lista elementow, ktore nie powinny by
traktowane jako elementy.Tagi te s traktowane jako wlczane i nie
musz by zamykane.
break
Rozdzielona spacjami lista elementow, ktore powinny przerwa
sekwencj. Domylnie wszystkie elementy przerywaj sekwencj.
Elementu musz by w postaci <aaa>, mona je jednak polczy
(<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).
inline
Rozdzielona spacjami lista elementow, ktore powinny zosta
potraktowane jako wlczane. Domylnie wszystkie elementy przerywaj
sekwencj.
Elementu musz by w postaci <aaa>, mona je jednak polczy
(<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).
placeholder
Rozdzielona spacjami lista elementow, ktore powinny zosta
potraktowane jako wypelniacze miejsca (placeholder). Wypelniacze
miejsca nie przerywaj sekwencji, jednak ich zawarto jest tlumaczona
osobno.
Poloenie wypelniaczy miejsca w bloku bdzie oznaczone lacuchem
znakow podobnym do:
<placeholder type=\"footnote\" id=\"0\"/>
Elementu musz by w postaci <aaa>, mona je jednak polczy
(<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).
nodefault
Rozdzielona spacjami lista elementow, ktorych modul nie powinien
probowa domylnie umieszcza jakiejkolwiek kategorii.
cpp Wspiera dyrektywy preprocesora C. Jeli opcja zostanie wlczona, po4a
bdzie przetwarzal dyrektywy preprocesora jako separatory akapitow.
Jest to wane, jeli plik XML jest przetwarzany przez preprocesor,
poniewa jeli nie uyje si tej opcji, a dyrektywy preprocesora trafi
w rodek linii, to po4a przyjmie, a nale do biecego paragramu, co
spowoduje, e preprocesor ich ju nie rozpozna. Uwaga: dyrektywy
preprocesora musz by umieszczone midzy elementami (nie mog
rozdziela elementu).
translated
Rozdzielona spacjami lista elementow do przetlumaczenia.
Elementu musz by w postaci <aaa>, mona je jednak polczy
(<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).
Mona poda take kilka opcji elementow dodajc pewne znaki na pocztku
hierarchii elementow. Na przyklad mona doda "w" (zawijaj tekst) lub
"W" (nie zawijaj), aby nadpisa domylne zachowanie okrelone przez
globaln opcj "wrap".
Przyklad: W<chapter><title>
untranslated
Rozdzielona spacjami lista elementow, ktore nie maj by tlumaczone.
Elementu musz by w postaci <aaa>, mona je jednak polczy
(<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).
defaulttranslateoption
Domylne kategorie tych elementow ktore nie s tlumaczone
(translated), nietlumaczone (untranslated), przerywaczami (break),
wlczane (inline), ani wypelniaczami miejsca (placeholder).
Jest to zbior liter:
w Elementy powinny by przetlumaczone i mona zmieni formatowanie
zawartoci.
W Elementy powinny by tlumaczone, ale nie mona zmienia
formatowania ich zawartoci.
i Elementy powinny tlumaczone jako wlczane.
p Elementy powinny by tlumaczone jako wypelniacze miejsca.
PRACA Z MODU/LAMI POCHODNYMI
DEFINIOWANIE ELEMENT'OW I ATRYBUT'OW DO PRZET/LUMACZENIA
Najprostsz zmian jest zdefiniowanie elementow i atrybutow, ktore parser
ma przetlumaczy. Powinno by to zrobione w funkcji initialize. Najpierw
trzeba wywola glown funkcj initialize, aby otrzyma opcje linii polece,
a nastpnie doda wlasne definicje do hasha opcji. Aby obsluy nowe opcje
w linii polece, trzeba je zdefiniowa przed wywolaniem glownej funkcji
initialize:
$self->{options}{'new_option'}='';
$self->SUPER::initialize(%options);
$self->{options}{'_default_translated'}.=' <p> <head><title>';
$self->{options}{'attributes'}.=' <p>lang id';
$self->{options}{'_default_inline'}.=' <br>';
$self->treat_options;
W modulach pochodnych naley uywa opcji _default_inline, _default_break,
_default_placeholder, _default_translated, _default_untranslated oraz
_default_attributes. Pozwala to uytkownikom zmieni domylne zachowanie
za pomoc opcji linii polece.
NADPISYWANIE FUNKCJI found_string
Innym prostym krokiem jest nadpisanie funkcji "found_string", ktora
otrzymuje od parsera wycignite komunikaty do przetlumaczenia. Tutaj
mona kontrolowa, ktore komunikaty tlumaczy, oraz przeprowadzi na nich
transformacje zarowno przed tlumaczeniem, jak i po nim.
Otrzymuje wyodrbniony tekst, odnonik do miejsca jego znalezienia i hash
zawierajce dodatkowe informacje kontrolujce, ktore komunikaty s do
przetlumaczenia, jak je przetlumaczy i jak wygenerowa komentarz.
Zawarto tych opcji zaley od rodzaju lacucha znakow (podanego we
rekordzie tego hasha):
type="tag"
Znaleziony lacuch znakow jest zawartoci elementu, ktory mona
przetlumaczy. Wpis "tag_options" zawiera znaki opcji wycignite z
pocztku hierarchii elementow z opcji "tags" modulu.
type="attribute"
Oznacza, e znaleziony tekst jest wartoci atrybutu moliwego do
tlumaczenia. Wpis "attribute" zawiera nazw atrybutu.
Funkcja musi zwroci tekst zastpujcy w tlumaczonym dokumencie tekst
oryginalny. Podstawowy przyklad takiej funkcji:
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
Kolejny prosty przyklad mona znale w nowym module Dia, ktory tylko
filtruje niektore lacuchy znakow.
MODYFIKOWANIE TYP'OW ELEMENT'OW (DO ZROBIENIA)
Jest to jeden z bardziej zloonych procesow, ale pozwala na (prawie)
calkowite dostosowanie do wlasnych potrzeb. Jest oparty na licie
hashow, z ktorych kady okrela sposob zachowania si typu elementu. Lista
powinna by posortowana, tak e elementy bardziej ogolne wystpuj po
bardziej szczegolowych (posortowanych najpierw po kluczach pocztkowych,
a potem kocowych). Aby zdefiniowa typ elementu, trzeba utworzy hash
zawierajcy nastpujce klucze:
beginning
Okrela pocztek elementu, po "<".
end Okrela koniec elementu, przed ">".
breaking
Mowi, e jest to klasa elementow rozdzielajcych. Element
nierozdzielajcy (inline) jest to taki element, ktore moe by pobrany
jako zawarto innego elementu. Moe to przyjmowa wartoci false (0),
true (1) lub undefinded. Jeli zostanie jako undefined, to trzeba
bdzie zdefiniowa funkcje f_breaking, mowic, czy podany element tej
klasy jest elementem rozdzielajcym, czy te nie.
f_breaking
Jest to funkcja, ktora powie, czy nastpny element jest elementem
zamykajcym, czy te nie. Powinna by zdefiniowana, jeli nie
zdefiniowano opcji breaking.
f_extract
Jeli wartoci tego klucza pozostanie undefined, to ogolne funkcje
wyodrbniajce bd musialy wyodrbni ten element samodzielnie. Jest to
uyteczne dla elementow, ktore mog zawiera w sobie inne elementy lub
specjalne struktury, tak eby glowny parser nie oszalal. Funkcja
otrzymuje flag logiczn mowic, czy element powinien zosta usunity z
wejciowego strumienia, czy te nie.
f_translate
Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca
przetlumaczony element (przetlumaczone atrybuty lub wszystkie
potrzebne transformacje) jako pojedynczy lacuch znakow.
FUNKCJE WEWNTRZNE, uywane do pisania parser'ow
PRACA Z ELEMENTAMI
get_path()
Funkcja zwraca ciek biecego elementu od korzenia dokumentu w
formacie <html><body><p>.
Jako argument mona przekaza dodatkow tablic elementow (bez
nawiasow). Elementy te zostan dolczone na kocu biecej cieki.
tag_type()
Funkcja zwraca indeks z listy tag_types, ktory odpowiada nastpnemu
elementowi ze strumienia wejciowego, lub -1 gdy dotarla do koca
pliku wejciowego.
extract_tag($$)
Funkcja zwraca nastpny element ze strumienia wejciowego bez pocztku
i koca, w postaci tablicy i zarzdza odnonikami do pliku wejciowego.
Przyjmuje dwa parametry: typ elementu (zwrocone przez tag_type) i
warto logiczn, okrelajc, czy element powinien zosta usunity ze
strumienia wejciowego.
get_tag_name(@)
Funkcja zwraca nazw nastpnego elementu przekazanego jako argument w
formie tablicy zwracanej przez extract_tag.
breaking_tag()
Funkcja zwraca warto logiczn, ktora mowi, czy nastpny element jest
elementem rozdzielajcym, czy nie (element inline). Nie zmienia
strumienia wejciowego.
treat_tag()
Funkcja tlumaczy nastpny element z rodlowego strumienia, uywajc do
tego wlasnych funkcji kadego typu elementu.
tag_in_list($@)
Funkcja zwraca warto bdc lacuchem znakow, mowic, czy jej pierwszy
argument (hierarchia elementow) pasuje do ktoregokolwiek elementu
jej drugiego argumentu (lista elementow lub hierarchii elementow).
Zwraca 0, jeli nie pasuje. W przeciwnym razie zwraca opcje
dopasowanego elementy (znaki z pocztku elementu) lub 1 (jeli
element nie mial opcji).
PRACA Z ATRYBUTAMI
treat_attributes(@)
Funkcja obsluguje tlumaczenia atrybutow elementow. Pobiera element
bez znacznikow pocztku/koca, a nastpnie szuka atrybutow, tlumaczy
te sporod nich, ktore s przeznaczone do tlumaczenia (podane w opcji
"attributes" modulu). Zwraca prosty tekst z przetlumaczonym
elementem.
PRACA Z OPCJAMI MODU/LU
treat_options()
Funkcja wypelnia wewntrzne struktury zawierajce elementy, atrybuty
i dane wlczane wraz z opcjami modulu (podanymi w linii polece lub w
funkcji initialize).
POBIERANIE TEKSTU Z PLIKU WEJCIOWEGO
get_string_until($%)
Funkcja zwraca tablic z liniami (i odnonikami) z wejciowego
dokumentu dopoki nie znajdzie pierwszego argumentu. Drugim
argumentem jest hash opcji. Warto 0 oznacza wylczenie (domylnie), a
1 - wlczenie.
Poprawne opcje:
include
Powoduje, e zwracana tablica zawiera szukany tekst.
remove
Usuwa zwrocony strumie z wejcia
unquoted
Zapewnia, e szukany tekst nie jest umieszczony w cudzyslowach.
skip_spaces(\@)
Funkcja otrzymuje jako argument odnonik do akapitu (w formacie
zwroconym przez get_string_until), pomija spacje naglowka i zwraca
prosty lacuch znakow.
join_lines(@)
Funkcja zwraca prosty lacuch znakow zawierajcy tekst z tablicy
argumentu (odrzucajc odnoniki).
STATUS MODU/LU
Ten modul umoliwia tlumaczenie elementow i atrybutow.
LISTA RZECZY DO ZROBIENIA
DOCTYPE (ENCJE)
Istnieje minimalna obsluga tlumacze encji. S one tlumaczone jako calo,
a elementy nie s brane pod uwag. Encje wieloliniowe nie s wspierane, a
podczas tlumaczenia tekst encji jest zawsze zawijany.
MODYFIKOWANIE TYPOW ELEMENTOW ODZIEDZICZONYCH MODULOW (przenie struktur
tag_types do hasha $self?)
ZOBACZ TAKE
po4a(7), Locale::Po4a::TransTractor(3pm).
AUTORZY
Jordi Vilalta <jvprat@gmail.com>
Nicolas Francois <nicolas.francois@centraliens.net>
PRAWA AUTORSKIE I LICENCJA
Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>
Copyright (c) 2008-2009 by Nicolas Francois <nicolas.francois@centraliens.net>
Program jest wolnym oprogramowaniem; mona go redystrybuowa i/lub
modyfikowa zgodnie z warunkami licencji GPL (patrz plik COPYING).