Provided by: po4a_0.55-1_all bug

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

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

       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.

           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.

           Internally, the XML parser only cares about these four options: w W i p.

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

           You can verify actual internal parameter behavior by invoking po4a with --debug
           option.

           Przykład: W<chapter><title>

           Please note a tag should be listed in either translated or untranslated setting
           string.

       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.

WRITING DERIVATIVE MODULES

   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;

       You should use the _default_inline, _default_break, _default_placeholder,
       _default_translated, _default_untranslated, and _default_attributes options in derivative
       modules. This allow users to override the default behavior defined in your module with
       command line options.

   OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
       If you don't like the default behavior of this xml module and its derivative modules, you
       can provide command line options to change their behavior.

       See Locale::Po4a::Docbook(3pm),

   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)
       Jest to jeden z bardziej złożonych procesów, 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.

INTERNAL FUNCTIONS used to write derivative parsers

   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.

           Here, the tag has structure started by < and end by > and it can contain multiple
           lines.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

       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.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

       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.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

       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.

   WORKING WITH TAGGED CONTENTS
       treat_content()
           This function gets the text until the next breaking tag (not inline) from the input
           stream.  Translate it using each tag type's custom translation functions.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

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