Provided by: po4a_0.41-1ubuntu1_all bug

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

       po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm).

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).