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.
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),
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.
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.
- 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).
- 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.
- 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($$)".
- 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»).
- 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?)
Locale::Po4a::TransTractor(3pm),
po4a(7)
Jordi Vilalta <[email protected]>
Nicolas François <[email protected]>
Jordi Vilalta <[email protected]>
Omar Campagne <[email protected]>
Copyright © 2004 Jordi Vilalta <[email protected]>
Copyright © 2008-2009 Nicolas François <[email protected]>
Esto es software libre; puede redistribuirlo y/o modificarlo bajo las
condiciones de la licencia GPL (consulte el fichero COPYING).