
        *****************************************************
        *           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::TransTractor - Trans(lator ex)tractor genérico (traductor extractor).

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

Esta clase es la antecesora de todos los analizadores de po4a usados para analizar un documento buscando cadenas traducibles, extraerlas a un fichero PO y reemplazarlas por su traducción en el documento de salida.

Más formalmente, toma los siguientes parámetros como entrada:

=over 2

=item -

un documento a traducir;

=item -

un fichero PO que contiene las traducciones a usar.

=back

Como salida produce:

=over 2

=item -

otro fichero PO, resultado de la extracción de cadenas traducibles del documento de entrada;

=item -

un documento traducido, con la misma estructura que el de la entrada, pero con todas las cadenas traducibles reemplazadas por las traducciones encontradas en el fichero PO suministrado en la entrada.

=back

Aquí tiene una representación gráfica:

   Documento de entrada -\                         /---> Documento de salida
                          \                       /         (traducido)
                           +-> función parse() --+
                          /                        \
   PO de entrada --------/                          \---> PO de salida
                                                            (extraído)

=head1 FUNCIONES QUE SU ANALIZADOR DEBERÍA IMPLEMENTAR

=over 4

=item parse()

Aquí es dónde se hace todo el trabajo: el análisis de los documentos de entrada, la generación de la salida, y la extracción de las cadenas traducibles. Es realmente simple usando las funciones presentadas en la sección B<FUNCIONES INTERNAS> más abajo. Consulte la B<SINOPSIS>, que presenta un ejemplo.

Esta función es invocada por la función «process()» a continuación, pero si elije usar la función «new()», y añadir contenido manualmente a su documento, deberá invocar ésta función manualmente.

=item docheader()

Esta función devuelve la cabecera que deberíamos añadir al documento creado, tratada de forma que sea un comentario para el lenguaje destino. Para ver las ventajas de esto, consulte la sección B<Educar a los programadores sobre las traducciones>, en L<po4a(7)|po4a.7>.

=back

=head1 SINOPSIS

El siguiente ejemplo analiza una lista de párrafos que empiezan con «<p>». Para simplificar, suponemos que el documento está correctamente formateado, es decir, que sólo hay presentes etiquetas '<p>', y que esta etiqueta está justo al principio de cada párrafo.

 sub parse {
   my $self = shift;

   PARAGRAPH: while (1) {
       my ($paragraph,$pararef)=("","");
       my $first=1;
       my ($line,$lref)=$self->shiftline();
       while (defined($line)) {
           if ($line =~ m/<p>/ && !$first--; ) {
               # No es la primera vez que vemos <p>.
               # Devuelve la línea actual a la entrada,
               # y pon el párrafo construido en la salida.
               $self->unshiftline($line,$lref);

               # Ahora que tenemos el documento creado, lo traducimos:
               #   - Eliminamos la etiqueta inicial
               $paragraph =~ s/^<p>//s;

               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Añadir al párrafo.
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reiniciar el bucle
           ($line,$lref)=$self->shiftline();
       }
¿       # ¿No se obtuvo una línea definida? Fin del fichero de entrada.
       return;
   }
 }

Una vez haya implementado la función de análisis, ya puede usar su clase de documento usando la interfaz pública presentada en la siguiente sección.

=head1 INTERFAZ PÚBLICA para scripts que usen su analizador

=head2 Constructor

=over 4

=item process(%)

Esta función puede hacer todo lo que quiera hacer con un documento po4a en una invocación:. Sus argumentos deben estar empaquetados como una tabla de elementos asociativos («hash»). ACCIONES:

=over 3

=item a.

Lee todos los ficheros PO especificados en «po_in_name»

=item b.

Lee todos los documentos originales especificado en «file_in_name»

=item c.

Analiza el documento

=item d.

Lee y aplica todos los apéndices especificados

=item e.

Escribe el documento traducido en «file_out_name» (si se da)

=item f.

Escribe el fichero PO extraído en «po_out_name» (si se da)

=back

ARGUMENTOS, aparte de los aceptados por «new()» (con el tipo esperado):

=over 4

=item file_in_name (@)

Lista de los nombres de ficheros de los que se debe leer el documento de entrada.

=item file_in_charset ($)

El juego de caracteres usado en el documento de entrada (si no se especifica, se intentará detectar del documento de entrada).

=item file_out_name ($)

Nombre del fichero donde se debe escribir el documento de salida.

=item file_out_charset ($)

El juego de caracteres usado en el documento de salida (si no se especifica, se usará el juego de caracteres del fichero PO).

=item po_in_name (@)

Lista de los nombres de ficheros de los que se deben leer los ficheros PO de entrada, y que contienen la traducción que se usará para traducir el documento.

=item po_out_name ($)

Nombre de fichero en el que se debe escribir el fichero PO de salida, el cual contendrá las cadenas extraídas del documento de entrada.

=item addendum (@)

Lista de los nombres de los ficheros de los que se deben leer los apéndices.

=item addendum_charset ($)

El juego de caracteres para los apéndices.

=back

=item new(%)

Create a new po4a document. Accepted options (in the hash passed as a parameter):

=over 4

=item verbose ($)

Configura el nivel de verbosidad.

=item debug ($)

Configura la depuración.

=back

=back

=head2 Manipulación de ficheros de documentos

=over 4

=item read($$)

Add another input document data at the end of the existing array C<< @{$self->{TT}{doc_in}} >>. The argument is the filename to read. If a second argument is provided, it is the filename to use in the references.

This array C<< @{$self->{TT}{doc_in}} >> holds this input document data as an
array of strings with alternating meanings.
 * The string C<$textline> holding each line of the input text data.
 * The string C<< $filename:$linenum >> holding its location and called as
   "reference" (C<linenum> starts with 1).

Cabe destacar que esto no analiza nada. Debe usar la función «parse()» cuando haya terminado de cargar los ficheros de entrada en el documento.

=item write($)

Escribe el documento traducido al fichero dado.

Estos datos de documentos traducidos se proporcionan por:
 * C<< $self->docheader() >> que contiene el texto de cabecera de la extensión, y
 * C<< @{$self->{TT}{doc_out}} >> que contiene cada línea del texto traducido principal de la matriz.

=back

=head2 Manipula ficheros PO

=over 4

=item readpo($)

Añade el contenido de un fichero (cuyo nombre se introduce como argumento) al PO de entrada existente. El contenido anterior no se desecha.

=item writepo($)

Escribe el fichero PO extraído al nombre de fichero dado.

=item stats()

Devuelve algunas estadísticas sobre el punto actual de la traducción en curso. Estas no son las mismas estadísticas que las que muestra «msgfmt --statistic». Aquí las estadísticas son sobre el uso reciente del fichero PO, mientras que msgfmt informa del estado del fichero. Esto es un «wrapper» (patrón de diseño) de la función Locale::Po4a::Po::stats_get aplicada al fichero PO de entrada. Ejemplo de uso:

    [uso normal del documento po4a...]

    ($porcentaje,$aciertos,$solicitudes) = $documento->stats();
    print "Se han encontrado traducciones para el $porcentaje\%  ($aciertos de $solicitudes) de cadenas.\n";

=item is_po_uptodate()

Devuelve ($uptodate, $diagnostic) donde $uptodate representa su el po de entrada y el po de salida coinciden (en caso contrario, significa que el se debería actualizar el po de entrada) y $diagnostic es una cadena que detalla porqué el fichero po no está actualizado, de ser así.

=back

=head2 Manipulación de apéndices

=over 4

=item addendum($)

Consulte L<po4a(7)|po4a.7> para más información acerca de los apéndices, y cómo los traductores deben escribirlos. Para aplicar un apéndice a un documento traducido, simplemente introduzca su nombre de fichero en ésta función y ya está ;)

Esta función devuelve un entero no nulo en caso de error.

=back

=head1 FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

=head2 Obtener entrada, proporcionar salida

Se proporcionan cuatro funciones para obtener la entrada y salida de vuelta. Son muy similares a shift/unshift y push/pop de Perl.

 * Perl shift devuelve el primer elemento de matriz y lo elimina de la matriz.
 * Perl unshift añade un elemento al matriz como el primer elemento del a matriz.
 * Perl pop devuelve el último elemento de la matriz y lo elimina de la matriz.
 * Perl push añade un elemento a la matriz como el último elemento de la matriz.

El primer par trata la entrada, mientras que el segundo trata la salida. Truco mnemoténico: en la entrada, está interesado en la primera línea, lo que ofrece shift, y en la salida desea insertar el resultado al final, como hace push.

=over 4

=item shiftline()

Esta función devuelve la primera línea para su análisis y la referencia correspondiente (en forma de matriz), de la matriz C<< @{$self->{TT}{doc_in}} >>, y elimina estos dos primeros elementos de matriz. Aquí, la referencia es proporcionada por la cadena C<< $filename:$linenum >>.

=item unshiftline($$)

Devuelve la modificación «shift» de la última línea «shifted» del documento de entrada y su referencia a la cabecera de C<< {$self->{TT}{doc_in}} >>.

=item pushline($)

Inserta una línea nueva al final de C<< {$self->{TT}{doc_out}} >>.

=item popline()

Extrae la últma línea insertada al final de C<< {$self->{TT}{doc_out}} >>.

=back

=head2 Marcar cadenas como traducibles

Se proporciona una función para tratar el texto que se debe traducir.

=over 4

=item translate($$$)

Argumentos obligatorios:

=over 2

=item -

Una cadena a traducir

=item -

La referencia a esa cadena (por ejemplo, la posición en el fichero de entrada)

=item -

El tipo de esta cadena (es decir la descripción textual de su rol estructural; utilizada en Locale::Po4a::Po::gettextization(); consulte también la sección B<Gettextización: ¿cómo funciona?> en L<po4a(7)|po4a.7>)

=back

Esta función también puede tomar algunos argumentos adicionales. Estos deben estar en una tabla de elementos asociativos («hash»). Por ejemplo:

  $self->translate("string","ref","type",
                   'wrap' => 1);

=over 

=item B<wrap>

Booleano que indica si podemos considerar que los espacios en blanco de la cadena carecen de importancia. En ese caso, la función canoniza la cadena antes de buscar su traducción o extraerla, y justifica la traducción.

=item B<wrapcol>

La columna en la que se debe hacer el salto de línea (por omisión: 76).

=item B<comment>

Un comentario adicional para añadir a la entrada.

=back

Acciones:

=over 2

=item -

Inserta la cadena, referencia y escribe en «po_out».

=item -

Devuelve la traducción de la cadena (como aparece en «po_in») de forma que el analizador pueda construir el fichero «doc_out».

=item -

Trata los juegos de caracteres para recodificar las cadenas antes de enviarlas a «po_out» y antes de devolver las traducciones.

=back

=back

=head2 Funciones varias

=over 4

=item verbose()

Devuelve si se pasó la opción de verbosidad durante la creación del TransTractor.

=item debug()

Devuelve si se pasó la opción de depuración de fallos durante la creación del TransTractor.

=item detected_charset($)

Esto informa al TransTractor que se ha detectado un nuevo juego de caracteres (el primer argumento) en el documento de entrada. Habitualmente se puede encontrar en la cabecera del documento. Solo permanecerá el primer juego de caracteres, ya venga de los argumentos de «process()» o si se detectó en el documento.

=item get_out_charset()

Esta función devuelve el juego de caracteres que se debe usar en el documento de salida (normalmente es útil para sustituir el juego de caracteres detectado en el documento de entrada donde se encontró).

Utilizará el juego de caracteres especificado en la linea de órdenes. Si no se ha especificado, utilizará el juego de caracteres del PO de entrada, y si el PO de entrada aún tiene el «CHARSET» predefinido, devolverá el juego de caracteres del documento de entrada, para que no se realice ninguna codificación.

=item recode_skipped_text($)

Esta función devuelve el texto recodificado introducido como argumento, desde el juego de caracteres del documento de entrada al del documento de salida. No es necesario cuando se traduzca una cadena (translate() ya lo recodifica por su cuenta), pero sí lo es cuando se salta alguna cadena del documento de entrada y quiere mantener la consistencia del documento de salida con la codificación global.

=back

=head1 DIRECCIONES FUTURAS

Una deficiencia del TransTractor actual es que no puede tratar documentos traducidos que contengan todos los idiomas, como las plantillas de debconf, o en los ficheros «.desktop».

Para tratar este problema, los únicos cambios necesarios en la interfaz son:

=over 2

=item -

tomar una tabla «hash» como «po_in_name» (una lista por idioma)

=item -

añadir un argumento a «translate» para indicar el idioma de destino

=item -

hacer una función «pushline_all», que haría un «pushline» de su contenido para todos los idiomas, usando una sintaxis parecida a «map»:

    $self->pushline_all({ "Description[".$langcode."]=".
                          $self->translate($line,$ref,$langcode)
                        });

=back

Ya veremos si es suficiente ;)

=head1 AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>


=head1 TRADUCCION

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

