Provided by: po4a_0.55-1_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 á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, 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
           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».

       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» (justificar) o «W»
           (no justificar) 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.

       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.

             * Etiquetas enumeradas en B<break> se ajustan a I<w> o I<W> según la opción <wrap>.
             * Etiquetas enumeradas en B<inline> se ajustan a I<i>.
             * Etiquetas enumeradas en B<placeholder> se ajustan a I<p>.
             * Etiquetas enumeradas en B<untranslated> no se ven afectadas por ninguna de estas opciones.

           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 traducible 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 traducido.

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