Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Xml.3pm

NAZWA

Locale::Po4a::Xml - Konwersja dokumentow XML i pochodnych z/do plikow PO

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.

Locale::Po4a::XML jest moduXem uXatwiajXcym tXumaczenie dokumentow XML do innych jezykow [uXywanych przez ludzi].

TXUMACZENIE Z POMOCX PO4A::XML

Tego moduXu moXna uXyae bezpoXrednio do obsXugi ogolnych dokumentow w formacie XML. WyciXgnie on zawartoXae wszystkich elementow, bez Xadnych atrybutow, poniewaX to wXaXnie w elementach jest zapisywany tekst w wiekszoXci dokumentow opartych na XML-u.

Istnieje kilka opcji (opisanych w nastepnej sekcji), ktore mogX dostosowaae zachowanie do Twoich wymagan~. JeXli nie pasuje ono do formatu Twojego dokumentu, zachecamy do napisania wXasnego moduXu dziedziczXcego z tego, opisujXcego szczegoXy formatu. SzczegoXy moXna znaleXae w sekcji ``Pisanie moduXow pochodnych'' poniXej.

OPCJE AKCEPTOWANE PRZEZ TEN MODUX

Globalna opcja debug powoduje, Xe ten moduX pokaXe wyXXczone komunikaty, aby moc sprawdziae, czy przypadkiem nie pomija czegoX istotnego.

Opcje tego moduXu:

nostrip

UniemoXliwia usuwanie spacji otaczajXcych wyodrebnione komunikaty.

wrap

Kanonizuje komunikaty do przetXumaczenia, przyjmujXc, Xe spacje nie sX waXnie i tylko sXuXX do zawijania przetXumaczonego dokumentu. Te opcje moXna nadpisaae opcjami dotyczXcymi wXasnych elementow. Patrz opis opcji ``tags'' poniXej.

caseinsensitive

Powoduje, Xe elementy i atrybuty sX wyszukiwane z pominieciem rozpoznawania wielkoXci liter. JeXli jest to zdefiniowane, to <BooK>laNG i <BOOK>Lang zostanX potraktowane tak samo jak <book>lang.

includeexternal

JeXeli zdefiniowano, zewnetrzne encje sX doXXczane do wygenerowanego (przetXumaczonego) dokumentu oraz do wyodrebnionych Xan~cuchow znakow. JeXeli nie zdefiniowano, bedzie trzeba przetXumaczyae zewnetrzne encje jako niezaleXne dokumenty.

ontagerror

Ta opcja okreXla zachowanie moduXu, kiedy napotka niepoprawny element kon~cowy (znaleziono element zamykany, ktory nie odpowiada elementowi ostatnio otwieranemu). MoXe przyjmowaae nastepujXce wartoXci:

fail

Jest to domyXlna wartoXae. DziaXanie moduXu zakon~czy sie bXedem.

warn

ModuX wyXwietli ostrzeXenie i bedzie kontynuowaX dziaXanie,

silent

ModuX bedzie kontynuowaX bez wypisywania Xadnych ostrzeXen~.

Prosze zachowaae ostroXnoXae, uXywajXc tej opcji. Rekomendowanym zachowaniem jest poprawienie pliku wejXciowego.

tagsonly

Wyodrebnia tylko elementy podane w opcji ``tags''. W przeciwnym wypadku wyodrebni wszystkie elementy poza podanymi w tej opcji.

doctype

Xan~cuch znakow, ktory bedziemy probowali dopasowaae do pierwszej linii typu dokumentu (doctype; jeXli zdefiniowany). JeXli nie pasuje, to dokument bedzie uwaXany za majXcy niepoprawny typ.

tags

Rozdzielona spacjami lista elementow, ktore majX byae przetXumaczone lub opuszczone. DomyXlnie podane elementy bede opuszczone, ale uXycie opcji ``tagsonly'' oznacza, Xe podane elementy zostanX wXXczone. Elementy muszX mieae postaae <aaa>, jednak moXna poXXczyae kilka z nich (<bbb><aaa>), aby okreXliae, Xe zawartoXae elementu <aaa> bedzie przetXumaczona tylko wtedy, gdy sam element jest zawarty w elemencie <bbb>.

MoXna podaae takXe kilka opcji elementow dodajXc pewne znaki na poczXtku hierarchii elementow. Na przykXad moXna dodaae ``w'' (zawijaj tekst) lub ``W'' (nie zawijaj), aby nadpisaae domyXlne zachowanie okreXlone przez globalnX opcje ``wrap''.

PrzykXad: W<chapter><title>

attributes

Rozdzielona spacjami lista atrybutow elementow, ktore naleXy tXumaczyae. MoXna podaae atrybuty, uXywajXc ich nazwy (na przykXad ``lang''), ale takXe moXna poprzedziae je hierarchiX elementow, aby powiedzieae, Xe ten atrybut bedzie tXumaczony tylko wtedy. gdy jest zawarty w okreXlonym elemencie. Na przykXad <bbb><aaa>lang mowi, Xe atrybut lang zostanie przetXumaczony, tylko jeXeli jest zawarty w elemencie <aaa>, ktory jest w elemencie <bbb>.

inline

Rozdzielona spacjami lista elementow, ktore powinny zostaae potraktowane jako inline. DomyXlnie wszystkie elementy przerywajX sekwencje. SkXadnia jest taka sama jak opcji tags.

nodefault

Rozdzielona spacjami lista elementow, ktorych moduX nie powinien probowaae domyXlnie umieszczaae w kategoriach ``tags'' lub ``inline''.

PRACA Z MODUXAMI POCHODNYMI

DEFINIOWANIE ELEMENTOW I ATRYBUTOW DO PRZETXUMACZENIA

NajprostszX zmianX jest zdefiniowanie elementow i atrybutow, ktore parser ma przetXumaczyae. Powinno byae to zrobione w funkcji initialize. Najpierw trzeba wywoXaae gXownX funkcje initialize, aby otrzymaae opcje linii polecen~, a nastepnie dodaae wXasne definicje do hasha opcji. Aby obsXuXyae nowe opcje w linii polecen~, trzeba je zdefiniowaae przed wywoXaniem gXownej funkcje initialize:

   $self->{options}{'new_option'}='';
   $self->SUPER::initialize(%options);
   $self->{options}{'tags'}.=' <p> <head><title>';
   $self->{options}{'attributes'}.=' <p>lang id';
   $self->{options}{'inline'}.=' <br>';
   $self->treat_options;
 
 

NADPISYWANIE FUNKCJI found_string

Innym prostym krokiem jest nadpisanie funkcji ``found_string'', ktora otrzymuje od parsera wyciXgniete komunikaty, aby je przetXumaczyae. Tutaj moXna kontrolowaae, ktore komunikaty tXumaczyae, oraz przeprowadziae transformacje na nich przed tXumaczeniem i po nim.

Otrzymuje wyodrebniony tekst, odnoXnik do miejsca jego znalezienia i hash zawierajXce dodatkowe informacje kontrolujXce, ktore komunikaty sX do przetXumaczenia, jak je przetXumaczyae i jak wygenerowaae komentarz.

ZawartoXae tych opcji zaleXy od rodzaju Xan~cucha znakow (podanego we rekordzie tego hasha):

type="tag"

Znaleziony Xan~cuch znakow jest zawartoXciX elementu, ktory moXna przetXumaczyae. Wpis ``tag_options'' zawiera znaki opcji wyciXgniete z poczXtku hierarchii elementow z opcji ``tags'' moduXu.

type="attribute"

Oznacza, Xe znaleziony tekst jest wartoXciX atrybutu moXliwego do tXumaczenia. Wpis ``attribute'' zawiera nazwe atrybutu.

Musi zwrociae tekst zastepujXcy w tXumaczonym dokumencie tekst oryginalny. Podstawowy przykXad tej 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 przykXad moXna znaleXae w nowym module Dia, ktory tylko filtruje niektore Xan~cuchy znakow.

MODYFIKOWANIE TYPOW ELEMENTOW (DO ZROBIENIA)

Jest to jeden z bardziej zXoXonych, ale pozwala na (prawie) caXkowite dostosowanie do wXasnych potrzeb. Jest oparty na liXcie hashow, z ktorych kaXdy okreXla sposob zachowania sie typu elementu. Lista powinna byae posortowana, tak Xe elementy bardziej ogolne wystepujX po bardziej szczegoXowych (posortowanych najpierw po kluczach poczXtkowych, a potem kon~cowych). Aby zdefiniowaae typ elementu, trzeba utworzyae hash zawierajXcy nastepujXce klucze:

beginning

OkreXla poczXtek elementu, po ``<''.

end

OkreXla koniec elementu, przed ``>''.

breaking

Mowi, Xe jest to klasa elementow rozdzielajXcych. Element nierozdzielajXcy (inline) jest to taki element, ktore moXe byae pobrany jako zawartoXae innego elementu. MoXe to przyjmowaae wartoXci false (0), true (1) lub undefinded. JeXli zostanie jako undefined, to trzeba bedzie zdefiniowaae funkcje f_breaking, mowiXcX, czy podany element tej klasy jest elementem rozdzielajXcym, czy teX nie.

f_breaking

Jest to funkcja, ktora powie, czy nastepny element jest elementem zamykajXcym, czy teX nie. Powinna byae zdefiniowana, jeXli nie zdefiniowano opcji ``breaking''.

f_extract

JeXli wartoXciX tego klucza pozostanie undefined, to ogolne funkcje wyodrebniajXce bedX musiaXy wyodrebniae ten element samodzielnie. Jest to uXyteczne dla elementow, ktore mogX zawieraae w sobie inne elementy lub specjalne struktury, tak Xeby gXowny parser nie oszalaX. Funkcja otrzymuje flage logicznX mowiXcX, czy element powinien zostaae usuniety z wejXciowego strumienia, czy teX nie.

f_translate

Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca przetXumaczony element (przetXumaczone atrybuty lub wszystkie potrzebne transformacje) jako pojedynczy Xan~cuch znakow.

FUNKCJE WEWNETRZNE, uXywane do pisania parserow

PRACA Z ELEMENTAMI

get_path()

Funkcja zwraca XcieXke bieXXcego elementu od korzenia dokumentu w formacie <html><body><p>.

tag_type()

Funkcja zwraca indeks z listy tag_types, ktory odpowiada nastepnemu elementowi ze strumienia wejXciowego, lub -1 gdy dotarXa do kon~ca pliku wejXciowego.

extract_tag($$)

Funkcja zwraca nastepny element ze strumienia wejXciowego bez poczXtku i kon~ca, w postaci tablicy i zarzXdza odnoXnikami do pliku wejXciowego. Przyjmuje dwa parametry: typ elementu (zwrocone przez tag_type) i wartoXae logicznX, okreXlajXcX, czy element powinien zostaae usuniety ze strumienia wejXciowego.

get_tag_name(@)

Funkcja zwraca nazwe nastepnego elementu przekazanego jako argument w formie tablicy zwracanej przez extract_tag.

breaking_tag()

Funkcja zwraca wartoXae logicznX, ktora mowi, czy nastepny element jest elementem rozdzielajXcym, czy nie (element inline). Nie zmienia strumienia wejXciowego.

treat_tag()

Funkcja tXumaczy nastepny element z XrodXowego strumienia, UXywa do tXumaczenia wXasnych funkcji kaXdego typu elementu.

tag_in_list($@)

Funkcja zwraca wartoXae bedXcX Xan~cuchem znakow, mowiXcX, czy jej pierwszy argument (hierarchia elementow) pasuje do ktoregokolwiek elementu jej drugiego argumentu (lista elementow lub hierarchii elementow). Zwraca 0, jeXli nie pasuje. W przeciwnym razie zwraca opcje dopasowanego elementy (znaki z poczXtku elementu) lub 1 (jeXli element nie miaX opcji).

PRACA Z ATRYBUTAMI

treat_attributes(@)

Funkcja obsXuguje tXumaczenia atrybutow elementow. Pobiera element bez znacznikow poczXtku/kon~ca, a nastepnie szuka atrybutow, tXumaczy te spoXrod nich, ktore sX przeznaczone do tXumaczenia (podane w opcji ``attributes'' moduXu). Zwraca prosty tekst z przetXumaczonym elementem.

PRACA Z OPCJAMI MODUXU

treat_options()

Funkcja wypeXnia wewnetrzne struktury zawierajXce elementy, atrybuty i wXXczane dane opcjami moduXu (podanymi w linii polecen~ lub w funkcji initialize).

POBIERANIE TEKSTU Z PLIKU WEJXCIOWEGO

get_string_until($%)

Funkcja zwraca tablice z liniami (i odnoXnikami) z wejXciowego dokumentu dopoki nie znajdzie pierwszego argumentu. Drugim argumentem jest hash opcji. WartoXae 0 oznacza wyXXczenie (domyXlnie), a 1 - wXXczenie.

Poprawne opcje:

include

Powoduje, Xe zwracana tablica zawiera szukany tekst.

remove

Usuwa zwrocony strumien~ z wejXcia

unquoted

Zapewnia, Xe szukany tekst nie jest umieszczony w cudzysXowach.

skip_spaces(\@)

Funkcja otrzymuje jako argument odnoXnik do akapitu (w formacie zwroconym przez get_string_until), pomija spacje nagXowka i zwraca prosty Xan~cuch znakow.

join_lines(@)

Funkcja zwraca prosty Xan~cuch znakow zawierajXcy tekst z tablicy argumentu (odrzucajXc odnoXniki).

STATUS MODUXU

Ten moduX umoXliwia tXumaczenie elementow i atrybutow.

Wsparcie dla encji i plikow wXXczanych jest na naszej liXcie rzeczy do zrobienia.

Pisanie moduXow pochodnych jest raczej ograniczone.

LISTA RZECZY DO ZROBIENIA

DOCTYPE (ENCJE)

Istnieje minimalna obsXuga tXumaczen~ encji. SX one tXumaczone jako caXoXae, a elementy nie sX brane pod uwage. Encje wieloliniowe nie sX wspierane, a podczas tXumaczenia tekst encji jest zawsze zawijany.

PLIKI WXXCZANE

MODYFIKOWANIE TYPOW ELEMENTOW ODZIEDZICZONYCH MODUXOW (przenieXae strukture tag_types do hasha $self?)

element dzielXcy w Xrodku elementu niedzielXcego (czy to jest moXliwe?) powoduje brzydkie komentarze.

ZOBACZ TAKXE

po4a(7), Locale::Po4a::TransTractor(3pm).

AUTORZY

  Jordi Vilalta <jvprat@gmail.com>
 
 

TXUMACZENIE

  Robert Luberda <robert@debian.org>
 
 

PRAWA AUTORSKIE I LICENCJA

Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>

Program jest wolnym oprogramowaniem; moXna go redystrybuowaae i/lub modyfikowaae zgodnie z warunkami licencji GPL (patrz plik COPYING).