oracular (3) Locale::Po4a::Xml.3pm.gz
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 ámbitos dónde no
previstos, 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 translated más abajo.
unwrap_attributes
Los atributos se justifican de forma predefinida. Esta opción desactiva el justificado.
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 de comillas en las cadenas de salida. Necesarias, por ejemplo, para crear recursos de cadenas
para us uso en herramientas de compilación Android.
Consulte también: 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
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). 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
Nota: Esta opción está obsoleta.
Extrae únicamente las etiquetas especificadas en la opción tags. De no ser así, extraerá todas las
etiquetas excepto las especificadas.
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».
optionalclosingtag
Expresión booleana que indica si las etiquetas de cierre son opcionales (como en HTML). Por defecto,
las etiquetas de cierre que faltan generan un error que se gestiona según ontagerror.
tags
Nota: Esta opción está obsoleta. En lugar de ello, debería usar las opciones translated y
untranslated.
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 (ajustar) o W (no ajustar) para hacer caso omiso
del comportamiento predefinido especificado por la opción global wrap.
Ejemplo: W<chapter><title>
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.
Tenga en cuenta que una etiqueta solo se puede introducir en solo una de las cadenas de ajuste break,
inline placeholder, o customtag.
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.
break-pi
Por defecto, las Instrucciones de Procesado (es decir, las etiquetas "<? ... ?>") se tratan como
etiquetas en línea. Pase esta opción si desea que la IP sea manejada como etiqueta de ruptura. Note
que las etiquetas PHP no procesadas son manejadas como Instrucciones de Procesado por el analizador
sintáctico.
nodefault
Una lista separada por espacios de etiquetas que el módulo no debería definir en ninguna categoría de
manera predefinidas.
Si existe una etiqueta cuyo ajuste predefindo se deriva de la subclase de este módulo, pero desea
definir un ajuste alternativo, debe introducir tal etiqueta como parte de la cadena de ajuste
nodefault.
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. Esto anula el comportamiento predefinido especificado por las opciones
globales wrap y defaulttranslateoption.
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.
Internamente, el analizador XML solo tiene en cuenta estas cuatro opciones: w W i p.
* Las etiquetas listadas en break se establecen en w o W en función de la opción wrap.
* Las etiquetas que aparecen en inline se establecen en i.
* Las etiquetas listadas en placeholder se establecen en p.
* Las etiquetas listadas en untranslated no tienen ninguna de estas opciones establecidas.
Puede comprobar el comportamiento de parámatro interno real invocando po4a con la opción --debug.
Ejemplo: W<chapter><title>
Tenga en cuenta que una etiqueta se debe introducir en la cadena de ajuste de translated o
untranslated.
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.
Tenga en cuenta que una etiqueta en línea traducible en una etiqueta no traducida se trata como una
etiqueta de ruptura traducible, se omite el ajuste i y se ajusta w o W según la opción wrap.
defaulttranslateoption
Las categorías predefinidas para las etiquetas que no pertenecen a translated, untranslated, break,
inline, o placeholder.
Esto es un conjunto de letras como define translated, y este ajuste solo es válido para etiquetas
traducibles.
ESCRITURA DE 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.
ANULACIÓN DEL COMPORTAMIENTO PREDEFINIDO CON OPCIONES DE LA LÍNEA DE ÓRDENES
Si no le satisface el comportamiento predefindo de este módulo xml y sus módulos derivados, puede
proporcionar opciones de línea de órdenes para modificar su comportamiento.
Consulte Locale::Po4a::Docbook(3pm),
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.
Aquí, la etiqueta presente una estructura iniciada por < y finalizada por >, y puede contener varias
líneas.
Esto funciona con la matriz "@{$self->{TT}{doc_in}}" que contiene los datos de documento de entrad y
su referencia indirecta mediante "$self->shiftline()" y "$self->unshiftline($$)".
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.
Esto funciona con la matriz "@{$self->{TT}{doc_in}}" que contiene los datos de documento de entrad y
su referencia indirecta mediante "$self->shiftline()" y "$self->unshiftline($$)".
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.
Esto funciona con la matriz "@{$self->{TT}{doc_in}}" que contiene los datos de documento de entrad y
su referencia indirecta mediante "$self->shiftline()" y "$self->unshiftline($$)".
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 traducida.
TRABAJAR CON CONTENIDO ETIQUETADO
treat_content()
Esta función obtien el texto hasta la siguiente etiqueta de ruptura (no en línea) del flujo de
entrada. Traduzca utilizando cada función de traducción personalizada de tipo de etiqueta.
Esto funciona con la matriz "@{$self->{TT}{doc_in}}" que contiene los datos de documento de entrad y
su referencia indirecta mediante "$self->shiftline()" y "$self->unshiftline($$)".
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 retornada 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
regex
Esto indica que el primer argumento es una expresión regular en lugar de una cadena sin formato
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 © 2004 Jordi Vilalta <jvprat@gmail.com> Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net> Este programa es software libre; puede redistribuirlo y/o modificarlo bajo los términos de la GPL v2.0 o posterior (consulte el archivo COPYING).