Provided by:
po4a_0.23-1_all 
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.
Tenga en cuenta que este módulo aún está en desarrollo, y no se
distribuye en los lanzamientos oficiales de po4a porque aún no lo
consideramos suficientemente maduro. Si desea probarlo de todas formas,
obténgalo del CVS.
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.
tagsonly
Extracts only the specified tags in the "tags" option. Otherwise,
it will extract all the tags except the ones specified.
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>
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.
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@gmail.com>
TRADUCCION
Jordi Vilalta <jvprat@gmail.com>
DERECHO DE COPIA Y LICENCIA
Copyright (c) 2004 por Jordi Vilalta <jvprat@gmail.com>
Esto es software libre; puedes redistribuirlo y/o modificarlo bajo las
condiciones de la GPL (ver el archivo COPYING).