Provided by: po4a_0.52-1_all 
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
Canonicalizes the string to translate, considering that whitespaces are not important,
and wraps the translated document. This option can be overridden by custom tag
options. See the "tags" option below.
unwrap_attributes
Attributes are wrapped by default. This option disables wrapping.
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.
escapequotes
Escape quotes in output strings. Necessary, for example, for creating string
resources for use by Android build tools.
See also: https://developer.android.com/guide/topics/resources/string-resource.html
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
This option defines the behavior of the module when it encounters 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
É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 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>
Nota: Esta opción está obsoleta. En lugar de ello, debería usar las opciones
translated y untranslated.
attributes
Space-separated list of tag's attributes you want to translate. You can specify the
attributes by their name (for example, "lang"), but you can prefix it with a tag
hierarchy, to specify that this attribute will only be translated when it's in the
specified tag. For example: <bbb><aaa>lang specifies that the lang attribute will only
be translated if it's in an <aaa> tag, and it's in a <bbb> tag.
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.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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\"/>
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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)
This is a more complex one, but it enables a (almost) total customization. It's based on
a list of hashes, each one defining a tag type's behavior. The list should be sorted so
that the most general tags are after the most concrete ones (sorted first by the beginning
and then by the end keys). To define a tag type you'll have to make a hash with the
following keys:
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>
TRADUCCION
Jordi Vilalta <jvprat@gmail.com>
Omar Campagne <ocampagne@gmail.com>
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).