
        *****************************************************
        *           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:

   Input document --\                             /---> Output document
                     \                           /       (translated)
                      +-> parse() function -----+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                         (extracted)

=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--; ) {
               # Not the first time we see <p>.
               # Reput the current line in input,
               #  and put the built paragraph to output
               $self->unshiftline($line,$lref);

               # Now that the document is formed, translate it:
               #   - Remove the leading tag
               $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 {
               # Append to the paragraph
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinit the loop
           ($line,$lref)=$self->shiftline();
       }
       # Did not get a defined line? End of input file.
       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 ($)

Conjunto de caracteres utilizado en el documento de entrada (si no se
especifica, se utiliza UTF-8).

=item file_out_name ($)

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

=item file_out_charset ($)

Conjunto de caracteres utilizado en el documento de salida (si no se
especifica, se utiliza UTF-8).

=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(%)

Crea un nuevo documento po4a. Las opciones aceptadas (en la tabla «hash»
pasada como parámetro):

=over 4

=item verbose ($)

Configura el nivel de verbosidad.

=item debug ($)

Configura la depuración.

=item wrapcol ($)

Columna a la que ajustar el texto de salida (predeterminado: 76).

El valor negativo significa no ajustar las líneas en absoluto.

=back

El archivo Po subyacente también acepta las siguientes opciones: B<porefs>,
B<copyright-holder>, B<msgid-bugs-address>, B<package-name>,
B<package-version>, B<wrap-po>.

=back

=head2 Manipulación de ficheros de documentos

=over 4

=item leer($$$)

Agregue otros datos del documento de entrada al final de la matriz existente
C<< @{$self->{TT}{doc_in}} >>.

This function takes two mandatory arguments and an optional one.
 * The filename to read on disk;
 * The name to use as filename when building the reference in the PO file;
 * The charset to use to read that file (UTF-8 by default)

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.

This translated document data are provided by:
 * C<< $self->docheader() >> holding the header text for the plugin, and
 * C<< @{$self->{TT}{doc_out}} >> holding each line of the main translated text in the array.

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

    [normal use of the po4a document...]

    ($percent,$hit,$queries) = $document->stats();
    print "We found translations for $percent\%  ($hit from $queries) of strings.\n";

=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 returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

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 debemos ajustar (predeterminado: el valor de B<wrapcol>
especificado durante la creación de TransTractor o 76).

El valor negativo se restará del valor predeterminado.

=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 get_in_charset()

Esta función devuelve el conjunto de caracteres que se proporcionó como
conjunto de caracteres maestro

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

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

