po4av0.73

LOCALE::PO4A::XML.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents
 

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

Extracts only the specified tags in the tags option. Otherwise, it will extract all the tags except the ones specified.

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

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.

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.

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

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.

 

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;

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

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.

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(@)
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 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.
regex
This denotes that the first argument is a regular expression rather than an plain string
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>

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

 

Index

NAZWA
OPIS
TŁUMACZENIE Z POMOCĄ PO4A::XML
OPCJE AKCEPTOWANE PRZEZ MODUŁ
PRACA Z MODUŁAMI POCHODNYMI
DEFINIOWANIE ELEMENTÓW I ATRYBUTÓW DO PRZETŁUMACZENIA
OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
NADPISYWANIE FUNKCJI found_string
MODYFIKOWANIE TYPÓW ELEMENTÓW (DO ZROBIENIA)
FUNKCJE WEWNĘTRZNE, używane do pisania parserów
PRACA Z ELEMENTAMI
PRACA Z ATRYBUTAMI
WORKING WITH TAGGED CONTENTS
PRACA Z OPCJAMI MODUŁU
POBIERANIE TEKSTU Z PLIKU WEJŚCIOWEGO
STATUS MODUŁU
LISTA RZECZY DO ZROBIENIA
ZOBACZ TAKŻE
AUTORZY
TŁUMACZENIE
PRAWA AUTORSKIE I LICENCJA
This document was created by using the manual pages.
Time: 20:30:49 GMT, June 17, 2024
català Deutsch English Esperanto español français hrvatski Magyar Italiano 日本語 Bokmål Nederlands polski Português Português (Brasil) Русский српски језик српски језик український 简体中文 简体中文 (how to set the default document language)