sourCEntral - mobile manpages

pdf

Locale::Po4a::Xml

NOMBRE

Locale::Po4a::Xml − Convierte documentos XML y derivados desde/a archivos PO

DESCRIPCION

El objetivo del proyecto po4a (po para todo) es facilitar la traducción (y más interesante, el mantenimiento de las traducciones) usando las herramientas de gettext en áreas dónde no eran de esperar, como en la documentación.

Locale::Po4a::Xml es un módulo para ayudar en la traducción de documentación en el formato XML a otros lenguajes [humanos]. También se puede usar como base para construir módulos para documentos basados en XML .

TRADUCIENDO CON PO4A::XML

Este módulo puede usarse directamente para tratar documentos XML genéricos. Esto extraerá el contenido de todos los tags, y ningún atributo, ya que ahí es donde se escribe el texto en la mayoría de documentos basados en XML .

Hay algunas opciones (descritas en la siguiente sección) que pueden personalizar este comportamiento. Si eso no es suficiente para su formato de documento, le animo a que escriba su propio módulo derivado de éste, para describir los detalles de su formato. Consulte la sección "Escribiendo módulos derivados" de más abajo, para una descripción del proceso.

OPCIONES ACEPTADAS POR ESTE MODULO

La opción debug global provoca que este módulo muestre las cadenas excluidas, para ver si se salta algo importante.

Estas son las opciones particulares de este módulo:
nostrip

Evita que se quiten los espacios alrededor de las cadenas extraídas.

wrap

Canoniza las cadenas a traducir, considerando que los espacios en blanco no son importantes, y justifica el documento traducido. Tienen preferencia sobre esta, las opciones personalizadas de cada tag. Consulte la opción "tags" de más abajo.

caseinsensitive

Realiza las búsquedas de tags y atributos sin tener en cuenta mayúsculas y minúsculas. Si está definido, tratará <BooK>laNG y < BOOK >Lang como <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 intentará encajar con la primera línea del doctype del documento (si está definida). Si no encaja, se considerará que el documento es de un tipo equivocado.

tags

Lista separada por espacios de los tags que desea traducir o omitir. Por defecto, los tags especificados serán excluidos, pero si utiliza la opción "tagsonly", los tags especificados serán los únicos incluidos. Los tags deben estar en la forma <aaa>, pero puede juntar algunos (<bbb><aaa>) para indicar que el contenido del tag <aaa> sólo se debe traducir cuando esté dentro del tag <bbb>.

También puede especificar algunas opciones de tags poniendo algunos caracteres delante de la jerarquía de tags. Por ejemplo, puede poner ’w’ (justificar) o ’W’ (no justificar) para hacer caso omiso del comportamiento por defecto especificaco por la opción global "wrap".

Ejemplo: W<chapter><title>

Note: This option is deprecated. You should use the translated and untranslate options instead.

attributes

Lista separada por espacios de los atributos de tags que quiere traducir. Puede especificar los atributos por su nombre (por ejemplo, "lang"), pero puede añadirle como prefijo una jerarquía de tags, para especificar que este tag sólo se debe traducir cuando esté dentro del tag especificado. Por ejemplo: <bbb><aaa>lang indica que el atributo lang sólo se traducirá cuando esté dentro del tag <aaa>, y este esté dentro de un tag <bbb>.

inline

Lista separada por espacios de los tags que quiere tratar como inline (que no rompen la secuencia). Por defecto, todos los tags rompen la secuencia. Sigue la misma sintaxis que la opción tags.

nodefault

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

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
unstranslated

Space-separated list of the tags you want to translate or not. The tags must be in the form <aaa>, but you can join some (<bbb><aaa>) to indicate 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 putting some characters in front of the tag hierarchy. For example, you can put ’w’ (wrap) or ’W’ (don’t wrap) to overide the default behavior specified by the global "wrap" option.

Ejemplo: W<chapter><title>

ESCRIBIENDO MODULOS DERIVADOS

DEFINIR QUE TAGS Y ATRIBUTOS TRADUCIR

La personalización más simple es definir qué tags y atributos quiere que el analizador traduzca. Esto se debe hacer en la función initialize. Primero debe llamar a la inicialización principal, para obtener las opciones de línea de comandos, y luego, añadir sus definiciones personalizadas al hash de opciones. Si quiere tratar nuevas opciones de la línea de comandos, debe definirlas antes de llamar a la función initialize principal:

  $self−>{options}{'nueva_opcion'}='';
  $self−>SUPER::initialize(%options);
  $self−>{options}{'tags'}.=' <p> <head><title>';
  $self−>{options}{'attributes'}.=' <p>lang id';
  $self−>{options}{'inline'}.=' <br>';
  $self−>treat_options;

REDEFINIENDO LA FUNCION found_string

Otro paso simple es redefinir la función "found_string", que recibe las cadenas extraídas por el analizador, para traducirlas. Ahí puede controlar qué cadenas quiere traducir, y realizar pequeñas traducciones anyes o después de la traducción misma.

Recibe el texto extraído, la referencia de dónde está, y un hash que contiene información extra para controlar qué cadenas traducir, cómo traducirlas y generar el comentario.

El contenido de las opciones depende del tipo de cadena que sea (especificado en una entrada del hash):
type="tag"

La cadena encontrada es el contenido de un tag traducible. La entrada "tag_options" contiene los caracteres de opciones que hubiera delante de la jerarquía de tags en la opción "tags" del módulo.

type="attribute"

Significa que la cadena encontrada es el valor de un atributo traducible. La entrada "attribute" contiene el nombre del atributo.

Debe devolver el texto que reemplazará al original en el documento traducido. Aquí hay un ejemplo básico de ésta función:

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

Hay otro ejemplo simple en el nuevo módulo de Dia, que sólo filtra algunas cadenas.

MODIFICANDO LOS TIPOS DE TAGS

Esta personalización es más compleja, pero le permite (prácticamente) una personalización total. Está basada en una lista de hashes, cada uno de los cuales define el comportamiento de un tipo de tags. La lista debe estar ordenada para que los tags más generales estén después de los más concretos (ordenado primero por la llave beginning y luego por la end). Para definir un tipo de tag debe construir un hash con las siguientes llaves:
beginning

Especifica el principio del tag, después del "<".

end

Especifica el final del tag, antes de ">".

breaking

Indica si esta clase de tags rompe la secuencia. Un tag no rompedor (inline) es uno que puede tomarse como parte del contenido de otro tag. Puede tomar valores falso (0), cierto (1) o indefinido. Si se deja indefinido, deeberá definir la función f_breaking que indicará si un tag concreto de esta clase es rompedor o no.

f_breaking

Es una función que dirá si el siguiente tag es rompedor o no. Debe definirla si deja la opción "breaking" indefinida.

f_extract

Si deja esta llave indefinida, la función de extracción genérica deberá extraer el tag por si misma. Es interesante para tags que pueden que pueden contener otros tags o estructuras especiales dentro, y que puedeen confundir al analizador principal. Esta función recibe un booleano que indica si el tag se debe eliminar del documento de entrada o no.

f_translate

Esta función devuelve el tag (en el formato de get_string_until()) y devuelve el tag traducido (atributos y toda la información necesaria traducidos) como una única cadena.

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

TRABAJANDO CON TAGS
get_path()

Esta función devuelve la ruta hasta el tag actual desde la raíz del documento, de la forma <html><body><p>.

tag_type()

Esta función devuelve el índice de la lista tag_types que encaja con el siguiente tag en el documento de entrada, o −1 si se está al final del fichero.

extract_tag($$)

Esta función devuelve el próximo tag del documento de entrada sin el principio ni el final, en forma de array, para mantener las referencias del fichero de entrada. Tiene dos parámetros: el tipo del tag (tal como devuelve tag_type) y un booleano, que indica si se debe eliminar del fichero de entrada.

get_tag_name(@)

Esta función devuelve el nombre del tag pasado como parámetro, en la forma de array devuelta por extract_tag.

breaking_tag()

Esta función devuelve un booleano que indica si el siguiente tag del documento de entrada es un tag "rompedor" o no (es un tag inline). Esto deja el documento de entrada intacto.

treat_tag()

Esta función traduce el siguiente tag del documento de entrada. Usa las funciones de traducción personalizadas de cada tipo de tag.

tag_in_list($@)

Esta función devuelve una cadena que dice si el primer parámetro (una gerarquía de tags) encaja con alguno de los tags del segundo parámetro (una lista de tags o jerarquías de tags). Si no encaja, devuelve 0. Sinó, devuelve las opciones del tag encajado (los caracteres delante del tag) o 1 (si el tag no tiene opciones).

TRABAJANDO CON ATRIBUTOS
treat_attributes(@)

Esta función trata la traducción de los atributos de los tags. Recibe un tag sin las marcas de principio / final, y luego busca los atributos, y traduce los traducibles (especificados por la opción "attributes" del módulo). Devuelve una cadena con el tag traducido.

TRABAJANDO CON LAS OPCIONES DEL MODULO
treat_options()

Esta función llena las estructuras internas que contienen los datos tags, atributos e "inline" con las opciones del módulo (especificadas en la línea de comandos o en la función de inicialización).

OBTENIENDO EL TEXTO DEL DOCUMENTO DE ENTRADA
get_string_until($%)

Esta función devuelve una lista con las lineas (y referencias) del documento de entrada hasta que encuentra el primer parámetro. El segundo parámetro es un hash de opciones. El valor 0 significa desactivado (por defecto) y 1, activado.

Las opciones válidas son:
include

Esto hace que el array de retorno contenga la cadena buscada

remove

Esto elimina de la entrada la cadena

unquoted

Esto asegura que el texto buscado se encuentra fuera de fragmentos encomillados

skip_spaces(\@)

Esta función recibe como parámetro la referencia a un párrafo (en el formato devuelto por get_string_until), salta los espacios del principio y los devuelve como una cadena simple.

join_lines(@)

Esta función devuelve una simple cadena con el texto del array del parámetro (descartando las referencias).

ESTADO DE ESTE MODULO

Este módulo puede traducir tags y atributos.

El soporte para entidades y inclusión de ficheros está en la lista de tareas pendientes.

La escritura de módulos derivados es aún muy limitada.

LISTA DE TAREAS PENDIENTES

DOCTYPE ( ENTIDADES )

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.

FICHEROS INCLUIDOS

" MODIFICAR LOS TIPOS DE TAGS DESDE LOS MODULOS HERENCIADOS (mover la estructura tag_types dentro del hash $self?)

un tag rompedor dentro de un tag no-rompedor (posible?) provoca comentarios muy feos

VER TAMBIEN

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

AUTORES

 Jordi Vilalta <jvprat AT gmail DOT com>

TRADUCCION

 Jordi Vilalta <jvprat AT gmail DOT com>

DERECHO DE COPIA Y LICENCIA

Copyright (c) 2004 por Jordi Vilalta <jvprat AT gmail DOT com>

Esto es software libre; puedes redistribuirlo y/o modificarlo bajo las condiciones de la GPL (ver el archivo COPYING ).

pdf