Locale::Po4a::Xml

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

Canonitza les cadenes a traduir, considerant que els espais no són importants, i justifica el document traduït. Aquest comportament es pot modificar des de les opcions personalitzades de cada tag. Vegeu l’opció "tags" de més avall.

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.

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 encounter a 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

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

Note: This option is deprecated.

doctype

Cadena que s’intentarà encaixar amb la primera línia del tipus de document (si està definit). Si falla, es considerarà que el document és de tipus erroni.

ESCRIVINT MÒDULS DERIVATS

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}{'nova_opcio'}='';
  $self−>SUPER::initialize(%options);
  $self−>{options}{'tags'}.=' <p> <head><title>';
  $self−>{options}{'attributes'}.=' <p>lang id';
  $self−>{options}{'inline'}.=' <br>';
  $self−>treat_options;

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 )

Aquesta és més complexa, però permet una personalització (pràcticament) total. Està basada en una llista de hashs, on cadascun defineix el comportament d’un tipus de tag. La llista ha d’estar ordenada de forma que els tags més generals apareguin després dels més concrets (ordenats primer per la clau de principi i després per la de final). Per definir un tipus de tag haureu de construir un hash amb les següents claus:
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.

FUNCIONS INTERNES utilitzades per escriure analitzadors derivats

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

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.

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.

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.

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(@)

Aquesta funció tracta la traducció dels atributs dels tags. Rep un tag sense les marques de principi i final, busca els atributs, i tradueix els traduïbles (especificats a l’opció "attributes" del mòdul). Retorna una cadena plana amb el tag traduït.

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

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.

El suport d’entitats i fitxers inclosos està a la llista de tasques pendents.

L’escriptura de mòduls derivats encara és força limitada.

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.

FITXERS INCLOSOS

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

tag trencador dins d’un tag no-trencador (possible?) provoca comentaris lletjos

CONSULTEU TAMBÉ

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

AUTORS

 Jordi Vilalta <jvprat AT gmail DOT com>

TRADUCCIÓ

 Carme Cirera <menxu AT hotmail DOT com>
 Jordi Vilalta <jvprat AT gmail DOT com>

DRET DE CÒPIA I LLICÈNCIA

Aquest programa és programari lliure; podeu redistribuir-lo i/o modificar-lo sota els termes de la GPL (consulteu el fitxer COPYING ).

pdf

sourCEntral - mobile manpages