attributes Rozdzielona spacjami lista atrybutow elementow, ktore nalezy tlumaczyc. Mozna podac atrybuty, uzywajac ich nazwy (na przyklad "lang"), ale takze mozna poprzedzic je hierarchia elementow, aby powiedziec, ze ten atrybut bedzie tlumaczony tylko wtedy. gdy jest zawarty w okreslonym elemencie. Na przyklad <bbb><aaa>lang mowi, ze atrybut lang zostanie przetlumaczony, tylko jezeli jest zawarty w elemencie <aaa>, ktory jest w elemencie <bbb>. foldattributes Nie tlumaczy atrybutow elementow wlaczanych. Zamiast tego zastepuje wszystkie atrybuty elementu przez po4a-id=<id>. Jest to uzyteczne w przypadku atrybutow, ktore nie powinny byc tlumaczone - upraszcza komunikaty do tlumaczenia i zapobiega pomylkom tlumaczy. customtag Rozdzielona spacjami lista elementow, ktore nie powinny byc traktowane jako elementy.Tagi te sa traktowane jako wlaczane i nie musza byc zamykane. break Rozdzielona spacjami lista elementow, ktore powinny przerwac sekwencje. Domyslnie wszystkie elementy przerywaja sekwencje. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 elementow, ktore powinny zostac potraktowane jako wlaczane. Domyslnie wszystkie elementy przerywaja sekwencje. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie w innym elemencie (<bbb>). placeholder Rozdzielona spacjami lista elementow, ktore powinny zostac potraktowane jako wypelniacze miejsca (placeholder). Wypelniacze miejsca nie przerywaja sekwencji, jednak ich zawartosc jest tlumaczona osobno. Polozenie wypelniaczy miejsca w bloku bedzie oznaczone lancuchem znakow podobnym do: <placeholder type=\"footnote\" id=\"0\"/> Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 elementow, ktorych modul nie powinien probowac domyslnie umieszczac 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. Jesli opcja zostanie wlaczona, po4a bedzie przetwarzal dyrektywy preprocesora jako separatory akapitow. Jest to wazne, jesli plik XML jest przetwarzany przez preprocesor, poniewaz jesli nie uzyje sie tej opcji, a dyrektywy preprocesora trafia w srodek linii, to po4a przyjmie, za naleza do biezacego paragramu, co spowoduje, ze preprocesor ich juz nie rozpozna. Uwaga: dyrektywy preprocesora musza byc umieszczone miedzy elementami (nie moga rozdzielac elementu). translated Rozdzielona spacjami lista elementow do przetlumaczenia. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 byc przetlumaczone i mozna zmienic formatowanie zawartosci. W Elementy powinny byc tlumaczone, ale nie mozna zmieniac formatowania ich zawartosci. i Elementy powinny tlumaczone jako wlaczane. p Elementy powinny byc tlumaczone jako wypelniacze miejsca. Internally, the XML parser only cares about these four options: w W i p. * Tags listed in break are set to w or W depending on the wrap option. * Tags listed in inline are set to i. * Tags listed in placeholder are set to p. * Tags listed in untranslated are without any of these options set. You can verify actual internal parameter behavior by invoking po4a with --debug option. Przyklad: W<chapter><title> Please note a tag should be listed in either translated or untranslated setting string. untranslated Rozdzielona spacjami lista elementow, ktore nie maja byc tlumaczone. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 Domyslne kategorie tych elementow ktore nie sa tlumaczone (translated), nietlumaczone (untranslated), przerywaczami (break), wlaczane (inline), ani wypelniaczami miejsca (placeholder). This is a set of letters as defined in translated and this setting is only valid for translatable tags. PRACA Z MODULAMI POCHODNYMI DEFINIOWANIE ELEMENTOW I ATRYBUTOW DO PRZETLUMACZENIA Najprostsza zmiana jest zdefiniowanie elementow i atrybutow, ktore parser ma przetlumaczyc. Powinno byc to zrobione w funkcji initialize. Najpierw trzeba wywolac glowna funkcje initialize, aby otrzymac opcje linii polecen, a nastepnie dodac wlasne definicje do hasha opcji. Aby obsluzyc nowe opcje w linii polecen, trzeba je zdefiniowac przed wywolaniem glownej funkcji initialize: $self->{options}{'new_option'}=''; $self->SUPER::initialize(%options); $self->{options}{'_default_translated'}.=' <head><title>'; $self->{options}{'attributes'}.=' lang id'; $self->{options}{'_default_inline'}.=' '; $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. Patrz Locale::Po4a::Docbook(3pm), NADPISYWANIE FUNKCJI found_string Innym prostym krokiem jest nadpisanie funkcji "found_string", ktora otrzymuje od parsera wyciagniete komunikaty do przetlumaczenia. Tutaj mozna kontrolowac, ktore komunikaty tlumaczyc, oraz przeprowadzic na nich transformacje zarowno przed tlumaczeniem, jak i po nim. Otrzymuje wyodrebniony tekst, odnosnik do miejsca jego znalezienia i hash zawierajace dodatkowe informacje kontrolujace, ktore komunikaty sa do przetlumaczenia, jak je przetlumaczyc i jak wygenerowac komentarz. Zawartosc tych opcji zalezy od rodzaju lancucha znakow (podanego we rekordzie tego hasha): type="tag" Znaleziony lancuch znakow jest zawartoscia elementu, ktory mozna przetlumaczyc. Wpis "tag_options" zawiera znaki opcji wyciagniete z poczatku hierarchii elementow z opcji "tags" modulu. type="attribute" Oznacza, ze znaleziony tekst jest wartoscia atrybutu mozliwego do tlumaczenia. Wpis "attribute" zawiera nazwe atrybutu. Funkcja musi zwrocic tekst zastepujacy w tlumaczonym dokumencie tekst oryginalny. Podstawowy przyklad 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 przyklad mozna znalezc w nowym module Dia, ktory tylko filtruje niektore lancuchy znakow. MODYFIKOWANIE TYPOW ELEMENTOW (DO ZROBIENIA) Jest to jeden z bardziej zlozonych procesow, ale pozwala na (prawie) calkowite dostosowanie do wlasnych potrzeb. Jest oparty na liscie hashow, z ktorych kazdy okresla sposob zachowania sie typu elementu. Lista powinna byc posortowana, tak ze elementy bardziej ogolne wystepuja po bardziej szczegolowych (posortowanych najpierw po kluczach poczatkowych, a potem koncowych). Aby zdefiniowac typ elementu, trzeba utworzyc hash zawierajacy nastepujace klucze: beginning Okresla poczatek elementu, po "<". end Okresla koniec elementu, przed ">". breaking Mowi, ze jest to klasa elementow rozdzielajacych. Element nierozdzielajacy (inline) jest to taki element, ktore moze byc pobrany jako zawartosc innego elementu. Moze to przyjmowac wartosci false (0), true (1) lub undefinded. Jesli zostanie jako undefined, to trzeba bedzie zdefiniowac funkcje f_breaking, mowiaca, czy podany element tej klasy jest elementem rozdzielajacym, czy tez nie. f_breaking Jest to funkcja, ktora powie, czy nastepny element jest elementem zamykajacym, czy tez nie. Powinna byc zdefiniowana, jesli nie zdefiniowano opcji breaking. f_extract Jesli wartoscia tego klucza pozostanie undefined, to ogolne funkcje wyodrebniajace beda musialy wyodrebnic ten element samodzielnie. Jest to uzyteczne dla elementow, ktore moga zawierac w sobie inne elementy lub specjalne struktury, tak zeby glowny parser nie oszalal. Funkcja otrzymuje flage logiczna mowiaca, czy element powinien zostac usuniety z wejsciowego strumienia, czy tez nie. f_translate Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca przetlumaczony element (przetlumaczone atrybuty lub wszystkie potrzebne transformacje) jako pojedynczy lancuch znakow. FUNKCJE WEWNETRZNE, uzywane do pisania parserow PRACA Z ELEMENTAMI get_path() Funkcja zwraca sciezke biezacego elementu od korzenia dokumentu w formacie <html><body>. Jako argument mozna przekazac dodatkowa tablice elementow (bez nawiasow). Elementy te zostana dolaczone na koncu biezacej sciezki. tag_type() Funkcja zwraca indeks z listy tag_types, ktory odpowiada nastepnemu elementowi ze strumienia wejsciowego, lub -1 gdy dotarla do konca pliku wejsciowego. 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 nastepny element ze strumienia wejsciowego bez poczatku i konca, w postaci tablicy i zarzadza odnosnikami do pliku wejsciowego. Przyjmuje dwa parametry: typ elementu (zwrocone przez tag_type) i wartosc logiczna, okreslajaca, czy element powinien zostac usuniety ze strumienia wejsciowego. 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 nazwe nastepnego elementu przekazanego jako argument w formie tablicy zwracanej przez extract_tag. breaking_tag() Funkcja zwraca wartosc logiczna, ktora mowi, czy nastepny element jest elementem rozdzielajacym, czy nie (element inline). Nie zmienia strumienia wejsciowego. treat_tag() Funkcja tlumaczy nastepny element z zrodlowego strumienia, uzywajac do tego wlasnych funkcji kazdego 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 wartosc bedaca lancuchem znakow, mowiaca, czy jej pierwszy argument (hierarchia elementow) pasuje do ktoregokolwiek elementu jej drugiego argumentu (lista elementow lub hierarchii elementow). Zwraca 0, jesli nie pasuje. W przeciwnym razie zwraca opcje dopasowanego elementy (znaki z poczatku elementu) lub 1 (jesli element nie mial opcji). PRACA Z ATRYBUTAMI treat_attributes(@) This function handles the translation of the tags' attributes. It receives the tag without the beginning / end marks, and then it finds the attributes, and it translates the translatable ones (specified by the module option attributes). This returns a plain string with the translated tag. 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 MODULU treat_options() Funkcja wypelnia wewnetrzne struktury zawierajace elementy, atrybuty i dane wlaczane wraz z opcjami modulu (podanymi w linii polecen lub w funkcji initialize). POBIERANIE TEKSTU Z PLIKU WEJSCIOWEGO get_string_until($%) Funkcja zwraca tablice z liniami (i odnosnikami) z wejsciowego dokumentu dopoki nie znajdzie pierwszego argumentu. Drugim argumentem jest hash opcji. Wartosc 0 oznacza wylaczenie (domyslnie), a 1 - wlaczenie. Poprawne opcje: include Powoduje, ze zwracana tablica zawiera szukany tekst. remove Usuwa zwrocony strumien z wejscia unquoted Zapewnia, ze szukany tekst nie jest umieszczony w cudzyslowach. regex This denotes that the first argument is a regular expression rather than an plain string skip_spaces(\@) Funkcja otrzymuje jako argument odnosnik do akapitu (w formacie zwroconym przez get_string_until), pomija spacje naglowka i zwraca prosty lancuch znakow. join_lines(@) Funkcja zwraca prosty lancuch znakow zawierajacy tekst z tablicy argumentu (odrzucajac odnosniki). STATUS MODULU Ten modul umozliwia tlumaczenie elementow i atrybutow. LISTA RZECZY DO ZROBIENIA DOCTYPE (ENCJE) Istnieje minimalna obsluga tlumaczen encji. Sa one tlumaczone jako calosc, a elementy nie sa brane pod uwage. Encje wieloliniowe nie sa wspierane, a podczas tlumaczenia tekst encji jest zawsze zawijany. MODYFIKOWANIE TYPOW ELEMENTOW ODZIEDZICZONYCH MODULOW (przeniesc strukture tag_types do hasha $self?) ZOBACZ TAKZE Locale::Po4a::TransTractor(3pm), po4a(7) AUTORZY Jordi Vilalta <jvprat@gmail.com> Nicolas Francois <nicolas.francois@centraliens.net> TLUMACZENIE Robert Luberda <robert@debian.org> PRAWA AUTORSKIE I LICENCJA Copyright (C) 2004 Jordi Vilalta <jvprat@gmail.com> Copyright (C) 2008-2009 Nicolas Francois <nicolas.francois@centraliens.net> This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). perl v5.38.2 2024-06-26 LOCALE::PO4A::XML.3PM(1)

LOCALE::PO4A::XML.3PM(1) User Contributed Perl Documentation NAZWA Locale::Po4a::Xml - konwersja dokumentow XML i pochodnych z/do plikow PO OPIS Celem projektu po4a ("PO for anything") jest ulatwienie tlumaczen (oraz, co ciekawsze, zarzadzania tlumaczeniami) przy uzyciu narzedzi gettext w tych obszarach, gdzie nie byly uzywane, jak na przyklad w obszarze dokumentacji. Locale::Po4a::XML jest modulem ulatwiajacym tlumaczenie dokumentow XML do innych jezykow [uzywanych przez ludzi]. TLUMACZENIE Z POMOCA PO4A::XML Tego modulu mozna uzyc bezposrednio do obslugi ogolnych dokumentow w formacie XML. Wyciagnie on zawartosc wszystkich elementow, bez zadnych atrybutow, poniewaz to wlasnie w elementach jest zapisywany tekst w wiekszosci dokumentow opartych na XML-u. Istnieje kilka opcji (opisanych w nastepnej sekcji), ktore moga dostosowac zachowanie do Twoich wymagan. Jesli nie pasuje ono do formatu Twojego dokumentu, zachecamy do napisania wlasnego modulu dziedziczacego z tego, opisujacego szczegoly formatu. Szczegoly mozna znalezc w sekcji PRACA ZMODULAMI POCHODNYMI ponizej. OPCJE AKCEPTOWANE PRZEZ MODUL Globalna opcja debug powoduje, ze ten modul pokaze wylaczone komunikaty, aby moc sprawdzic, czy przypadkiem nie pomija czegos istotnego. Opcje tego modulu: nostrip Uniemozliwia usuwanie spacji otaczajacych wyodrebnione komunikaty. wrap Kanonizuje komunikaty do przetlumaczenia, przyjmujac, ze spacje nie sa waznie i tylko sluza do zawijania przetlumaczonego dokumentu. Te opcje mozna nadpisac opcjami dotyczacymi wlasnych elementow. Patrz opis opcji translated ponizej. unwrap_attributes Attributes are wrapped by default. This option disables wrapping. caseinsensitive Powoduje, ze elementy i atrybuty sa wyszukiwane z pominieciem rozpoznawania wielkosci liter. Jesli jest to zdefiniowane, to laNG i Lang zostana potraktowane tak samo jak lang. escapequotes Escape quotes in output strings. Necessary, for example, for creating string resources for use by Android build tools. Patrz takze: https://developer.android.com/guide/topics/resources/string-resource.html includeexternal Jezeli zdefiniowano, zewnetrzne encje sa dolaczane do wygenerowanego (przetlumaczonego) dokumentu oraz do wyodrebnionych lancuchow znakow. Jezeli nie zdefiniowano, bedzie trzeba przetlumaczyc zewnetrzne encje jako niezalezne 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: fail Jest to domyslna wartosc. Dzialanie modulu zakonczy sie bledem. warn Modul wyswietli ostrzezenie i bedzie kontynuowal dzialanie. silent Modul bedzie kontynuowal bez wypisywania zadnych ostrzezen. Prosze zachowac ostroznosc, uzywajac tej opcji. Rekomendowanym zachowaniem jest poprawienie pliku wejsciowego. tagsonly Uwaga: Opcja ta jest przestarzala. Extracts only the specified tags in the tags option. Otherwise, it will extract all the tags except the ones specified. doctype Lancuch znakow, ktory bedziemy probowali dopasowac do pierwszej linii typu dokumentu (doctype; jesli zdefiniowany). Jesli nie pasuje, to zostanie wypisane ostrzezenie, ze dokument moze miec niepoprawny typ. addlang Lancuch znakow oznaczajacy sciezke (np. )) znacznika, do ktorego powinien zostac dodany atrybut lang="..." . Jezyk jest zdefiniowany jako nazwa bazowa pliku PO z usunietym 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 przestarzala. Prosimy zamiast niej uzywac opcji translated i untranslated. Rozdzielona spacjami lista elementow, ktore maja byc przetlumaczone lub opuszczone. Domyslnie podane elementy bede opuszczone, ale uzycie opcji "tagsonly" oznacza, ze podane elementy beda jedynymi elementami wlaczonymi. Elementy musza miec postac , jednak mozna polaczyc kilka z nich (), aby okreslic, ze zawartosc elementu bedzie przetlumaczona tylko wtedy, gdy sam element jest zawarty w elemencie . You can also specify some tag options by putting some characters in front of the tag hierarchy. For example, you can put w (wrap) or W (don't wrap) to override the default behavior specified by the global wrap option. Przyklad: W attributes Rozdzielona spacjami lista atrybutow elementow, ktore nalezy tlumaczyc. Mozna podac atrybuty, uzywajac ich nazwy (na przyklad "lang"), ale takze mozna poprzedzic je hierarchia elementow, aby powiedziec, ze ten atrybut bedzie tlumaczony tylko wtedy. gdy jest zawarty w okreslonym elemencie. Na przyklad <bbb><aaa>lang mowi, ze atrybut lang zostanie przetlumaczony, tylko jezeli jest zawarty w elemencie <aaa>, ktory jest w elemencie <bbb>. foldattributes Nie tlumaczy atrybutow elementow wlaczanych. Zamiast tego zastepuje wszystkie atrybuty elementu przez po4a-id=<id>. Jest to uzyteczne w przypadku atrybutow, ktore nie powinny byc tlumaczone - upraszcza komunikaty do tlumaczenia i zapobiega pomylkom tlumaczy. customtag Rozdzielona spacjami lista elementow, ktore nie powinny byc traktowane jako elementy.Tagi te sa traktowane jako wlaczane i nie musza byc zamykane. break Rozdzielona spacjami lista elementow, ktore powinny przerwac sekwencje. Domyslnie wszystkie elementy przerywaja sekwencje. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 elementow, ktore powinny zostac potraktowane jako wlaczane. Domyslnie wszystkie elementy przerywaja sekwencje. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie w innym elemencie (<bbb>). placeholder Rozdzielona spacjami lista elementow, ktore powinny zostac potraktowane jako wypelniacze miejsca (placeholder). Wypelniacze miejsca nie przerywaja sekwencji, jednak ich zawartosc jest tlumaczona osobno. Polozenie wypelniaczy miejsca w bloku bedzie oznaczone lancuchem znakow podobnym do: <placeholder type=\"footnote\" id=\"0\"/> Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 elementow, ktorych modul nie powinien probowac domyslnie umieszczac 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. Jesli opcja zostanie wlaczona, po4a bedzie przetwarzal dyrektywy preprocesora jako separatory akapitow. Jest to wazne, jesli plik XML jest przetwarzany przez preprocesor, poniewaz jesli nie uzyje sie tej opcji, a dyrektywy preprocesora trafia w srodek linii, to po4a przyjmie, za naleza do biezacego paragramu, co spowoduje, ze preprocesor ich juz nie rozpozna. Uwaga: dyrektywy preprocesora musza byc umieszczone miedzy elementami (nie moga rozdzielac elementu). translated Rozdzielona spacjami lista elementow do przetlumaczenia. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 byc przetlumaczone i mozna zmienic formatowanie zawartosci. W Elementy powinny byc tlumaczone, ale nie mozna zmieniac formatowania ich zawartosci. i Elementy powinny tlumaczone jako wlaczane. p Elementy powinny byc tlumaczone jako wypelniacze miejsca. Internally, the XML parser only cares about these four options: w W i p. * Tags listed in break are set to w or W depending on the wrap option. * Tags listed in inline are set to i. * Tags listed in placeholder are set to p. * Tags listed in untranslated are without any of these options set. You can verify actual internal parameter behavior by invoking po4a with --debug option. Przyklad: W<chapter><title> Please note a tag should be listed in either translated or untranslated setting string. untranslated Rozdzielona spacjami lista elementow, ktore nie maja byc tlumaczone. Elementu musza byc w postaci <aaa>, mozna je jednak polaczyc (<bbb><aaa>), jezeli dany element (<aaa>) powinien byc rozpatrywany tylko wtedy, gdy znajduje sie 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 Domyslne kategorie tych elementow ktore nie sa tlumaczone (translated), nietlumaczone (untranslated), przerywaczami (break), wlaczane (inline), ani wypelniaczami miejsca (placeholder). This is a set of letters as defined in translated and this setting is only valid for translatable tags. PRACA Z MODULAMI POCHODNYMI DEFINIOWANIE ELEMENTOW I ATRYBUTOW DO PRZETLUMACZENIA Najprostsza zmiana jest zdefiniowanie elementow i atrybutow, ktore parser ma przetlumaczyc. Powinno byc to zrobione w funkcji initialize. Najpierw trzeba wywolac glowna funkcje initialize, aby otrzymac opcje linii polecen, a nastepnie dodac wlasne definicje do hasha opcji. Aby obsluzyc nowe opcje w linii polecen, trzeba je zdefiniowac przed wywolaniem glownej funkcji initialize: $self->{options}{'new_option'}=''; $self->SUPER::initialize(%options); $self->{options}{'_default_translated'}.=' <head><title>'; $self->{options}{'attributes'}.=' lang id'; $self->{options}{'_default_inline'}.=' '; $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. Patrz Locale::Po4a::Docbook(3pm), NADPISYWANIE FUNKCJI found_string Innym prostym krokiem jest nadpisanie funkcji "found_string", ktora otrzymuje od parsera wyciagniete komunikaty do przetlumaczenia. Tutaj mozna kontrolowac, ktore komunikaty tlumaczyc, oraz przeprowadzic na nich transformacje zarowno przed tlumaczeniem, jak i po nim. Otrzymuje wyodrebniony tekst, odnosnik do miejsca jego znalezienia i hash zawierajace dodatkowe informacje kontrolujace, ktore komunikaty sa do przetlumaczenia, jak je przetlumaczyc i jak wygenerowac komentarz. Zawartosc tych opcji zalezy od rodzaju lancucha znakow (podanego we rekordzie tego hasha): type="tag" Znaleziony lancuch znakow jest zawartoscia elementu, ktory mozna przetlumaczyc. Wpis "tag_options" zawiera znaki opcji wyciagniete z poczatku hierarchii elementow z opcji "tags" modulu. type="attribute" Oznacza, ze znaleziony tekst jest wartoscia atrybutu mozliwego do tlumaczenia. Wpis "attribute" zawiera nazwe atrybutu. Funkcja musi zwrocic tekst zastepujacy w tlumaczonym dokumencie tekst oryginalny. Podstawowy przyklad 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 przyklad mozna znalezc w nowym module Dia, ktory tylko filtruje niektore lancuchy znakow. MODYFIKOWANIE TYPOW ELEMENTOW (DO ZROBIENIA) Jest to jeden z bardziej zlozonych procesow, ale pozwala na (prawie) calkowite dostosowanie do wlasnych potrzeb. Jest oparty na liscie hashow, z ktorych kazdy okresla sposob zachowania sie typu elementu. Lista powinna byc posortowana, tak ze elementy bardziej ogolne wystepuja po bardziej szczegolowych (posortowanych najpierw po kluczach poczatkowych, a potem koncowych). Aby zdefiniowac typ elementu, trzeba utworzyc hash zawierajacy nastepujace klucze: beginning Okresla poczatek elementu, po "<". end Okresla koniec elementu, przed ">". breaking Mowi, ze jest to klasa elementow rozdzielajacych. Element nierozdzielajacy (inline) jest to taki element, ktore moze byc pobrany jako zawartosc innego elementu. Moze to przyjmowac wartosci false (0), true (1) lub undefinded. Jesli zostanie jako undefined, to trzeba bedzie zdefiniowac funkcje f_breaking, mowiaca, czy podany element tej klasy jest elementem rozdzielajacym, czy tez nie. f_breaking Jest to funkcja, ktora powie, czy nastepny element jest elementem zamykajacym, czy tez nie. Powinna byc zdefiniowana, jesli nie zdefiniowano opcji breaking. f_extract Jesli wartoscia tego klucza pozostanie undefined, to ogolne funkcje wyodrebniajace beda musialy wyodrebnic ten element samodzielnie. Jest to uzyteczne dla elementow, ktore moga zawierac w sobie inne elementy lub specjalne struktury, tak zeby glowny parser nie oszalal. Funkcja otrzymuje flage logiczna mowiaca, czy element powinien zostac usuniety z wejsciowego strumienia, czy tez nie. f_translate Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca przetlumaczony element (przetlumaczone atrybuty lub wszystkie potrzebne transformacje) jako pojedynczy lancuch znakow. FUNKCJE WEWNETRZNE, uzywane do pisania parserow PRACA Z ELEMENTAMI get_path() Funkcja zwraca sciezke biezacego elementu od korzenia dokumentu w formacie <html><body>. Jako argument mozna przekazac dodatkowa tablice elementow (bez nawiasow). Elementy te zostana dolaczone na koncu biezacej sciezki. tag_type() Funkcja zwraca indeks z listy tag_types, ktory odpowiada nastepnemu elementowi ze strumienia wejsciowego, lub -1 gdy dotarla do konca pliku wejsciowego. 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 nastepny element ze strumienia wejsciowego bez poczatku i konca, w postaci tablicy i zarzadza odnosnikami do pliku wejsciowego. Przyjmuje dwa parametry: typ elementu (zwrocone przez tag_type) i wartosc logiczna, okreslajaca, czy element powinien zostac usuniety ze strumienia wejsciowego. 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 nazwe nastepnego elementu przekazanego jako argument w formie tablicy zwracanej przez extract_tag. breaking_tag() Funkcja zwraca wartosc logiczna, ktora mowi, czy nastepny element jest elementem rozdzielajacym, czy nie (element inline). Nie zmienia strumienia wejsciowego. treat_tag() Funkcja tlumaczy nastepny element z zrodlowego strumienia, uzywajac do tego wlasnych funkcji kazdego 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 wartosc bedaca lancuchem znakow, mowiaca, czy jej pierwszy argument (hierarchia elementow) pasuje do ktoregokolwiek elementu jej drugiego argumentu (lista elementow lub hierarchii elementow). Zwraca 0, jesli nie pasuje. W przeciwnym razie zwraca opcje dopasowanego elementy (znaki z poczatku elementu) lub 1 (jesli element nie mial opcji). PRACA Z ATRYBUTAMI treat_attributes(@) This function handles the translation of the tags' attributes. It receives the tag without the beginning / end marks, and then it finds the attributes, and it translates the translatable ones (specified by the module option attributes). This returns a plain string with the translated tag. 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 MODULU treat_options() Funkcja wypelnia wewnetrzne struktury zawierajace elementy, atrybuty i dane wlaczane wraz z opcjami modulu (podanymi w linii polecen lub w funkcji initialize). POBIERANIE TEKSTU Z PLIKU WEJSCIOWEGO get_string_until($%) Funkcja zwraca tablice z liniami (i odnosnikami) z wejsciowego dokumentu dopoki nie znajdzie pierwszego argumentu. Drugim argumentem jest hash opcji. Wartosc 0 oznacza wylaczenie (domyslnie), a 1 - wlaczenie. Poprawne opcje: include Powoduje, ze zwracana tablica zawiera szukany tekst. remove Usuwa zwrocony strumien z wejscia unquoted Zapewnia, ze szukany tekst nie jest umieszczony w cudzyslowach. regex This denotes that the first argument is a regular expression rather than an plain string skip_spaces(\@) Funkcja otrzymuje jako argument odnosnik do akapitu (w formacie zwroconym przez get_string_until), pomija spacje naglowka i zwraca prosty lancuch znakow. join_lines(@) Funkcja zwraca prosty lancuch znakow zawierajacy tekst z tablicy argumentu (odrzucajac odnosniki). STATUS MODULU Ten modul umozliwia tlumaczenie elementow i atrybutow. LISTA RZECZY DO ZROBIENIA DOCTYPE (ENCJE) Istnieje minimalna obsluga tlumaczen encji. Sa one tlumaczone jako calosc, a elementy nie sa brane pod uwage. Encje wieloliniowe nie sa wspierane, a podczas tlumaczenia tekst encji jest zawsze zawijany. MODYFIKOWANIE TYPOW ELEMENTOW ODZIEDZICZONYCH MODULOW (przeniesc strukture tag_types do hasha $self?) ZOBACZ TAKZE Locale::Po4a::TransTractor(3pm), po4a(7) AUTORZY Jordi Vilalta <jvprat@gmail.com> Nicolas Francois <nicolas.francois@centraliens.net> TLUMACZENIE Robert Luberda <robert@debian.org> PRAWA AUTORSKIE I LICENCJA Copyright (C) 2004 Jordi Vilalta <jvprat@gmail.com> Copyright (C) 2008-2009 Nicolas Francois <nicolas.francois@centraliens.net> This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). perl v5.38.2 2024-06-26 LOCALE::PO4A::XML.3PM(1)