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

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 translated poniżej.

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.

Patrz także: 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). It can take the following values:

tagsonly

Uwaga: Opcja ta jest przestarzała.

Wyodrębnia tylko elementy podane w opcji "tags". W przeciwnym wypadku wyodrębni wszystkie elementy poza podanymi w tej opcji.

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.

optionalclosingtag

Boolean indicating whether closing tags are optional (as in HTML). By default, missing closing tags raise an error handled according to "ontagerror".

tags

Uwaga: Opcja ta jest przestarzała. Prosimy zamiast niej używać opcji translated i untranslated.

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>

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

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

Elementu muszą być w postaci <aaa>, można je jednak połączyć (<bbb><aaa>), jeżeli dany element (<aaa>) powinien być rozpatrywany tylko wtedy, gdy znajduje się w innym elemencie (<bbb>).

Please note a tag should be listed in only one of the break, inline placeholder, or customtag setting string.

inline

Rozdzielona spacjami lista elementów, które powinny zostać potraktowane jako włączane. Domyślnie wszystkie elementy przerywają sekwencję.

Elementu muszą być w postaci <aaa>, można je jednak połączyć (<bbb><aaa>), jeżeli dany element (<aaa>) powinien być rozpatrywany tylko wtedy, gdy znajduje się w innym elemencie (<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\"/>
    

Elementu muszą być w postaci <aaa>, można je jednak połączyć (<bbb><aaa>), jeżeli dany element (<aaa>) powinien być rozpatrywany tylko wtedy, gdy znajduje się w innym elemencie (<bbb>).

break-pi

By default, Processing Instructions (i.e., "<? ... ?"> tags) are handled as inline tags. Pass this option if you want the PI to be handled as breaking tag. Note that unprocessed PHP tags are handled as Processing Instructions by the parser.

nodefault

Rozdzielona spacjami lista elementów, których moduł nie powinien próbować domyślnie umieszczać jakiejkolwiek kategorii.

If you have a tag which has its default setting by the subclass of this module but you want to set alternative setting, you need to list that tag as a part of the nodefault setting string.

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.

Elementu muszą być w postaci <aaa>, można je jednak połączyć (<bbb><aaa>), jeżeli dany element (<aaa>) powinien być rozpatrywany tylko wtedy, gdy znajduje się w innym elemencie (<bbb>).

You can also specify some tag options by putting some characters in front of the tag hierarchy. This overrides the default behavior specified by the global wrap and defaulttranslateoption option.

  * Tags listed in B<break> are set to I<w> or I<W> depending on the <wrap> option.
  * Tags listed in B<inline> are set to I<i>.
  * Tags listed in B<placeholder> are set to I<p>.
  * Tags listed in B<untranslated> are without any of these options set.

untranslated

Rozdzielona spacjami lista elementów, które nie mają być tłumaczone.

Elementu muszą być w postaci <aaa>, można je jednak połączyć (<bbb><aaa>), jeżeli dany element (<aaa>) powinien być rozpatrywany tylko wtedy, gdy znajduje się w innym elemencie (<bbb>).

Please note a translatable inline tag in an untranslated tag is treated as a translatable breaking tag, i setting is dropped and w or W is set depending on the <wrap> option.

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

This is a set of letters as defined in translated and this setting is only valid for translatable tags.

PRACA Z MODUŁAMI POCHODNYMI¶

  $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;

  sub found_string {
    my ($self,$text,$ref,$options)=@_;
    $text = $self->translate($text,$ref,"type ".$options->{'type'},
      'wrap'=>$self->{options}{'wrap'});
    return $text;
  }

FUNKCJE WEWNĘTRZNE, używane do pisania parserów¶

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 © 2004 Jordi Vilalta  <jvprat@gmail.com>
 Copyright © 2008-2009 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).