blib::man::Xml(3pm)

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

DESCRIPCIO
L'objectiu del projecte po4a (po per a tot) es facilitar la traduccio (i sobretot el manteniment de les traduccions) utilitzant les eines de gettext en arees on no eren d'esperar, com ara en la documentacio.

Locale::Po4a::XmL es un modul per ajudar en la traduccio de documents XML a altres llenguatges [humans]. Tambe es pot utilitzar com a base per construir moduls per documents basats en XML.

Tingueu en compte que aquest modul encara esta en desenvolupament, i no es distribueix en les versions oficials de po4a perque creiem que encara no es prou madur. Si el voleu provar de totes maneres, agafeu-lo del CVS.

TRADUINT AMB PO4A::XML
Aquest modul es pot utilitzar directament per tractar documents XML generics. Aquest extraura el contingut de tots els tags, i cap atribut, ja que aqui es on s'escriu el text en la majoria de documents basats en XML.

Hi ha algunes opcions (descrites a la propera seccio) que permeten personalitzar aquest comportament. Si aixo no acaba d'encaixar amb el vostre format de document, us animo a escriure el vostre propi modul derivat d'aquest, per descriure els detalls del vostre format. Consulteu la seccio "Escrivint moduls derivats" mes avall, per la descripcio del proces.

OPCIONS QUE ACCEPTA AQUEST MODUL
L'opcio global de depuracio fa que aquest modul mostri les cadenes excloses, per tal de comprovar si se salta quelcom important.

Aquestes son les opcions particulars d'aquest modul:

nostrip
    Evita que es netegin els espais al voltant de les cadenes extretes.

wrap
    Canonitza les cadenes a traduir, considerant que els espais no son importants, i justifica el document traduiet. Aquest comportament es pot modificar des de les opcions personalitzades de cada tag. Vegeu l'opcio "tags" de mes avall.

caseinsensitive
    Fa que la cerca de tags i atributs es faci independentment de majuscules i minuscules. Si esta definit, tractara els tags <BooK>laNG i <BOOK>Lang com <book>lang.

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

doctype
    Cadena que s'intentara encaixar amb la primera linia del tipus de document (si esta definit). Si falla, es considerara que el document es de tipus erroni.

tags
    Llista separada per espais dels tags que voleu traduir o saltar. Per defecte, els tags especificats s'exclouran, pero si utilitzeu l'opcio "tagsonly", els tags especificats seran els unics inclosos. Els tags han d'estar en la forma <aaa>, pero podeu ajuntar-ne alguns (<bbb><aaa>) per dir que nomes s'ha de traduir el contingut del tag <aaa> quan estigui dins d'un tag <bbb>.

    Tambe podeu especificar algunes opcions de cada tag posant alguns caracters davant de la gerarquia de tags. Per exemple, podeu posar 'w' (wrap, justificar) o 'W' (no justificar) per saltar el comportament per defecte especificat en l'opcio global "wrap".

    Exemple: W<chapter><title>

attributes
    Llista separada per espais dels atributs dels tags que voleu traduir. Podeu especificar els atributs pel seu nom (per exemple, "lang"), pero tambe podeu prefixar-los amb una jerarquia de tags, per especificar que nomes es tradueixi quan estigui dins del tag especificat. Per exemple: <bbb><aaa>lang especifica que l'atribut lang nomes es traduira quan estigui dins d'un tag <aaa>, i aquest estigui dins d'un tag <bbb>.

inline
    Llista separada per espais dels tags que voleu tractar com a inline (que no trenquin la sequeencia). Per defecte, tots els tags trenquen la sequeencia. Aquesta opcio segueix la mateixa sintaxi de l'opcio tags.

nodefault
    Space separated list of tags that the module should not try to set by default in the "tags" or "inline" category.

ESCRIVINT MODULS DERIVATS

  DEFINIR ELS TAGS I ATRIBUTS A TRADUIR
La personalitzacio mes simple tracta de definir quins tags i atributs voleu que l'analitzador tradueixi. Aixo s'ha de fer en la funcio initialize. Primer haureu de cridar l'initialize principal, per tal d'obtenir les opcions de la linia de comandes, i despres afegir les definicions personalitzades al hash d'opcions. Si voleu tractar algunes opcions noves de la linia 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 FUNCIO found_string
Una altra forma simple es sobreescriure la funcio "found_string", que rep les cadenes que extreu l'analitzador, per tal de traduir-les. Aqui podeu controlar quines cadenes voleu traduir, i aplicar-los transformacions abans i despres de la mateixa traduccio.

Rep el text extret, la referencia d'on s'ha trobat, i un hash que conte informacio extra per controlar quines cadenes s'han de traduir, com traduir-les, i com generar el comentari.

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

type="tag"
    La cadena trobada es el contingut d'un tag traduieble. L'entrada "tag_options" conte els caracters d'opcions de davant la jerarquia de tags de l'opcio "tags" del modul.

type="attribute"
    Significa que la cadena trobada es el valor d'un atribut traduieble. L'entrada "attribute" conte el nom de l'atribut.

Ha de retornar el text que reemplacara l'original al document traduiet. Aqui hi ha un exemple basic d'aquesta funcio:

  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 modul de Dia, que tan sols filtra algunes cadenes.

  MODIFICANT ELS TIPUS DE TAGS (PER FER)
Aquesta es mes complexa, pero permet una personalitzacio (practicament) total. Esta 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 mes generals apareguin despres dels mes concrets (ordenats primer per la clau de principi i despres per la de final). Per definir un tipus de tag haureu de construir un hash amb les segueents claus:

beginning
    Especifica el principi del tag, despres de "<".

end Especifica el final del tag, abans de ">".

breaking
    Indica si aquesta classe de tags es trencadora. Un tag no-trencador (inline) es 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 funcio f_breaking que dira si un tag concret d'aquesta classe es trencador o no.

f_breaking
    Es una funcio que dira si el segueent tag es trencador o no. S'ha de definir si l'opcio "breaking" no ho esta.

f_extract
    Si deixeu aquesta funcio indefinida, la funcio d'extraccio generica s'encarregara d'extreure aquests tags. Es util per tags que poden contenir altres tags o estructures especials a dins, per tal que l'analitzador principal no es torni boig. Aquesta funcio rep un boolea que indica si el tag s'ha d'eliminar de la sequeencia d'entrada o no.

f_translate
    Aquesta funcio rep el tag (en el format de get_string_until()) i retorna el tag traduiet (amb els atributs traduiets o totes les transformacions necessaries) com una unica cadena.

FUNCIONS INTERNES utilitzades per escriure analitzadors derivats

  TREBALLANT AMB TAGS

get_path()
    Aquesta funcio retorna el cami des de l'arrel del document fins al tag actual, de la forma <html><body><p>.

tag_type()
    Aquesta funcio retorna l'index de la llista tag_types que encaixa amb el segueent tag de la sequeencia d'entrada, o -1 si s'ha arribat al final del document d'entrada.

extract_tag($$)
    Aquesta funcio retorna el segueent tag de la sequeencia d'entrada sense el principi i el final, en forma de vector, per tal de mantenir les referencies del fitxer d'entrada. Te dos parametres: el tipus del tag (de la forma retornada per tag_type) i un boolea, que indica si s'ha d'eliminar de la sequeencia d'entrada.

get_tag_name(@)
    Aquesta funcio retorna el nom del tag passar com a parametre, en la forma de vector retornat per extract_tag.

breaking_tag()
    Aquesta funcio retorna un boolea que diu si el segueent tag de la sequeencia d'entrada es un tag trencador de sequeencia o no (tag inline). Deixa la sequeencia d'entrada intacta.

treat_tag()
    Aquesta funcio tradueix el segueent tag de la sequeencia d'entrada. Utilitza les funcions de traduccio personalitzades de cada tipus de tag.

tag_in_list($@)
    Aquesta funcio retorna una cadena que indica si el primer parametre (una jerarquia de tags) encaixa amb algun dels tags del segon parametre (una llista de tags o jerarquies de tags). Si no encaixa, retorna 0. En cas contrari, retorna les opcions del tag encaixat (els caracters davant del tag) o 1 (si el tag no te opcions).

  TREBALLANT AMB ATRIBUTS

treat_attributes(@)
    Aquesta funcio tracta la traduccio dels atributs dels tags. Rep un tag sense les marques de principi i final, busca els atributs, i tradueix els traduiebles (especificats a l'opcio "attributes" del modul). Retorna una cadena plana amb el tag traduiet.

  TREBALLANT AMB LES OPCIONS DELS MODULS

treat_options()
    Aquesta funcio omple les estructures internes que contenen els tags, atributs i dades inline amb les opcions del modul (especificades a la linia de comandes o a la funcio d'inicialitzacio).

  OBTENINT TEXT DEL DOCUMENT D'ENTRADA

get_string_until($%)
    Aquesta funcio retorna un vector amb les linies (i les referencies) del document d'entrada fins que troba el primer parametre. El segon parametre es un hash d'opcions. El valor 0 significa desactivat (per defecte) i 1, activat.

    Les opcions valides son:

    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 esta envoltat de cometes

skip_spaces(\@)
    Aquesta funcio rep com a parametre la referencia a un paragraf (en el format retornat per get_string_until), se salta els espais del principi, i els retorna com una cadena simple.

join_lines(@)
    Aquesta funcio retorna una cadena simple amb el text del vector de parametre (descartant les referencies).

ESTAT D'AQUEST MODUL
Aquest modul pot traduir tags i atributs.

El suport d'entitats i fitxers inclosos esta a la llista de tasques pendents.

L'escriptura de moduls derivats encara es forca 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 MODULS HEREDATS (moure l'estructura tag_types dins del hash $self?)

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

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

AUTORS
 Jordi Vilalta <jvprat@gmail.com>

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

DRET DE COPIA I LLICENCIA
Copyright (c) 2004 per Jordi Vilalta <jvprat@gmail.com>

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