
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOMBRE

Locale::Po4a::Xml - Convierte documentos XML y derivados desde/a ficheros PO

=head1 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.

=head1 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 B<Escribir módulos
derivados> que encontrará más abajo para una descripción del proceso.

=head1 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:

=over 4

=item B<nostrip>

Evita que se quiten los espacios alrededor de las cadenas extraídas.

=item B<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
B<translated> más abajo.

=item B<unwrap_attributes>

Los atributos se justifican de forma predefinida. Esta opción desactiva el
justificado.

=item B<caseinsensitive>

Permite que las búsquedas de etiqueta y atributos no tengan en cuenta
mayúsculas y minúsculas. Si está definido, tratará E<lt>BooKE<gt>laNG y
E<lt>BOOKE<gt>Lang como E<lt>bookE<gt>lang.

=item B<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

=item B<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.

=item B<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:

=over

=item I<fail>

Éste es el valor predefinido. El módulo cerrará con un mensaje de error.

=item I<warn>

El módulo continuará, mostrando una advertencia.

=item I<silent>

El módulo continuará sin advertencias.

=back

Sea cuidadoso a la hora de usar esta opción. En general, recomendamos
arreglar el fichero de entrada.

=item B<tagsonly>

Nota: Esta opción está obsoleta.

Extrae únicamente las etiquetas especificadas en la opción B<tags>. De no
ser así, extraerá todas las etiquetas excepto las especificadas.

=item B<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.

=item B<addlang>

Cadena que indica la ruta (por ejemplo, E<lt>bbbE<gt>E<lt>aaaE<gt>) 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».

=item B<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 B<ontagerror>.

=item B<tags>

Nota: Esta opción está obsoleta. En lugar de ello, debería usar las opciones
B<translated> y B<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 E<lt>aaaE<gt>, pero puede
juntar algunos (E<lt>bbbE<gt>E<lt>aaaE<gt>) para indicar que el contenido de
la etiqueta E<lt>aaaE<gt> sólo se debe traducir cuando esté dentro de la
etiqueta E<lt>bbbE<gt>.

También puede especificar algunas opciones de etiquetas poniendo algunos
caracteres delante de la jerarquía de etiquetas. Por ejemplo, puede poner
I<w> (ajustar) o I<W> (no ajustar) para hacer caso omiso del comportamiento
predefinido especificado por la opción global B<wrap>.

Ejemplo: WE<lt>chapterE<gt>E<lt>titleE<gt>

=item B<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: E<lt>bbbE<gt>E<lt>aaaE<gt>lang indica
que el atributo «lang» sólo se traducirá cuando esté dentro de la etiqueta
E<lt>aaaE<gt>, y ésta esté dentro de una etiqueta E<lt>bbbE<gt>.

=item B<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.

=item B<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.

=item B<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 B<break>, B<inline> B<placeholder>, o B<customtag>.

=item B<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.

=item B<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.

=item B<break-pi>

Por defecto, las Instrucciones de Procesado (es decir, las etiquetas
C<E<lt>? ... ?E<gt>>) 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.

=item B<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 B<nodefault>.

=item B<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).

=item B<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 B<wrap> y
B<defaulttranslateoption>.

=over

=item I<w>

Las etiquetas deberían traducirse, y se puede justificar el contenido.

=item I<W>

Las etiquetas deberían traducirse, y no se debe justificar el contenido.

=item I<i>

Las etiquetas se deberían traducir como elementos en línea.

=item I<p>

Las etiquetas se deberían traducir como marcadores de posición.

=back

Internamente, el analizador XML solo tiene en cuenta estas cuatro opciones:
I<w> I<W> I<i> I<p>.

* Las etiquetas listadas en B<break> se establecen en I<w> o I<W> en función
de la opción B<wrap>.

* Las etiquetas que aparecen en B<inline> se establecen en I<i>.

* Las etiquetas listadas en B<placeholder> se establecen en I<p>.

* Las etiquetas listadas en B<untranslated> no tienen ninguna de estas
opciones establecidas.

Puede comprobar el comportamiento de parámatro interno real invocando
B<po4a> con la opción B<--debug>.

Ejemplo: WE<lt>chapterE<gt>E<lt>titleE<gt>

Tenga en cuenta que una etiqueta se debe introducir en la cadena de ajuste
de B<translated> o B<untranslated>.

=item B<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<i> y se ajusta I<w> o I<W> según la opción B<wrap>.

=item B<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 B<translated>, y este ajuste solo
es válido para etiquetas traducibles.

=back

=head1 ESCRITURA DE MÓDULOS DERIVADOS

=head2 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 B<_default_inline>, B<_default_break>,
B<_default_placeholder>, B<_default_translated>, B<_default_untranslated> y
B<_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.

=head2 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 L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

=head2 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»):

=over

=item 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.

=item type="atributo"

Significa que la cadena encontrada es el valor de un atributo traducible. La
entrada «atributo» contiene el nombre del atributo.

=back

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.

=head2 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:

=over 4

=item B<beginning>

Especifica el principio de la etiqueta, después de «E<lt>».

=item B<end>

Especifica el final de la etiqueta, antes de «E<gt>».

=item B<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.

=item B<f_breaking>

Es una función que dirá si la siguiente etiqueta rompe o no. Debe definirla
si la opción B<breaking> no lo está.

=item B<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.

=item B<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.

=back

=head1 FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

=head2 TRABAJAR CON ETIQUETAS

=over 4

=item get_path()

Esta función devuelve la ruta hasta la etiqueta actual desde la raíz del
documento, con la forma E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

Puede introducir como argumento una lista adicional de etiquetas (sin
corchetes). Estos elementos de ruta se añaden la final de la ruta actual.

=item 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 E<lt> y finalizada
por E<gt>, y puede contener varias líneas.

Esto funciona con la matriz C<< @{$self->{TT}{doc_in}} >> que contiene los
datos de documento de entrad y su referencia indirecta mediante C<<
$self->shiftline() >> y C<< $self->unshiftline($$) >>.

=item 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 C<< @{$self->{TT}{doc_in}} >> que contiene los
datos de documento de entrad y su referencia indirecta mediante C<<
$self->shiftline() >> y C<< $self->unshiftline($$) >>.

=item get_tag_name(@)

Esta función devuelve el nombre de la etiqueta introducida como argumento,
en la forma de vector devuelta por «extract_tag».

=item 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.

=item 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 C<< @{$self->{TT}{doc_in}} >> que contiene los
datos de documento de entrad y su referencia indirecta mediante C<<
$self->shiftline() >> y C<< $self->unshiftline($$) >>.

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

=back

=head2 TRABAJAR CON ATRIBUTOS

=over 4

=item 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 B<attributes> del
módulo). Devuelve una cadena con la etiqueta traducida.

=back

=head2 TRABAJAR CON CONTENIDO ETIQUETADO

=over 4

=item 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 C<< @{$self->{TT}{doc_in}} >> que contiene los
datos de documento de entrad y su referencia indirecta mediante C<<
$self->shiftline() >> y C<< $self->unshiftline($$) >>.

=back

=head2 TRABAJAR CON LAS OPCIONES DEL MÓDULO

=over 4

=item 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»).

=back

=head2 OBTENER TEXTO DEL DOCUMENTO DE ENTRADA

=over

=item 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:

=over 4

=item B<include>

Esto hace que la lista retornada contenga la cadena buscada

=item B<remove>

Esto elimina el flujo devuelto de la entrada

=item B<unquoted>

Esto asegura que el texto buscado se encuentra fuera de cadenas
entrecomilladas

=item B<regex>

Esto indica que el primer argumento es una expresión regular en lugar de una
cadena sin formato

=back

=item 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.

=item join_lines(@)

Esta función devuelve una cadena simple con el texto de la lista del
argumento (descartando las referencias).

=back

=head1 ESTADO DE ESTE MODULO

Este módulo puede traducir etiquetas y atributos.

=head1 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?)

=head1 VÉASE TAMBIÉN

L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>,
L<po4a(7)|po4a.7>

=head1 AUTORES

 Jordi Vilalta <jvprat@gmail.com>
 Nicolas François <nicolas.francois@centraliens.net>


=head1 TRADUCCION

 Jordi Vilalta <jvprat@gmail.com>
 Omar Campagne <ocampagne@gmail.com>

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