Provided by: po4a_0.34-2_all bug

NOMBRE

       Locale::Po4a::TransTractor - Generic trans(lator ex)tractor.

DESCRIPCION

       El objetivo del proyecto po4a (po para todo) es facilitar la
       traducciA~Xn (y mA~Xs interesante, el mantenimiento de las
       traducciones) usando las herramientas de gettext en A~Xreas dA~Xnde no
       eran de esperar, como en la documentaciA~Xn.

       Esta clase es la antecesora de todos los analizadores de po4a usados
       para analizar un documento buscando cadenas traducibles, extraerlas a
       un archivo po y reemplazarlas por su traducciA~Xn en el documento de
       salida.

       MA~Xs formalmente, toma los siguientes parA~Xmetros como entrada:

       - un documento a traducir ;

       - un archivo po que contiene las traducciones a usar.

       Como salida produce:

       - otro archivo po, resultante de la extracciA~Xn de las cadenas
         traducibles del documento de entrada ;

       - 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 archivo po suministrado en la entrada.

       AquA~ hay una representaciA~Xn grA~Xfica de A~Xsto:

          Documento de entrada -\                         /---> Documento de salida
                                 \                       /         (traducido)
                                  +-> funciA~Xn parse() --+
                                 /                        \
          po de entrada --------/                          \---> po de salida
                                                                   (extraA~do)

FUNCIONES QUE TU ANALIZADOR DEBE IMPLEMENTAR

       parse()
           AquA~ es dA~Xnde se hace todo el trabajo: el anA~Xlisis de los
           documentos de entrada, la generaciA~Xn de la salida, y la
           extracciA~Xn de las cadenas traducibles. Es realmente simple usando
           las funciones presentadas en la secciA~Xn "FUNCIONES INTERNAS"
           mA~Xs abajo. VA~Xase la sinopsis, que presenta un ejemplo.

           Esta funciA~Xn se llama desde la funciA~Xn process() de abajo, pero
           si elijes usar la funciA~Xn new(), y aA~Xadir contenido manualmente
           a tu documento, deberA~Xs llamar A~Xsta funciA~Xn manualmente.

       docheader()
           Esta funciA~Xn devuelve la cabecera que debemos aA~Xadir al
           documento creado, tratada de forma que sea un comentario para el
           lenguaje destino  Para ver las ventajas de esto, ver la secciA~Xn
           "Educando a los programadores sobre las traducciones", de po4a(7).

SINOPSIS

       The following example parses a list of paragraphs beginning with "<p>".
       For the sake of simplicity, we assume that the document is well
       formatted, i.e. that ’<p>’ tags are the only tags present, and that
       this tag is at the very beginning of each paragraph.

        sub parse {
          my $self = shift;

          PARRAFO: while (1) {
              $my ($parrafo,$parraref)=("","");
              $my $primera=1;
              my ($linea,$lref)=$self->shiftline();
              while (defined($linea)) {
                  if ($linea =~ m/<p>/ && !$primera--; ) {
                      # No es la primera vez que vemos <p>.
                      # Reinsertar la lA~nea actual en la entrada,
                      #  y poner el pA~Xrrafo construido en la salida
                      $self->unshiftline($linea,$lref);

                      # Ahora que tenemos el documento creado, lo traducimos:
                      #   - Eliminamos el tag principal
                      $parrafo =~ s/^<p>//s;

                      #   - ponemos en la salida el tag inicial (sin traducir) y el resto
                      #     del pA~Xrrafo (traducido)
                      $documento->pushline(  "<p>"
                                          . $documento->translate($parrafo,$parraref)
                                          );

                      next PARRAFO;
                  } else {
                      # AA~Xadimos al pA~Xrrafo
                      $parrafo .= $linea;
                      $parraref = $lref unless(length($parraref));
                  }

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

       Una vez hayas implementado la funcion parse, ya puedes usar tu clase de
       documento, usando la interfA~cie presentada en la siguiente secciA~Xn.

INTERFICIE PUBLICA para scripts que usen tu analizador

   Constructor
       process(%)
           Esta funciA~Xn puede hacer todo lo que quiera hacer con un
           documento po4a en una invocaciA~Xn:. Sus parA~Xmetros deben estar
           empaquetados como un hash. ACCIONES:

           a. Lee todos los archivos po especificados en po_in_name

           b. Lee el documento original especificado en file_in_name

           c. Analiza el documento

           d. Lee y aplica todos los apA~Xndices especificados

           e. Escribe el documento traducido en file_out_name (si se da)

           f. Escribe el archivo po extraido en po_out_name (si se da)

           PARAMETROS, a parte de los aceptados por new() (con el tipo
           esperado):

           file_in_name (@)
               Lista de los nombres de archivos de los que se debe leer el
               documento de entrada.

           file_in_charset ($)
               Juego de caracteres usado en el documento de entrada (si no se
               especifica, se intentarA~X detectarlo del documento de entrada)

           file_out_name ($)
               Nombre del archivo donde se debe grabar el documento de salida.

           file_out_charset ($)
               Juego de caracteres usado en el documento de salida (si no se
               especifica, se usarA~X el juego de caracteres del fichero po).

           po_in_name (@)
               Lista de los nombres de ficheros de los que se deben leer los
               archivos po de entrada, los cuales contienen la traducciA~Xn
               que se va a usar para traducir el documento.

           po_out_name ($)
               Nombre de archivo en el que se debe escribir el archivo po de
               salida, el cual contendrA~X las cadenas extraA~das del
               documento de entrada.

           addendum (@)
               List of filenames where we should read the addenda from.

           addendum_charset ($)
               Juego de caracteres del apA~Xndice.

       new(%)
           Crea un nuevo documento Po4a. Las opciones aceptadas (que deben
           estar en un hash):

           verbose ($)
               Ajusta el nivel de informaciA~Xn extra.

           debug ($)
               Ajusta la depuraciA~Xn.

   manipulando archivos de documento
       read($)
           AA~Xade otro documento de entrada al final del existente
           actualmente. El parA~Xmetro es el nombre del archivo a leer.

           Cabe destacar que esto no analiza nada. Debes usar la funciA~Xn
           parse() cuando hayas terminado de cargar los archivos de entrada en
           el documento.

       write($)
           Escribe el documento traducido al fichero dado.

   Manipulando archivos po
       readpo($)
           AA~Xade el contenido del archivo (cuyo nombre es pasado como
           parA~Xmetro) al po de entrada existente. El contenido anterior no
           se desecha.

       writepo($)
           Escribe el archivo po extraido al nombre de archivo dado.

       stats()
           Devuelve algunas estadA~sticas sobre la traducciA~Xn hecha hasta
           ahora. Estas no son las mismas estadA~sticas que las que muestra
           msgfmt --statistic. AquA~ las estadA~sticas son sobre el uso
           reciente del archivo po, mientras que msgfmt informa del estado del
           archivo. Esto es una envoltura de la funciA~Xn
           Locale::Po4a::Po::stats_get aplicada al archivo 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";

   Manipulando apA~Xndices
       addendum($)
           Consulte po4a(7) para mA~Xs informaciA~Xn sobre quA~X son los
           apA~Xndices, y cA~Xmo los traductores deben escribirlos. Para
           aplicar un apA~Xndice a un documento traducido, simplemente pasa su
           nombre de archivo a A~Xsta funciA~Xn y ya estA~X ;)

           Esta funciA~Xn devuelve un entero no nulo en caso de error.

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

   Obteniendo entrada, proporcionando salida
       Para obtener la entrada y devolver la salida se proporcionan cuatro
       funciones. Son muy parecidas a shift/unshift y push/pop. El primer par
       trata la entrada, mientras que el segunro trata la salida. MnemA~Xnica:
       en la entrada, estA~Xs interesado en la primera lA~nea, lo que obtiene
       shift, y en la salida se quiere insertar el resultado al final, como
       hace push.

       shiftline()
           Esta funciA~Xn devuelve la prA~Xxima lA~nea de doc_in para ser
           analizada, y su referencia (empaquetado como un array).

       unshiftline($$)
           Devuelve una lA~nea del documento de entrada y su referencia.

       pushline($)
           Inserta una nueva lA~nea al doc_out.

       popline()
           Extrae la A~Xltima linea insertada al doc_out.

   Marcando cadenas como traducibles
       Se proporcionan una funciA~Xn para tratar el texto que debe ser
       traducido.

       translate($$$)
           ParA~Xmetros obligatorios:

           - Una cadena a traducir

           - La referencia a esa cadena (p.e., la posiciA~Xn en el archivo de
             entrada)

           - El tipo de A~Xsta cadena (p.e., la descripciA~Xn textual de la
             estructura ; utilizada en Locale::Po4a::Po::gettextization() ;
             ver tambiA~Xn la secciA~Xn GettextizaciA~Xn: cA~Xmo funciona?) en
             po4a(7).

           Esta funciA~Xn tambiA~Xn puede tomar algunos parA~Xmetros extra.
           Estos deben estar en un hash. Por ejemplo:

             $self->translate("cadena","referencia","tipo",
                              'wrap' => 1);

           wrap
               booleano indicando si podemos considerar que los espacios en
               blanco de la cadena son despreciables. En ese caso, la
               funciA~Xn canoniza la cadena antes de buscar su traducciA~Xn o
               extraerla, y justifica la traducciA~Xn.

           wrapcol
               La columna en la que se debe hacer el salto de lA~nea (defecto:
               76).

           comment
               Un comentario extra para aA~Xadir a la entrada.

           Acciones:

           - Inserta la cadena, referencia y tipo a po_out.

           - Devuelve la traducciA~Xn de la cadena (encontrada en po_in) de
             forma que el analizador pueda construir doc_out.

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

   Funciones varias
       verbose()
           Devuelve si se pasA~X la opciA~Xn verbose durante la creaciA~Xn del
           TransTractor.

       debug()
           Devuelve si se pasA~X la opciA~Xn debug durante la creaciA~Xn del
           TransTractor.

       detected_charset($)
           Esto informa al TransTractor que se ha detectado un nuevo juego de
           caracteres (el primer parA~Xmetro) en el documento de entrada.
           Habitualmente se puede encontrar en la cabecera del documento. Solo
           permanecerA~X el primer juego de carA~Xcteres, ya venga de los
           parA~Xmetros de process() o sea detectado del documento.

       get_out_charset()
           Esta funciA~Xn devuelve el juego de caracteres que se debe usar en
           el documento de salida (normalmente es util para sustituir el juego
           de caracteres detectado en el documento de entrada donde se haya
           encontrado).

           UtilizarA~X el juego de caracteres especificado en la linea de
           comandos. Si no se ha especificado, utilizarA~X el juego de
           caracteres del po de entrada, y si el po de entrada aA~Xn tiene el
           "CHARSET" por defecto, devolverA~X el juego de caracteres del
           documento de entrada, para que no se realice ninguna
           codificaciA~Xn.

       recode_skipped_text($)
           Esta funciA~Xn devuelve el texto pasado como parA~Xmetro
           recodificado, desde el juego de caracteres del documento de entrada
           al del documento de salida. No es nececsario cuando se traduzca una
           cadena (translate() ya lo recodifica por su cuenta), pero sA~ lo es
           cuando se salta alguna cadena del documento de entrada y quiere
           mantener la consistencia del documento de salida con la
           codificaciA~Xn global.

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 los archivos .desktop.

       Para tratar este problema, los A~Xnicos cambios necesarios en la
       interfA~cie son:

       - take a hash as po_in_name (a list per language)

       - aA~Xadir un parA~Xmetro a translate para indicar el idioma destino

       - hacer una funciA~Xn pushline_all, que harA~a un pushline de su
         contenido para todos los idiomas, usando una sintaxi parecida al map:

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

       Ya veremos si es suficiente ;)

AUTORES

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

TRADUCCION

        Jordi Vilalta <jvprat@gmail.com>