Provided by: po4a_0.52-1_all 
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 PRACA ZMODUŁAMI POCHODNYMI
poniżej.
OPCJE AKCEPTOWANE PRZEZ 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
Canonicalizes the string to translate, considering that whitespaces are not important, and wraps the
translated document. This option can be overridden by custom tag options. See the "tags" option
below.
unwrap_attributes
Attributes are wrapped by default. This option disables wrapping.
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.
escapequotes
Escape quotes in output strings. Necessary, for example, for creating string resources for use by
Android build tools.
See also: https://developer.android.com/guide/topics/resources/string-resource.html
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
This option defines the behavior of the module when it encounters invalid XML syntax (a closing tag
which does not match the last opening tag, or a tag's attribute without value). It can take the
following values:
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 zostanie wypisane ostrzeżenie, że dokument może mieć niepoprawny
typ.
addlang
Łańcuch znaków oznaczający ścieżkę (np. <bbb><aaa>)) znacznika, do którego powinien zostać dodany
atrybut lang="..." . Język jest zdefiniowany jako nazwa bazowa pliku PO z usuniętym rozszerzeniem
.po.
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 będą jedynymi
elementami włączonymi. 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>
Uwaga: Opcja ta jest przestarzała. Prosimy zamiast niej używać opcji translated i untranslated.
attributes
Space-separated list of tag's attributes you want to translate. You can specify the attributes by
their name (for example, "lang"), but you can prefix it with a tag hierarchy, to specify that this
attribute will only be translated when it's in the specified tag. For example: <bbb><aaa>lang
specifies that the lang attribute will only be translated if it's in an <aaa> tag, and it's in a
<bbb> tag.
foldattributes
Nie tłumaczy atrybutów elementów włączanych. Zamiast tego zastępuje wszystkie atrybuty elementu przez
po4a-id=<id>.
Jest to użyteczne w przypadku atrybutów, które nie powinny być tłumaczone - upraszcza komunikaty do
tłumaczenia i zapobiega pomyłkom tłumaczy.
customtag
Rozdzielona spacjami lista elementów, które nie powinny być traktowane jako elementy.Tagi te są
traktowane jako włączane i nie muszą być zamykane.
break
Rozdzielona spacjami lista elementów, które powinny przerwać sekwencję. Domyślnie wszystkie elementy
przerywają sekwencję.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
inline
Rozdzielona spacjami lista elementów, które powinny zostać potraktowane jako włączane. Domyślnie
wszystkie elementy przerywają sekwencję.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
placeholder
Rozdzielona spacjami lista elementów, które powinny zostać potraktowane jako wypełniacze miejsca
(placeholder). Wypełniacze miejsca nie przerywają sekwencji, jednak ich zawartość jest tłumaczona
osobno.
Położenie wypełniaczy miejsca w bloku będzie oznaczone łańcuchem znaków podobnym do:
<placeholder type=\"footnote\" id=\"0\"/>
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
nodefault
Rozdzielona spacjami lista elementów, których moduł nie powinien próbować domyślnie umieszczać
jakiejkolwiek kategorii.
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 przetwarzany przez
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
Rozdzielona spacjami lista elementów do przetłumaczenia.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<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>
untranslated
Rozdzielona spacjami lista elementów, które nie mają być tłumaczone.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
defaulttranslateoption
Domyślne kategorie tych elementów które nie są tłumaczone (translated), nietłumaczone (untranslated),
przerywaczami (break), włączane (inline), ani wypełniaczami miejsca (placeholder).
Jest to zbiór liter:
w Elementy powinny być przetłumaczone i można zmienić formatowanie zawartości.
W Elementy powinny być tłumaczone, ale nie można zmieniać formatowania ich zawartości.
i Elementy powinny tłumaczone jako włączane.
p Elementy powinny być tłumaczone jako wypełniacze miejsca.
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 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 modułach pochodnych należy używać opcji _default_inline, _default_break, _default_placeholder,
_default_translated, _default_untranslated oraz _default_attributes. Pozwala to użytkownikom zmienić
domyślne zachowanie za pomocą opcji linii poleceń.
NADPISYWANIE FUNKCJI found_string
Innym prostym krokiem jest nadpisanie funkcji "found_string", która otrzymuje od parsera wyciągnięte
komunikaty do przetłumaczenia. Tutaj można kontrolować, które komunikaty tłumaczyć, oraz przeprowadzić na
nich transformacje zarówno przed tłumaczeniem, jak 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.
Funkcja musi zwrócić tekst zastępujący w tłumaczonym dokumencie tekst oryginalny. Podstawowy przykład
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 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)
This is a more complex one, but it enables a (almost) total customization. It's based on a list of
hashes, each one defining a tag type's behavior. The list should be sorted so that the most general tags
are after the most concrete ones (sorted first by the beginning and then by the end keys). To define a
tag type you'll have to make a hash with the following keys:
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>.
Jako argument można przekazać dodatkową tablicę elementów (bez nawiasów). Elementy te zostaną
dołączone na końcu bieżącej ścieżki.
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żywając do tego 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 dane włączane wraz z 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.
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.
MODYFIKOWANIE TYPÓW ELEMENTÓW ODZIEDZICZONYCH MODUŁÓW (przenieść strukturę tag_types do hasha $self?)
ZOBACZ TAKŻE
Locale::Po4a::TransTractor(3pm), po4a(7)
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-2009 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).
Narzędzia po4a 2017-08-26 Locale::Po4a::Xml(3pm)