Locale::Po4a::Xml - Convierte documentos XML y derivados desde/a
ficheros PO
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.
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.
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.
Extracts only the specified tags in the tags option.
Otherwise, it will extract all the tags except the ones specified.
- 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
- Boolean indicating whether closing tags are optional (as in HTML). By
default, missing closing tags raise an error handled according to
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>.
You can also specify some tag options by putting some
characters in front of the tag hierarchy. For example, you can put
w (wrap) or W (don't wrap) to override the default
behavior specified by the global wrap option.
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
- By default, Processing Instructions (i.e., "<?
... ?>" tags) are handled as inline tags. Pass this option
if you want the PI to be handled as breaking tag. Note that unprocessed
PHP tags are handled as Processing Instructions by the parser.
- 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.
Internally, the XML parser only cares about these four options:
w W i p.
* Tags listed in break are set to w or W
depending on the wrap option.
* Tags listed in inline are set to i.
* Tags listed in placeholder are set to p.
* Tags listed in untranslated are without any of these
options set.
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.
Please note a translatable inline tag in an untranslated tag
is treated as a translatable breaking tag, i setting is dropped
and w or W is set depending on the wrap option.
- 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.
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.
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á.
- 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.
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($$)".
- 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(@)
- This function handles the translation of the tags' attributes. It receives
the tag without the beginning / end marks, and then it finds the
attributes, and it translates the translatable ones (specified by the
module option attributes). This returns a plain string with the
translated tag.
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
- This denotes that the first argument is a regular expression rather than
an plain string
- 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).
Este módulo puede traducir etiquetas y atributos.
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?)
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
Jordi Vilalta <jvprat@gmail.com>
Omar Campagne <ocampagne@gmail.com>
Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
Copyright © 2008-2009 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).