po4av0.55

Locale::Po4a::Xml

Section: Strumenti Po4a (3pm)
Updated: 2018-12-10
Index Return to Main Contents
 

NOME

Locale::Po4a::Xml - converte documenti XML e derivati da/verso file PO  

DESCRIZIONE

Lo scopo del progetto po4a (PO for anything - PO per tutto) è di facilitare la traduzione e, cosa ancor più interessante, la manutenzione delle traduzioni usando gettext e i relativi strumenti in campi in cui il loro uso non era programmato, come la documentazione.

Locale::Po4a::Xml è un modulo che aiuta la traduzione in altre lingue della documentazione in formato XML. Può anche essere usato come base per scrivere moduli per documenti basati su XML.  

TRADURRE CON PO4A::XML

This module can be used directly to handle generic XML documents. This will extract all tag's content, and no attributes, since it's where the text is written in most XML based documents.

Ci sono alcune opzioni (descritte nella sezione successiva) che possono personalizzare questo comportamento. Se questo non dovesse adattarsi sufficientemente al formato del proprio documento si incoraggia a scriverne uno per il proprio modulo derivandolo da questo, per descrivere i dettagli del proprio formato. Consultare la prossima sezione SCRIVERE MODULI DERIVATI più sotto, per la descrizione del processo.  

OPZIONI ACCETTATE DA QUESTO MODULO

The global debug option causes this module to show the excluded strings, in order to see if it skips something important.

Queste sono le opzioni speciali per questo modulo:

nostrip
Previene la rimozione degli spazi attorno alle stringhe estratte.
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
It makes the tags and attributes searching to work in a case insensitive way. If it's defined, it will treat <BooK>laNG and <BOOK>Lang as <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
When defined, external entities are included in the generated (translated) document, and for the extraction of strings. If it's not defined, you will have to translate external entities separately as independent documents.
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
This is the default value. The module will exit with an error.
warn
The module will continue, and will issue a warning.
silent
The module will continue without any warnings.

Be careful when using this option. It is generally recommended to fix the input file.

tagsonly
Note: This option is deprecated.

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

doctype
String that will try to match with the first line of the document's doctype (if defined). If it doesn't, a warning will indicate that the document might be of a bad type.
addlang
String indicating the path (e.g. <bbb><aaa>) of a tag where a lang=``...'' attribute shall be added. The language will be defined as the basename of the PO file without any .po extension.
tags
Note: This option is deprecated. You should use the translated and untranslated options instead.

Space-separated list of tags you want to translate or skip. By default, the specified tags will be excluded, but if you use the ``tagsonly'' option, the specified tags will be the only ones included. The tags must be in the form <aaa>, but you can join some (<bbb><aaa>) to say that the content of the tag <aaa> will only be translated when it's into a <bbb> tag.

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.

Example: W<chapter><title>

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
Do not translate attributes in inline tags. Instead, replace all attributes of a tag by po4a-id=<id>.

This is useful when attributes shall not be translated, as this simplifies the strings for translators, and avoids typos.

customtag
Space-separated list of tags which should not be treated as tags. These tags are treated as inline, and do not need to be closed.
break
Space-separated list of tags which should break the sequence. By default, all tags break the sequence.

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

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

inline
Space-separated list of tags which should be treated as inline. By default, all tags break the sequence.

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
Space-separated list of tags which should be treated as placeholders. Placeholders do not break the sequence, but the content of placeholders is translated separately.

The location of the placeholder in its block will be marked with a string similar to:

  <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
Space separated list of tags that the module should not try to set by default in any category.

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
Support C preprocessor directives. When this option is set, po4a will consider preprocessor directives as paragraph separators. This is important if the XML file must be preprocessed because otherwise the directives may be inserted in the middle of lines if po4a consider it belong to the current paragraph, and they won't be recognized by the preprocessor. Note: the preprocessor directives must only appear between tags (they must not break a tag).
tradotto
Elenco separato da spazi di marcatori che si intende tradurre.

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

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
Tags should be translated and content can be re-wrapped.
W
Tags should be translated and content should not be re-wrapped.
i
Tags should be translated inline.
p
Tags should be translated as placeholders.

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.

Example: W<chapter><title>

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

untranslated
Elenco separato da spazi di marcatori che non si intende tradurre.

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

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.

opzioneditraduzionepredefinita
The default categories for tags that are not in any of the translated, untranslated, break, inline, or placeholder.

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

 

SCRIVERE MODULI DERIVATI

 

DEFINIRE CHE MARCATORI E ATTRIBUTI TRADURRE

The simplest customization is to define which tags and attributes you want the parser to translate. This should be done in the initialize function. First you should call the main initialize, to get the command-line options, and then, append your custom definitions to the options hash. If you want to treat some new options from command line, you should define them before calling the main 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.

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

OVERRIDING THE found_string FUNCTION

Another simple step is to override the function ``found_string'', which receives the extracted strings from the parser, in order to translate them. There you can control which strings you want to translate, and perform transformations to them before or after the translation itself.

It receives the extracted text, the reference on where it was, and a hash that contains extra information to control what strings to translate, how to translate them and to generate the comment.

The content of these options depends on the kind of string it is (specified in an entry of this hash):

type="tag"
The found string is the content of a translatable tag. The entry ``tag_options'' contains the option characters in front of the tag hierarchy in the module ``tags'' option.
type="attributo"
Means that the found string is the value of a translatable attribute. The entry ``attribute'' has the name of the attribute.

It must return the text that will replace the original in the translated document. Here's a basic example of this function:

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

There's another simple example in the new Dia module, which only filters some strings.  

MODIFICA DEI TIPI DI TAG (DA FARE)

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
Specifica l'inizio del tag, dopo del ``<''.
end
Specifica la fine del tag, prima del ``>''.
breaking
It says if this is a breaking tag class. A non-breaking (inline) tag is one that can be taken as part of the content of another tag. It can take the values false (0), true (1) or undefined. If you leave this undefined, you'll have to define the f_breaking function that will say whether a concrete tag of this class is a breaking tag or not.
f_breaking
It's a function that will tell if the next tag is a breaking one or not. It should be defined if the breaking option is not.
f_extract
If you leave this key undefined, the generic extraction function will have to extract the tag itself. It's useful for tags that can have other tags or special structures in them, so that the main parser doesn't get mad. This function receives a boolean that says if the tag should be removed from the input stream or not.
f_translate
This function receives the tag (in the get_string_until() format) and returns the translated tag (translated attributes or all needed transformations) as a single string.
 

FUNZIONI INTERNE usate per scrivere parser derivati

 

LAVORARE CON I TAG

get_path()
This function returns the path to the current tag from the document's root, in the form <html><body><p>.

An additional array of tags (without brackets) can be passed as argument. These path elements are added to the end of the current path.

tag_type()
This function returns the index from the tag_types list that fits to the next tag in the input stream, or -1 if it's at the end of the input file.

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($$)
This function returns the next tag from the input stream without the beginning and end, in an array form, to maintain the references from the input file. It has two parameters: the type of the tag (as returned by tag_type) and a boolean, that indicates if it should be removed from the input stream.

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(@)
This function returns the name of the tag passed as an argument, in the array form returned by extract_tag.
breaking_tag()
This function returns a boolean that says if the next tag in the input stream is a breaking tag or not (inline tag). It leaves the input stream intact.
treat_tag()
This function translates the next tag from the input stream. 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($$)".

tag_in_list($@)
This function returns a string value that says if the first argument (a tag hierarchy) matches any of the tags from the second argument (a list of tags or tag hierarchies). If it doesn't match, it returns 0. Else, it returns the matched tag's options (the characters in front of the tag) or 1 (if that tag doesn't have options).
 

LAVORARE CON GLI ATTRIBUTI

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.
 

LAVORARE CON CONTENUTI MARCATI

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($$)".

 

LAVORARE CON LE OPZIONI DEL MODULO

treat_options()
This function fills the internal structures that contain the tags, attributes and inline data with the options of the module (specified in the command-line or in the initialize function).
 

RICAVARE IL TESTO DAL DOCUMENTO IN INGRESSO

get_string_until($%)
This function returns an array with the lines (and references) from the input document until it finds the first argument. The second argument is an options hash. Value 0 means disabled (the default) and 1, enabled.

Le opzioni valide sono:

include
Questo fa in modo che l'array restituito contenga il testo cercato
remove
Questo rimuove il flusso restituito dall'ingresso
unquoted
Questo si assicura che il testo cercato sia fuori da ogni virgolettatura
skip_spaces(\@)
This function receives as argument the reference to a paragraph (in the format returned by get_string_until), skips his heading spaces and returns them as a simple string.
join_lines(@)
Questa funzione restituisce una stringa semplice con il testo dall'array di argomenti (senza i riferimenti).
 

STATO DI QUESTO MODULO

Questo modulo può tradurre tag e attributi.  

TODO LIST

TIPO DI DOCUMENTO (ENTITÀ)

There is a minimal support for the translation of entities. They are translated as a whole, and tags are not taken into account. Multilines entities are not supported and entities are always rewrapped during the translation.

MODIFY TAG TYPES FROM INHERITED MODULES (move the tag_types structure inside the $self hash?)  

VEDERE ANCHE

Locale::Po4a::TransTractor(3pm), po4a(7)  

AUTORI

 Jordi Vilalta <jvprat@gmail.com>
 Nicolas François <nicolas.francois@centraliens.net>

 

TRADUZIONE

 Danilo Piazzalunga <danilopiazza@libero.it>
 Marco Ciampa <ciampix@libero.it>

 

COPYRIGHT E LICENZA

 Copyright © 2004 by Jordi Vilalta  <jvprat@gmail.com>
 Copyright © 2008-2009 by Nicolas François <nicolas.francois@centraliens.net>

Questo programma è software libero; è lecito ridistribuirlo o modificarlo secondo i termini della licenza GPL (vedere il file COPYING).


 

Index

NOME
DESCRIZIONE
TRADURRE CON PO4A::XML
OPZIONI ACCETTATE DA QUESTO MODULO
SCRIVERE MODULI DERIVATI
DEFINIRE CHE MARCATORI E ATTRIBUTI TRADURRE
OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
OVERRIDING THE found_string FUNCTION
MODIFICA DEI TIPI DI TAG (DA FARE)
FUNZIONI INTERNE usate per scrivere parser derivati
LAVORARE CON I TAG
LAVORARE CON GLI ATTRIBUTI
LAVORARE CON CONTENUTI MARCATI
LAVORARE CON LE OPZIONI DEL MODULO
RICAVARE IL TESTO DAL DOCUMENTO IN INGRESSO
STATO DI QUESTO MODULO
TODO LIST
VEDERE ANCHE
AUTORI
TRADUZIONE
COPYRIGHT E LICENZA

This document was created by using the manual pages.
Time: 11:07:06 GMT, December 10, 2018
català Deutsch English español français Italiano 日本語 Bokmål polski Português Português (Brasil) Русский український 简体中文 (how to set the default document language)