NOMBRE¶
Locale::Po4a::Xml - Convierte documentos XML y derivados desde/a ficheros PO
DESCRIPCIÓN¶
El objetivo del proyecto po4a («PO for anything», PO para todo) es
facilitar la traducción (y más interesante, el mantenimiento de las
traducciones) usando las herramientas de gettext en áreas donde no eran
de esperar, como la documentación.
Locale::Po4a::Xml es un módulo que asiste 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.
TRADUCIR CON PO4A::XML¶
Este módulo se puede usar directamente para tratar documentos XML
genéricos. Extraerá el contenido de todas las etiquetas, 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 el formato de
su documento, le animo a que escriba su propio módulo derivado de
éste para describir los detalles de su formato. Consulte la sección
Escribir módulos derivados que encontrará 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
etiqueta. Consulte la opción «tags» más abajo.
- caseinsensitive
- Permite que las búsquedas de etiqueta y atributos no
tengan en cuenta mayúsculas y minúsculas. Si está definido,
tratará <BooK>laNG y <BOOK>Lang como
<book>lang.
- includeexternal
- Si se define, se incluirán las entidades externas en
el documento (traducido) generado, así como para la extracción
de cadenas. De no estar definido tendrá que traducir las entidades
externas separadamente, como documentos independientes.
- ontagerror
- Esta opción define el comportamiento del módulo
cuando encuentra una sintaxis XML no válida (una etiqueta de cierre
que no concuerda con la última etiqueta de inicio, o un atributo de
etiqueta sin un valor). Puede tomar los siguientes valores.
- fail
- Éste es el valor predefinido. El módulo
cerrará con un mensaje de error.
- warn
- El módulo continuará, mostrando una
advertencia.
- silent
- El módulo continuará sin advertencias.
Sea cuidadoso a la hora de usar esta opción. En general, recomendamos
arreglar el fichero de entrada.
- tagsonly
- Extrae únicamente las etiquetas especificadas en la
opción «tags». De no ser así, extraerá todas las
etiquetas excepto las especificadas.
Nota: Esta opción está obsoleta.
- doctype
- La cadena que intentará encajar con la primera
línea del «doctype» del documento (si está definida).
Una advertencia indicará que el documento puede ser de un tipo
equivocado, si no encaja.
- addlang
- Cadena que indica la ruta (por ejemplo,
<bbb><aaa>) de una etiqueta donde se ha de añadir el
atributo «lang="..."». El idioma se definirá como
el nombre base del fichero PO sin ninguna extensión
«po».
- tags
- Lista separada por espacios de las etiquetas que desea
traducir u omitir. Por omisión, se excluirán las etiquetas
especificadas, pero si utiliza la opción «tagsonly», las
etiquetas especificadas serán los únicos incluidos. Las
etiquetas deben tener la forma <aaa>, pero puede juntar algunos
(<bbb><aaa>) para indicar que el contenido de la etiqueta
<aaa> sólo se debe traducir cuando esté dentro de la
etiqueta <bbb>.
También puede especificar algunas opciones de etiqueta poniendo algunos
caracteres delante de la jerarquía de etiquetas. Por ejemplo, puede
poner «w» (justificar) o «W» (no justificar) para
hacer caso omiso del comportamiento predefinido especificado por la
opción global «wrap».
Ejemplo: W<chapter><title>
Nota: Esta opción está obsoleta. En lugar de ello, debería
usar las opciones translated y untranslated.
- attributes
- Lista separada por espacios de los atributos de etiquetas
que quiere traducir. Puede especificar los atributos por su nombre (por
ejemplo, «lang»), pero puede añadirle como prefijo una
jerarquía de etiquetas para especificar que esta etiqueta sólo
se debe traducir cuando esté dentro de la etiqueta especificada. Por
ejemplo: <bbb><aaa>lang indica que el atributo
«lang» sólo se traducirá cuando esté dentro de la
etiqueta <aaa>, y ésta esté dentro de una etiqueta
<bbb>.
- foldattributes
- No traduce los atributos en etiquetas en línea. En
lugar de ello, reemplaza todos los atributos de una etiqueta con
po4a-id=<id>.
Esto es útil cuando no se deben traducir los atributos, simplificando
las cadenas a las traductores evitando así errores al teclear.
- customtag
- Lista separada por espacios de las etiquetas que no se
deberían tratar como tales. Éstas se tratan como etiquetas en
línea, y no precisan cierre.
- break
- Lista separada por espacios de las etiquetas que
deberían romper la secuencia. Por omisión todas las etiquetas
rompen la secuencia.
Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
(<bbb><aaa>), si una etiqueta (<aaa>) sólo se debe
considerar cuando está dentro de otra etiqueta.
- inline
- Lista separada por espacios de las etiquetas que quiere
tratar como elementos en línea (que no rompen la secuencia). Por
omisión todas las etiquetas rompen la secuencia.
Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
(<bbb><aaa>), si una etiqueta (<aaa>) sólo se debe
considerar cuando está dentro de otra etiqueta.
- placeholder
- Lista separada por espacios de las etiquetas que se
deberían tratar como marcadores de posición
(«placeholders»). Éstos no rompen la secuencia, pero su
contenido se traduce separadamente.
La ubicación del «placeholder» dentro de su bloque se
marcará con una cadena similar a:
<placeholder type=\"footnote\" id=\"0\"/>
Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
(<bbb><aaa>), si una etiqueta (<aaa>) sólo se debe
considerar cuando está dentro de otra etiqueta.
- nodefault
- Una lista separada por espacios de etiquetas que el
módulo no debería definir en ninguna categoría de manera
predefinidas.
- cpp
- Compatibilidad con directivas de preprocesador de C. Si
activa esta opción, po4a tratará las directivas de preprocesador
como separadores de párrafo. Esto cobra importancia si se debe
preprocesar el fichero XML, ya que de otra forma las directivas se
podrían insertar en medio de la línea si po4a considera que
pertenecen al párrafo actual, y serían irreconocibles para el
preprocesador. Nota: las directivas del preprocesador deben aparecer entre
etiquetas (no deben romper etiquetas).
- translated
- Una lista separada por espacios de etiquetas que desea
traducir.
Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
(<bbb><aaa>), si una etiqueta (<aaa>) sólo se debe
considerar cuando está dentro de otra etiqueta.
También puede especificar algunas opciones de etiquetas poniendo
algunos caracteres delante de la jerarquía de etiquetas. Por ejemplo,
puede poner «w» (justificar) o «W» (no justificar)
para hacer caso omiso del comportamiento predefinido especificado por la
opción global «wrap».
Ejemplo: W<chapter><title>
- untranslated
- Lista separada por espacios de las etiquetas que no desea
traducir.
Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
(<bbb><aaa>), si una etiqueta (<aaa>) sólo se debe
considerar cuando está dentro de otra etiqueta.
- defaulttranslateoption
- Las categorías predefinidas para las etiquetas que no
pertenecen a translated, untranslated, break, inline, o placeholder.
Este es un conjunto de letras:
- w
- Las etiquetas deberían traducirse, y se puede
justificar el contenido.
- W
- Las etiquetas deberían traducirse, y no se debe
justificar el contenido.
- i
- Las etiquetas se deberían traducir como elementos en
línea.
- p
- Las etiquetas se deberían traducir como marcadores de
posición.
ESCRIBIR MÓDULOS DERIVADOS¶
DEFINIR QUÉ ETIQUETAS Y ATRIBUTOS TRADUCIR¶
La personalización más simple es definir qué etiquetas
(«tags») y atributos quiere que el analizador traduzca. Esto se debe
hacer en la función «initialize». Primero debe invocar la
inicialización principal, para obtener las opciones de la línea de
órdenes, y luego, añadir sus definiciones personalizadas a la tabla
«hash» de opciones. Si quiere tratar nuevas opciones de la
línea de órdenes, debe definirlas antes de invocar la función
«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;
Debería usar las opciones
_default_inline,
_default_break,
_default_placeholder,
_default_translated,
_default_untranslated y
_default_attributes con módulos
derivados. Esto permite a los usuarios invalidar el comportamiento predefinido
configurado en su módulo mediante las opciones de línea de
órdenes.
REDEFINIR LA FUNCIÓN found_string¶
Otro paso simple es redefinir la función «found_string», que
recibe las cadenas extraídas por el analizador para su traducción.
Ahí puede controlar qué cadenas quiere traducir, y realizar
pequeñas transformaciones antes o después de la traducción
misma.
Recibe el texto extraído, la referencia de dónde está, y una
tabla «hash» que contiene información adicional 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 de este «hash»):
- type="etiqueta"
- La cadena encontrada es el contenido de una etiqueta
(«tag») traducible. La entrada «tag_options» (opciones
de etiquetas) contiene los caracteres de opciones delante de la
jerarquía de etiquetas en la opción «tags» del
módulo.
- type="atributo"
- Significa que la cadena encontrada es el valor de un
atributo traducible. La entrada «atributo» 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,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
Aquí tiene otro ejemplo simple en el nuevo módulo Dia, que sólo
filtra algunas cadenas.
MODIFICAR LOS TIPOS DE ETIQUETA (PENDIENTE)¶
Esta personalización es más compleja, pero le permite una
personalización (prácticamente) total. Está basada en una lista
de tablas de elementos asociativos («hash»), cada una de las cuales
define el comportamiento de un tipo de etiqueta. La lista debe estar ordenada
para que las etiquetas más generales estén después de las
más concretas (ordenado primero por la llave «beginning» y
luego por la llave «end»). Para definir un tipo de etiqueta debe
construir un «hash» con las siguientes llaves:
- beginning
- Especifica el principio de la etiqueta, después de
«<».
- end
- Especifica el final de la etiqueta, antes de
«>».
- breaking
- Indica si esta clase de etiqueta rompe la secuencia. Una
etiqueta en línea («inline») que no rompe la secuencia es
uno que se puede tomar como parte del contenido de otra etiqueta. Puede
tomar los valores falso (0), verdadero (1) o indefinido. Si se deja
indefinido, deberá definir la función «f_breaking»,
que indicará si una etiqueta de esta clase en concreto rompe o no la
secuencia.
- f_breaking
- Es una función que dirá si la siguiente etiqueta
rompe o no. Debe definirla si la opción breaking no lo
está.
- f_extract
- Si deja esta llave indefinida, la función de
extracción genérica deberá extraer la etiqueta por si
misma. Es útil con etiquetas que pueden contener otras etiquetas o
estructuras especiales dentro, y que pueden confundir al analizador
principal. Esta función recibe un booleano que indica si la etiqueta
se debe eliminar del documento de entrada o no.
- f_translate
- Esta función devuelve la etiqueta (en el formato
« get_string_until()») y devuelve la etiqueta traducida
(atributos y toda la información necesaria traducidos) como una
única cadena.
FUNCIONES INTERNAS utilizadas para escribir analizadores
derivados¶
TRABAJAR CON ETIQUETAS¶
- get_path()
- Esta función devuelve la ruta hasta la etiqueta actual
desde la raíz del documento, con la forma
<html><body><p>.
Puede introducir como argumento una lista adicional de etiquetas (sin
corchetes). Estos elementos de ruta se añaden la final de la ruta
actual.
- tag_type()
- Esta función devuelve el índice de la lista
«tag_types» que encaja con la siguiente etiqueta en el documento
de entrada, o «-1» si está al final del fichero.
- extract_tag($$)
- Esta función devuelve la próxima etiqueta del
documento de entrada sin el principio ni el final, en forma de vector
(«array»), para mantener las referencias del fichero de entrada.
Tiene dos parámetros: el tipo de la etiqueta (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 de la etiqueta
introducida como argumento, en la forma de vector devuelta por
«extract_tag».
- breaking_tag()
- Esta función devuelve un booleano que indica si la
siguiente etiqueta del documento de entrada es una etiqueta que rompe o no
(es una etiqueta en línea). Esto deja el documento de entrada
intacto.
- treat_tag()
- Esta función traduce la siguiente etiqueta del
documento de entrada. Usa las funciones de traducción personalizadas
de cada tipo de etiqueta.
- tag_in_list($@)
- Esta función devuelve una cadena que dice si el primer
argumento (una jerarquía de etiquetas) encaja con alguna de las
etiquetas del segundo argumento (una lista de etiquetas o jerarquías
de etiqueta). Si no encaja, devuelve cero. De otra forma, devuelve las
opciones de la etiqueta emparejada (los caracteres delante de la etiqueta)
o 1 (si la etiqueta no tiene opciones).
TRABAJAR CON ATRIBUTOS¶
- treat_attributes(@)
- Esta función trata la traducción de los atributos
de las etiquetas. Recibe una etiqueta sin las marcas beginning / end, y
luego busca los atributos y traduce los traducibles (especificados con la
opción «attributes» del módulo). Devuelve una cadena
con la etiqueta traducido.
TRABAJAR CON LAS OPCIONES DEL MÓDULO¶
- treat_options()
- Esta función llena las estructuras internas que
contienen las etiquetas, atributos y datos de elementos en línea con
las opciones del módulo (especificadas en la línea de
órdenes o en la función «initialize»).
OBTENER 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
argumento. El segundo argumento es una tabla «hash» de opciones.
El valor de cero significa desactivado (valor predefinido) y 1, activado.
Las opciones válidas son:
- include
- Esto hace que la lista de retorno contenga la cadena
buscada.
- remove
- Esto elimina el flujo devuelto de la entrada.
- unquoted
- Esto asegura que el texto buscado se encuentra fuera de
cadenas entrecomilladas.
- skip_spaces(\@)
- Esta función recibe como argumento la referencia a un
párrafo (en el formato devuelto por «get_string_until»),
omite los espacios de la cabecera y los devuelve como una cadena
simple.
- join_lines(@)
- Esta función devuelve una cadena simple con el texto
de la lista del argumento (descartando las referencias).
ESTADO DE ESTE MODULO¶
Este módulo puede traducir etiquetas y atributos.
LISTA DE TAREAS PENDIENTES¶
DOCTYPE (ENTIDADES)
Existe una mínima compatibilidad con la traducción de entidades. Se
traducen en conjunto, y no se tienen en cuenta las etiquetas. Las entidades
multi-línea no son compatibles y siempre se justifican las entidades
durante la traducción.
MODIFICAR LOS TIPOS DE ETIQUETA DE LOS MÓDULOS HEREDADOS (¿mover la
estructura «tag_types» dentro de la tabla hash $self?)
VÉASE TAMBIÉN¶
Locale::Po4a::TransTractor(3pm),
po4a(7)
AUTORES¶
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
DERECHO DE COPIA Y LICENCIA¶
Copyright (c) 2004 por Jordi Vilalta <jvprat@gmail.com>
Copyright (c) 2008-2009 por Nicolas François <nicolas.francois@centraliens.net>
Esto es software libre; puede redistribuirlo y/o modificarlo bajo las
condiciones de la licencia GPL (consulte el fichero COPYING).