Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Xml.3pm

NAZWA

Locale::Po4a::Xml - Konwersja dokumentów XML i pochodnych z/do plików PO

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.

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).