po4av0.70

Locale::Po4a::Xml

Section: Po4a Tools (3pm)
Updated: 2024-01-29
Index Return to Main Contents
 

NOM

Locale::Po4a::Xml - Converteix documents XML i derivats des de/a fitxers PO  

DESCRIPCIÓ

L'objectiu del projecte po4a (PO per a tot) és facilitar la traducció (i sobretot el manteniment de les traduccions) utilitzant les eines de gettext en àrees on no eren d'esperar, com ara en la documentació.

Locale::Po4a::XmL és un mòdul per ajudar en la traducció de documents XML a altres llenguatges [humans]. També es pot utilitzar com a base per construir mòduls per documents basats en XML.  

TRADUINT AMB PO4A::XML

Aquest mòdul es pot utilitzar directament per tractar documents XML genèrics. Aquest extraurà el contingut de tots els tags, i cap atribut, ja que aquí és on s'escriu el text en la majoria de documents basats en XML.

Hi ha algunes opcions (descrites a la propera secció) que permeten personalitzar aquest comportament. Si això no acaba d'encaixar amb el vostre format de document, us animo a escriure el vostre propi mòdul derivat d'aquest, per descriure els detalls del vostre format. Consulteu la secció ESCRIVINT MÒDULS DERIVATS més avall, per la descripció del procés.  

OPCIONS QUE ACCEPTA AQUEST MÒDUL

L'opció global de depuració fa que aquest mòdul mostri les cadenes excloses, per tal de comprovar si se salta quelcom important.

Aquestes són les opcions particulars d'aquest mòdul:

nostrip
Evita que es netegin els espais al voltant de les cadenes extretes.
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
Fa que la cerca de tags i atributs es faci independentment de majúscules i minúscules. Si està definit, tractarà els tags <BooK>laNG i <BOOK>Lang com <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). 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.
optionalclosingtag
Boolean indicating whether closing tags are optional (as in HTML). By default, missing closing tags raise an error handled according to ontagerror.
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.

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

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
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).
translated
Space-separated list of tags you want to translate.

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

Exemple: W<chapter><title>

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

untranslated
Space-separated list of tags you do not want to translate.

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.

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

 

WRITING DERIVATIVE MODULES

 

DEFINIR ELS TAGS I ATRIBUTS A TRADUIR

La personalització més simple tracta de definir quins tags i atributs voleu que l'analitzador tradueixi. Això s'ha de fer en la funció initialize. Primer haureu de cridar l'initialize principal, per tal d'obtenir les opcions de la línia de comandes, i després afegir les definicions personalitzades al hash d'opcions. Si voleu tractar algunes opcions noves de la línia de comandes, haureu de definir-les abans de cridar l'initialize principal: 

  $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),  

REESCRIVINT LA FUNCIÓ found_string

Una altra forma simple és sobreescriure la funció ``found_string'', que rep les cadenes que extreu l'analitzador, per tal de traduir-les. Aquí podeu controlar quines cadenes voleu traduir, i aplicar-los transformacions abans i després de la mateixa traducció.

Rep el text extret, la referència d'on s'ha trobat, i un hash que conté informació extra per controlar quines cadenes s'han de traduir, com traduir-les, i com generar el comentari.

El contingut d'aquestes opcions depèn del tipus de cadena que sigui (especificat en una entrada d'aquest hash):

type="tag"
La cadena trobada és el contingut d'un tag traduïble. L'entrada ``tag_options'' conté els caràcters d'opcions de davant la jerarquia de tags de l'opció ``tags'' del mòdul.
type="attribute"
Significa que la cadena trobada és el valor d'un atribut traduïble. L'entrada ``attribute'' conté el nom de l'atribut.

Ha de retornar el text que reemplaçarà l'original al document traduït. Aquí hi ha un exemple bàsic d'aquesta funció: 

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

Podeu trobar un altre exemple simple en el mòdul de Dia, que tan sols filtra algunes cadenes.  

MODIFICANT ELS TIPUS DE TAGS (PER FER)

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
Especifica el principi del tag, després de ``<''.
end
Especifica el final del tag, abans de ``>''.
breaking
Indica si aquesta classe de tags és trencadora. Un tag no-trencador (inline) és un que es pot agafar com a part del contingut d'un altre tag. Pot prendre els valors fals (0), cert (1) o indefinit. Si el deixeu indefinit, haureu de definir la funció f_breaking que dirà si un tag concret d'aquesta classe és trencador o no.
f_breaking
És una funció que dirà si el següent tag és trencador o no. S'ha de definir si l'opció breaking no ho està.
f_extract
Si deixeu aquesta funció indefinida, la funció d'extracció genèrica s'encarregarà d'extreure aquests tags. És útil per tags que poden contenir altres tags o estructures especials a dins, per tal que l'analitzador principal no es torni boig. Aquesta funció rep un booleà que indica si el tag s'ha d'eliminar de la seqüència d'entrada o no.
f_translate
Aquesta funció rep el tag (en el format de get_string_until()) i retorna el tag traduït (amb els atributs traduïts o totes les transformacions necessàries) com una única cadena.
 

INTERNAL FUNCTIONS used to write derivative parsers

 

TREBALLANT AMB TAGS

get_path()
Aquesta funció retorna el camí des de l'arrel del document fins al tag actual, de la forma <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()
Aquesta funció retorna l'índex de la llista tag_types que encaixa amb el següent tag de la seqüència d'entrada, o -1 si s'ha arribat al final del document d'entrada.

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($$)
Aquesta funció retorna el següent tag de la seqüència d'entrada sense el principi i el final, en forma de vector, per tal de mantenir les referències del fitxer d'entrada. Té dos paràmetres: el tipus del tag (de la forma retornada per tag_type) i un booleà, que indica si s'ha d'eliminar de la seqüència d'entrada.

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(@)
Aquesta funció retorna el nom del tag passar com a paràmetre, en la forma de vector retornat per extract_tag.
breaking_tag()
Aquesta funció retorna un booleà que diu si el següent tag de la seqüència d'entrada és un tag trencador de seqüència o no (tag inline). Deixa la seqüència d'entrada intacta.
treat_tag()
Aquesta funció tradueix el següent tag de la seqüència d'entrada. Utilitza les funcions de traducció personalitzades de cada tipus de tag.

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($@)
Aquesta funció retorna una cadena que indica si el primer paràmetre (una jerarquia de tags) encaixa amb algun dels tags del segon paràmetre (una llista de tags o jerarquies de tags). Si no encaixa, retorna 0. En cas contrari, retorna les opcions del tag encaixat (els caràcters davant del tag) o 1 (si el tag no té opcions).
 

TREBALLANT AMB ATRIBUTS

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

 

TREBALLANT AMB LES OPCIONS DELS MÒDULS

treat_options()
Aquesta funció omple les estructures internes que contenen els tags, atributs i dades inline amb les opcions del mòdul (especificades a la línia de comandes o a la funció d'inicialització).
 

OBTENINT TEXT DEL DOCUMENT D'ENTRADA

get_string_until($%)
Aquesta funció retorna un vector amb les línies (i les referències) del document d'entrada fins que troba el primer paràmetre. El segon paràmetre és un hash d'opcions. El valor 0 significa desactivat (per defecte) i 1, activat.

Les opcions vàlides són:

include
Fa que la cadena retornada contingui el text buscat
remove
Elimina de l'entrada la cadena retornada
unquoted
Assegura que el text buscat no està envoltat de cometes
regex
This denotes that the first argument is a regular expression rather than an plain string
skip_spaces(\@)
Aquesta funció rep com a paràmetre la referència a un paràgraf (en el format retornat per get_string_until), se salta els espais del principi, i els retorna com una cadena simple.
join_lines(@)
Aquesta funció retorna una cadena simple amb el text del vector de paràmetre (descartant les referències).
 

ESTAT D'AQUEST MÒDUL

Aquest mòdul pot traduir tags i atributs.  

LLISTA DE TASQUES PENDENTS

DOCTYPE (ENTITATS)

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.

MODIFICAR ELS TIPUS DE TAGS DES DELS MÒDULS HEREDATS (moure l'estructura tag_types dins del hash $self?)  

CONSULTEU TAMBÉ

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

AUTORS

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

TRADUCCIÓ

 Carme Cirera <menxu@hotmail.com>
 Jordi Vilalta <jvprat@gmail.com>
 

DRET DE CÒPIA I LLICÈNCIA

 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

NOM
DESCRIPCIÓ
TRADUINT AMB PO4A::XML
OPCIONS QUE ACCEPTA AQUEST MÒDUL
WRITING DERIVATIVE MODULES
DEFINIR ELS TAGS I ATRIBUTS A TRADUIR
OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
REESCRIVINT LA FUNCIÓ found_string
MODIFICANT ELS TIPUS DE TAGS (PER FER)
INTERNAL FUNCTIONS used to write derivative parsers
TREBALLANT AMB TAGS
TREBALLANT AMB ATRIBUTS
WORKING WITH TAGGED CONTENTS
TREBALLANT AMB LES OPCIONS DELS MÒDULS
OBTENINT TEXT DEL DOCUMENT D'ENTRADA
ESTAT D'AQUEST MÒDUL
LLISTA DE TASQUES PENDENTS
CONSULTEU TAMBÉ
AUTORS
TRADUCCIÓ
DRET DE CÒPIA I LLICÈNCIA
This document was created by using the manual pages.
Time: 00:28:40 GMT, January 29, 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)