Provided by: po4a_0.23-1_all bug

NOMBRE

       Po4a TransTractor - Trans(lator ex)tractor genérico (traductor
       extractor).

DESCRIPCION

       El objetivo del proyecto po4a (po para todo) es facilitar la traducción
       (y más interesante, el mantenimiento de las traducciones) usando las
       herramientas de gettext en áreas dónde no eran de esperar, como en 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 archivo po y reemplazarlas por su traducción en el documento de
       salida.

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

       - un documento a traducir ;

       - un archivo po que contiene las traducciones a usar.

       Como salida produce:

       - otro archivo po, resultante de la extracción 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.

       Aquí hay una representación gráfica de ésto:

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

FUNCIONES QUE TU ANALIZADOR DEBE IMPLEMENTAR

       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 "FUNCIONES INTERNAS" más abajo.
           Véase la sinopsis, que presenta un ejemplo.

           Esta función se llama desde la función process() de abajo, pero si
           elijes usar la función new(), y añadir contenido manualmente a tu
           documento, deberás llamar ésta función manualmente.

       docheader()
           Esta función devuelve la cabecera que debemos añadir al documento
           creado, tratada de forma que sea un comentario para el lenguaje
           destino  Para ver las ventajas de esto, ver la sección "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 línea actual en la entrada,
                      #  y poner el párrafo 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 párrafo (traducido)
                      $documento->pushline(  "<p>"
                                          . $documento->translate($parrafo,$parraref)
                                          );

                      next PARRAFO;
                  } else {
                      # Añadimos al párrafo
                      $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 interfície presentada en la siguiente sección.

INTERFICIE PUBLICA para scripts que usen tu analizador

       Constructor

       process(%)
           Esta función puede hacer todo lo que quiera hacer con un documento
           po4a en una invocación:. Sus parámetros 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 apéndices 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 intentará 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 usará 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 traducción 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 contendrá las cadenas extraídas del documento
               de entrada.

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

           addendum_charset ($)
               Juego de caracteres del apéndice.

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

           verbose ($)
               Ajusta el nivel de información extra.

           debug ($)
               Ajusta la depuración.

       manipulando archivos de documento

       read($)
           Añade otro documento de entrada al final del existente actualmente.
           El parámetro es el nombre del archivo a leer.

           Cabe destacar que esto no analiza nada. Debes usar la función
           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($)
           Añade el contenido del archivo (cuyo nombre es pasado como
           parámetro) 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 estadísticas sobre la traducción hecha hasta
           ahora. Estas no son las mismas estadísticas que las que muestra
           msgfmt --statistic. Aquí las estadísticas son sobre el uso reciente
           del archivo po, mientras que msgfmt informa del estado del archivo.
           Esto es una envoltura de la función 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 apéndices

       addendum($)
           Consulte po4a(7) para más información sobre qué son los apéndices,
           y cómo los traductores deben escribirlos. Para aplicar un apéndice
           a un documento traducido, simplemente pasa su nombre de archivo a
           ésta función y ya está ;)

           Esta función 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. Mnemónica:
       en la entrada, estás interesado en la primera línea, lo que obtiene
       shift, y en la salida se quiere insertar el resultado al final, como
       hace push.

       shiftline()
           Esta función devuelve la próxima línea de doc_in para ser
           analizada, y su referencia (empaquetado como un array).

       unshiftline($$)
           Devuelve una línea del documento de entrada y su referencia.

       pushline($)
           Inserta una nueva línea al doc_out.

       popline()
           Extrae la última linea insertada al doc_out.

       Marcando cadenas como traducibles

       Se proporcionan una función para tratar el texto que debe ser
       traducido.

       translate($$$)
           Parámetros obligatorios:

           - Una cadena a traducir

           - La referencia a esa cadena (p.e., la posición en el archivo de
             entrada)

           - El tipo de ésta cadena (p.e., la descripción textual de la
             estructura ; utilizada en Locale::Po4a::Po::gettextization() ;
             ver también la sección Gettextizacin: cmo funciona?) en
             po4a(7).

           Esta función también puede tomar algunos parámetros extra. Estos
           deben estar en un hash. Por ejemplo:

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

           wrap
               booleano indicando si podemos considerar que los espacios en
               blanco de la cadena son despreciables. En ese caso, la función
               canoniza la cadena antes de buscar su traducción o extraerla, y
               justifica la traducción.

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

           comment
               Un comentario extra para añadir a la entrada.

           Acciones:

           - Inserta la cadena, referencia y tipo a po_out.

           - Devuelve la traducción 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 pasó la opción verbose durante la creación del
           TransTractor.

       debug()
           Devuelve si se pasó la opción debug durante la creación del
           TransTractor.

       detected_charset($)
           Esto informa al TransTractor que se ha detectado un nuevo juego de
           caracteres (el primer parámetro) en el documento de entrada.
           Habitualmente se puede encontrar en la cabecera del documento. Solo
           permanecerá el primer juego de carácteres, ya venga de los
           parámetros de process() o sea detectado del documento.

       get_out_charset()
           Esta función 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).

           Utilizará el juego de caracteres especificado en la linea de
           comandos. 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" por defecto, devolverá el juego de caracteres del
           documento de entrada, para que no se realice ninguna codificación.

       recode_skipped_text($)
           Esta función devuelve el texto pasado como parámetro 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 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.

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 únicos cambios necesarios en la
       interfície son:

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

       - añadir un parámetro a translate para indicar el idioma destino

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

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

       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>