Rechercher une page de manuel
Locale::Po4a::Xml.3pm
Langue: pl
Version: 2010-06-01 (fedora - 01/12/10)
Section: 3 (Bibliothèques de fonctions)
Sommaire
NAZWA
Locale::Po4a::Xml - Konwersja dokumentów XML i pochodnych z/do plików POOPIS
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.Locale::Po4a::XML jest moduÅem uÅatwiajÄ cym tÅumaczenie dokumentów XML do innych jÄzyków [używanych przez ludzi].
TÅUMACZENIE Z POMOCÄ PO4A::XML
Tego moduÅu można użyÄ bezpoÅrednio do obsÅugi ogólnych dokumentów w formacie XML. WyciÄ gnie on zawartoÅÄ wszystkich elementów, bez żadnych atrybutów, ponieważ to wÅaÅnie w elementach jest zapisywany tekst w wiÄkszoÅci dokumentów opartych na XML-u.Istnieje kilka opcji (opisanych w nastÄpnej sekcji), które mogÄ dostosowaÄ zachowanie do Twoich wymagaÅ. JeÅli nie pasuje ono do formatu Twojego dokumentu, zachÄcamy do napisania wÅasnego moduÅu dziedziczÄ cego z tego, opisujÄ cego szczegóÅy formatu. SzczegóÅy można znaleÅºÄ w sekcji ``Pisanie moduÅów pochodnych'' poniżej.
OPCJE AKCEPTOWANE PRZEZ TEN MODUÅ
Globalna opcja debug powoduje, że ten moduÅ pokaże wyÅÄ czone komunikaty, aby móc sprawdziÄ, czy przypadkiem nie pomija czegoÅ istotnego.Opcje tego moduÅu:
- nostrip
- Uniemożliwia usuwanie spacji otaczajÄ cych wyodrÄbnione komunikaty.
- wrap
- Kanonizuje komunikaty do przetÅumaczenia, przyjmujÄ c, że spacje nie sÄ ważnie i tylko sÅuÅ¼Ä do zawijania przetÅumaczonego dokumentu. TÄ opcjÄ można nadpisaÄ opcjami dotyczÄ cymi wÅasnych elementów. Patrz opis opcji ``tags'' poniżej.
- caseinsensitive
- Powoduje, że elementy i atrybuty sÄ wyszukiwane z pominiÄciem rozpoznawania wielkoÅci liter. JeÅli jest to zdefiniowane, to <BooK>laNG i <BOOK>Lang zostanÄ potraktowane tak samo jak <book>lang.
- includeexternal
- Jeżeli zdefiniowano, zewnÄtrzne encje sÄ doÅÄ czane do wygenerowanego (przetÅumaczonego) dokumentu oraz do wyodrÄbnionych ÅaÅcuchów znaków. Jeżeli nie zdefiniowano, bÄdzie trzeba przetÅumaczyÄ zewnÄtrzne encje jako niezależne dokumenty.
- ontagerror
- Ta opcja okreÅla zachowanie moduÅu, kiedy wykryje bÅÄ
d skÅadni XML (element zamykany, który nie odpowiada elementowi ostatnio otwieranemu lub brak jest wartoÅci atrybutu elementu). Może przyjmowaÄ nastÄpujÄ
ce wartoÅci:
-
- fail
- Jest to domyÅlna wartoÅÄ. DziaÅanie moduÅu zakoÅczy siÄ bÅÄdem.
- warn
- ModuÅ wyÅwietli ostrzeżenie i bÄdzie kontynuowaÅ dziaÅanie,
- silent
- ModuÅ bÄdzie kontynuowaÅ bez wypisywania żadnych ostrzeżeÅ.
ProszÄ zachowaÄ ostrożnoÅÄ, używajÄ c tej opcji. Rekomendowanym zachowaniem jest poprawienie pliku wejÅciowego.
-
- tagsonly
- WyodrÄbnia tylko elementy podane w opcji ``tags''. W przeciwnym wypadku wyodrÄbni wszystkie elementy poza podanymi w tej opcji.
Uwaga: Opcja ta jest przestarzaÅa.
- doctype
- ÅaÅcuch znaków, który bÄdziemy próbowali dopasowaÄ do pierwszej linii typu dokumentu (doctype; jeÅli zdefiniowany). JeÅli nie pasuje, to dokument bÄdzie uważany za majÄ cy niepoprawny typ.
- tags
- Rozdzielona spacjami lista elementów, które majÄ
byÄ przetÅumaczone lub opuszczone. DomyÅlnie podane elementy bÄdÄ opuszczone, ale użycie opcji ``tagsonly'' oznacza, że podane elementy zostanÄ
wÅÄ
czone. Elementy muszÄ
mieÄ postaÄ <aaa>, jednak można poÅÄ
czyÄ kilka z nich (<bbb><aaa>), aby okreÅliÄ, że zawartoÅÄ elementu <aaa> bÄdzie przetÅumaczona tylko wtedy, gdy sam element jest zawarty w elemencie <bbb>.
Można podaÄ także kilka opcji elementów dodajÄ c pewne znaki na poczÄ tku hierarchii elementów. Na przykÅad można dodaÄ ``w'' (zawijaj tekst) lub ``W'' (nie zawijaj), aby nadpisaÄ domyÅlne zachowanie okreÅlone przez globalnÄ opcjÄ ``wrap''.
PrzykÅad: W<chapter><title>
Note: This option is deprecated. You should use the translated and untranslated options instead.
- attributes
- Rozdzielona spacjami lista atrybutów elementów, które należy tÅumaczyÄ. Można podaÄ atrybuty, używajÄ c ich nazwy (na przykÅad ``lang''), ale także można poprzedziÄ je hierarchiÄ elementów, aby powiedzieÄ, że ten atrybut bÄdzie tÅumaczony tylko wtedy. gdy jest zawarty w okreÅlonym elemencie. Na przykÅad <bbb><aaa>lang mówi, że atrybut lang zostanie przetÅumaczony, tylko jeżeli jest zawarty w elemencie <aaa>, który jest w elemencie <bbb>.
- inline
- Rozdzielona spacjami lista elementów, które powinny zostaÄ potraktowane jako inline. DomyÅlnie wszystkie elementy przerywajÄ sekwencjÄ. SkÅadnia jest taka sama jak opcji tags.
- nodefault
- Rozdzielona spacjami lista elementów, których moduÅ nie powinien próbowaÄ domyÅlnie umieszczaÄ w kategoriach ``tags'' lub ``inline''.
- cpp
- Wspiera dyrektywy preprocesora C. JeÅli opcja zostanie wÅÄ czona, po4a bÄdzie przetwarzaÅ dyrektywy preprocesora jako separatory akapitów. Jest to ważne, jeÅli plik XML jest przetwarzanyprzez preprocesor, ponieważ jeÅli nie użyje siÄ tej opcji, a dyrektywy preprocesora trafiÄ w Årodek linii, to po4a przyjmie, ża naleÅ¼Ä do bieÅ¼Ä cego paragramu, co spowoduje, że preprocesor ich już nie rozpozna. Uwaga: dyrektywy preprocesora muszÄ byÄ umieszczone miÄdzy elementami (nie mogÄ rozdzielaÄ elementu).
- translated
- Space-separated list of the tags you want to translate. The tags must be in the form <aaa>, but you can join some (<bbb><aaa>) to indicate that the content of the tag <aaa> will only be translated when it's into a <bbb> tag.
You can also specify some tag options putting some characters in front of the tag hierarchy. For example, you can put 'w' (wrap) or 'W' (don't wrap) to overide the default behavior specified by the global ``wrap'' option.
PrzykÅad: W<chapter><title>
- untranslated
- Space-separated list of the tags you do not want to translate or not. It uses the same format as the translated option.
PRACA Z MODUÅAMI POCHODNYMI
DEFINIOWANIE ELEMENTÃW I ATRYBUTÃW DO PRZETÅUMACZENIA
NajprostszÄ zmianÄ jest zdefiniowanie elementów i atrybutów, które parser ma przetÅumaczyÄ. Powinno byÄ to zrobione w funkcji initialize. Najpierw trzeba wywoÅaÄ gÅównÄ funkcjÄ initialize, aby otrzymaÄ opcje linii poleceÅ, a nastÄpnie dodaÄ wÅasne definicje do hasha opcji. Aby obsÅużyÄ nowe opcje w linii poleceÅ, trzeba je zdefiniowaÄ przed wywoÅaniem gÅównej 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'', która otrzymuje od parsera wyciÄ gniÄte komunikaty, aby je przetÅumaczyÄ. Tutaj można kontrolowaÄ, które komunikaty tÅumaczyÄ, oraz przeprowadziÄ transformacje na nich przed tÅumaczeniem i po nim.Otrzymuje wyodrÄbniony tekst, odnoÅnik do miejsca jego znalezienia i hash zawierajÄ ce dodatkowe informacje kontrolujÄ ce, które komunikaty sÄ do przetÅumaczenia, jak je przetÅumaczyÄ i jak wygenerowaÄ komentarz.
ZawartoÅÄ tych opcji zależy od rodzaju ÅaÅcucha znaków (podanego we rekordzie tego hasha):
- type=tag
- Znaleziony ÅaÅcuch znaków jest zawartoÅciÄ elementu, który można przetÅumaczyÄ. Wpis ``tag_options'' zawiera znaki opcji wyciÄ gniÄte z poczÄ tku hierarchii elementów z opcji ``tags'' moduÅu.
- type=attribute
- Oznacza, że znaleziony tekst jest wartoÅciÄ atrybutu możliwego do tÅumaczenia. Wpis ``attribute'' zawiera nazwÄ atrybutu.
Musi zwróciÄ tekst zastÄpujÄ cy w tÅumaczonym dokumencie tekst oryginalny. Podstawowy przykÅad 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 przykÅad można znaleÅºÄ w nowym module Dia, który tylko filtruje niektóre ÅaÅcuchy znaków.
MODYFIKOWANIE TYPÃW ELEMENTÃW (DO ZROBIENIA)
Jest to jeden z bardziej zÅożonych, ale pozwala na (prawie) caÅkowite dostosowanie do wÅasnych potrzeb. Jest oparty na liÅcie hashów, z których każdy okreÅla sposób zachowania siÄ typu elementu. Lista powinna byÄ posortowana, tak że elementy bardziej ogólne wystÄpujÄ po bardziej szczegóÅowych (posortowanych najpierw po kluczach poczÄ tkowych, a potem koÅcowych). Aby zdefiniowaÄ typ elementu, trzeba utworzyÄ hash zawierajÄ cy nastÄpujÄ ce klucze:- beginning
- OkreÅla poczÄ tek elementu, po ``<''.
- end
- OkreÅla koniec elementu, przed ``>''.
- breaking
- Mówi, że jest to klasa elementów rozdzielajÄ cych. Element nierozdzielajÄ cy (inline) jest to taki element, które może byÄ pobrany jako zawartoÅÄ innego elementu. Może to przyjmowaÄ wartoÅci false (0), true (1) lub undefinded. JeÅli zostanie jako undefined, to trzeba bÄdzie zdefiniowaÄ funkcje f_breaking, mówiÄ cÄ , czy podany element tej klasy jest elementem rozdzielajÄ cym, czy też nie.
- f_breaking
- Jest to funkcja, która powie, czy nastÄpny element jest elementem zamykajÄ cym, czy też nie. Powinna byÄ zdefiniowana, jeÅli nie zdefiniowano opcji ``breaking''.
- f_extract
- JeÅli wartoÅciÄ tego klucza pozostanie undefined, to ogólne funkcje wyodrÄbniajÄ ce bÄdÄ musiaÅy wyodrÄbniÄ ten element samodzielnie. Jest to użyteczne dla elementów, które mogÄ zawieraÄ w sobie inne elementy lub specjalne struktury, tak żeby gÅówny parser nie oszalaÅ. Funkcja otrzymuje flagÄ logicznÄ mówiÄ cÄ , czy element powinien zostaÄ usuniÄty z wejÅciowego strumienia, czy też nie.
- f_translate
- Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca przetÅumaczony element (przetÅumaczone atrybuty lub wszystkie potrzebne transformacje) jako pojedynczy ÅaÅcuch znaków.
FUNKCJE WEWNÄTRZNE, używane do pisania parserów
PRACA Z ELEMENTAMI
- get_path()
- Funkcja zwraca ÅcieżkÄ bieÅ¼Ä cego elementu od korzenia dokumentu w formacie <html><body><p>.
- tag_type()
- Funkcja zwraca indeks z listy tag_types, który odpowiada nastÄpnemu elementowi ze strumienia wejÅciowego, lub -1 gdy dotarÅa do koÅca pliku wejÅciowego.
- extract_tag($$)
- Funkcja zwraca nastÄpny element ze strumienia wejÅciowego bez poczÄ tku i koÅca, w postaci tablicy i zarzÄ dza odnoÅnikami do pliku wejÅciowego. Przyjmuje dwa parametry: typ elementu (zwrócone przez tag_type) i wartoÅÄ logicznÄ , okreÅlajÄ cÄ , czy element powinien zostaÄ usuniÄty ze strumienia wejÅciowego.
- get_tag_name(@)
- Funkcja zwraca nazwÄ nastÄpnego elementu przekazanego jako argument w formie tablicy zwracanej przez extract_tag.
- breaking_tag()
- Funkcja zwraca wartoÅÄ logicznÄ , która mówi, czy nastÄpny element jest elementem rozdzielajÄ cym, czy nie (element inline). Nie zmienia strumienia wejÅciowego.
- treat_tag()
- Funkcja tÅumaczy nastÄpny element z źródÅowego strumienia, Używa do tÅumaczenia wÅasnych funkcji każdego typu elementu.
- tag_in_list($@)
- Funkcja zwraca wartoÅÄ bÄdÄ cÄ ÅaÅcuchem znaków, mówiÄ cÄ , czy jej pierwszy argument (hierarchia elementów) pasuje do któregokolwiek elementu jej drugiego argumentu (lista elementów lub hierarchii elementów). Zwraca 0, jeÅli nie pasuje. W przeciwnym razie zwraca opcje dopasowanego elementy (znaki z poczÄ tku elementu) lub 1 (jeÅli element nie miaÅ opcji).
PRACA Z ATRYBUTAMI
- treat_attributes(@)
- Funkcja obsÅuguje tÅumaczenia atrybutów elementów. Pobiera element bez znaczników poczÄ tku/koÅca, a nastÄpnie szuka atrybutów, tÅumaczy te spoÅród nich, które sÄ przeznaczone do tÅumaczenia (podane w opcji ``attributes'' moduÅu). Zwraca prosty tekst z przetÅumaczonym elementem.
PRACA Z OPCJAMI MODUÅU
- treat_options()
- Funkcja wypeÅnia wewnÄtrzne struktury zawierajÄ ce elementy, atrybuty i wÅÄ czane dane opcjami moduÅu (podanymi w linii poleceÅ lub w funkcji initialize).
POBIERANIE TEKSTU Z PLIKU WEJÅCIOWEGO
- get_string_until($%)
- Funkcja zwraca tablicÄ z liniami (i odnoÅnikami) z wejÅciowego dokumentu dopóki nie znajdzie pierwszego argumentu. Drugim argumentem jest hash opcji. WartoÅÄ 0 oznacza wyÅÄ
czenie (domyÅlnie), a 1 - wÅÄ
czenie.
Poprawne opcje:
-
- include
- Powoduje, że zwracana tablica zawiera szukany tekst.
- remove
- Usuwa zwrócony strumieÅ z wejÅcia
- unquoted
- Zapewnia, że szukany tekst nie jest umieszczony w cudzysÅowach.
-
- skip_spaces(\@)
- Funkcja otrzymuje jako argument odnoÅnik do akapitu (w formacie zwróconym przez get_string_until), pomija spacje nagÅówka i zwraca prosty ÅaÅcuch znaków.
- join_lines(@)
- Funkcja zwraca prosty ÅaÅcuch znaków zawierajÄ cy tekst z tablicy argumentu (odrzucajÄ c odnoÅniki).
STATUS MODUÅU
Ten moduÅ umożliwia tÅumaczenie elementów i atrybutów.Wsparcie dla encji i plików wÅÄ czanych jest na naszej liÅcie rzeczy do zrobienia.
Pisanie moduÅów pochodnych jest raczej ograniczone.
LISTA RZECZY DO ZROBIENIA
DOCTYPE (ENCJE)Istnieje minimalna obsÅuga tÅumaczeÅ encji. SÄ one tÅumaczone jako caÅoÅÄ, a elementy nie sÄ brane pod uwagÄ. Encje wieloliniowe nie sÄ wspierane, a podczas tÅumaczenia tekst encji jest zawsze zawijany.
PLIKI WÅÄCZANE
MODYFIKOWANIE TYPÃW ELEMENTÃW ODZIEDZICZONYCH MODUÅÃW (przenieÅÄ strukturÄ tag_types do hasha $self?)
element dzielÄ cy w Årodku elementu niedzielÄ cego (czy to jest możliwe?) powoduje brzydkie komentarze.
ZOBACZ TAKŻE
po4a(7), Locale::Po4a::TransTractor(3pm).AUTORZY
Jordi Vilalta <jvprat@gmail.com> Nicolas François <nicolas.francois@centraliens.net>
TÅUMACZENIE
Robert Luberda <robert@debian.org>
PRAWA AUTORSKIE I LICENCJA
Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com> Copyright (c) 2008 by Nicolas François <nicolas.francois@centraliens.net>
Program jest wolnym oprogramowaniem; można go redystrybuowaÄ i/lub modyfikowaÄ zgodnie z warunkami licencji GPL (patrz plik COPYING).
Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre