LOCALE::PO4A::TRANSTRACTOR.3PM(1)          User Contributed Perl Documentation


NOMBRE
       Locale::Po4a::TransTractor - Trans(lator ex)tractor generico (traductor
       extractor).

DESCRIPCION
       El objetivo del proyecto po4a (<<PO for anything>>, PO para todo) es
       facilitar la traduccion (y mas interesante, el mantenimiento de las
       traducciones) usando las herramientas de gettext en ambitos donde no
       previstos, como la documentacion.

       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 traduccion en el documento de
       salida.

       Mas formalmente, toma los siguientes parametros como entrada:

       - un documento a traducir;

       - un fichero PO que contiene las traducciones a usar.

       Como salida produce:

       - otro fichero PO, resultado de la extraccion de 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 fichero PO suministrado en la entrada.

       Aqui tiene una representacion grafica:

          Documento de entrada -\                         /---> Documento de salida
                                 \                       /         (traducido)
                                  +-> funcion parse() --+
                                 /                        \
          PO de entrada --------/                          \---> PO de salida
                                                                   (extraido)

FUNCIONES QUE SU ANALIZADOR DEBERIA IMPLEMENTAR
       parse()
           Aqui es donde se hace todo el trabajo: el analisis de los
           documentos de entrada, la generacion de la salida, y la extraccion
           de las cadenas traducibles. Es realmente simple usando las
           funciones presentadas en la seccion FUNCIONES INTERNAS mas abajo.
           Consulte la SINOPSIS, que presenta un ejemplo.

           Esta funcion es invocada por la funcion <<process()>> a
           continuacion, pero si elije usar la funcion <<new()>>, y anadir
           contenido manualmente a su documento, debera invocar esta funcion
           manualmente.

       docheader()
           Esta funcion devuelve la cabecera que deberiamos anadir al
           documento creado, tratada de forma que sea un comentario para el
           lenguaje destino. Para ver las ventajas de esto, consulte la
           seccion Educar a los programadores sobre las traducciones, en
           po4a(7).

SINOPSIS
       El siguiente ejemplo analiza una lista de parrafos que empiezan con
       <<<p>>>. Para simplificar, suponemos que el documento esta
       correctamente formateado, es decir, que solo hay presentes etiquetas
       '<p>', y que esta etiqueta esta justo al principio de cada parrafo.

        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 linea actual a la entrada,
                      # y pon el parrafo construido en la salida.
                      $self->unshiftline($line,$lref);

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

                      #   - Ponemos en la salida la etiqueta inicial (sin traducir) y el
                      #     resto del parrafo (traducido)
                      $self>pushline(  "<p>"
                                          . $self->translate($paragraph,$parraref)
                                          );

                      next PARAGRAPH;
                  } else {
                      # Anadir al parrafo.
                      $paragraph .= $line;
                      $pararef = $lref unless(length($pararef));
                  }

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

       Una vez haya implementado la funcion de analisis, ya puede usar su
       clase de documento usando la interfaz publica presentada en la
       siguiente seccion.

INTERFAZ PUBLICA para scripts que usen su analizador
   Constructor
       process(%)
           Esta funcion puede hacer todo lo que quiera hacer con un documento
           po4a en una invocacion:. Sus argumentos deben estar empaquetados
           como una tabla de elementos asociativos (<<hash>>). ACCIONES:

           a. Lee todos los ficheros PO especificados en <<po_in_name>>

           b. Lee todos los documentos originales especificado en
              <<file_in_name>>

           c. Analiza el documento

           d. Lee y aplica todos los apendices especificados

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

           f. Escribe el fichero PO extraido en <<po_out_name>> (si se da)

           ARGUMENTOS, aparte de los aceptados por <<new()>> (con el tipo
           esperado):

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

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

           file_out_name ($)
               Nombre del fichero donde se debe escribir el documento de
               salida.

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

           po_in_name (@)
               Lista de los nombres de ficheros de los que se deben leer los
               ficheros PO de entrada, y que contienen la traduccion que se
               usara para traducir el documento.

           po_out_name ($)
               Nombre de fichero en el que se debe escribir el fichero PO de
               salida, el cual contendra las cadenas extraidas del documento
               de entrada.

           addendum (@)
               Lista de los nombres de los ficheros de los que se deben leer
               los apendices.

           addendum_charset ($)
               El juego de caracteres para los apendices.

       new(%)
           Crea un nuevo documento po4a. Las opciones aceptadas (en la tabla
           <<hash>> pasada como parametro):

           verbose ($)
               Configura el nivel de verbosidad.

           debug ($)
               Configura la depuracion.

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

               El valor negativo significa no ajustar las lineas en absoluto.

           El archivo Po subyacente tambien acepta las siguientes opciones:
           porefs, copyright-holder, msgid-bugs-address, package-name,
           package-version, wrap-po.

   Manipulacion de ficheros de documentos
       read($$$)
           Add another input document data at the end of the existing array
           "@{$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)

           El array "@{$self->{TT}{doc_in}}" contiene estos datos de
           documentos de entrada como un array de cadenas con significados
           alternos.
            * La cadena $textline que contiene cada linea de los datos de
           texto de entrada.
            * La cadena "$filename:$linenum" que contiene su ubicacion, y se
           denomina
              "referencia" ("linenum" comienza con 1).

           Cabe destacar que esto no analiza nada. Debe usar la funcion
           <<parse()>> cuando haya terminado de cargar los ficheros de entrada
           en el documento.

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

           Estos datos de documentos traducidos se proporcionan por:
            * "$self->docheader()" que contiene el texto de cabecera de la
           extension, y
            * "@{$self->{TT}{doc_out}}" que contiene cada linea del texto
           traducido principal de la matriz.

   Manipula ficheros PO
       readpo($)
           Anade el contenido de un fichero (cuyo nombre se introduce como
           argumento) al PO de entrada existente. El contenido anterior no se
           desecha.

       writepo($)
           Escribe el fichero PO extraido al nombre de fichero dado.

       stats()
           Devuelve algunas estadisticas sobre el punto actual de la
           traduccion en curso. Estas no son las mismas estadisticas que las
           que muestra <<msgfmt --statistic>>. Aqui las estadisticas son sobre
           el uso reciente del fichero PO, mientras que msgfmt informa del
           estado del fichero. Esto es un <<wrapper>> (patron de diseno) de la
           funcion 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";

   Manipulacion de apendices
       addendum($)
           Consulte po4a(7) para mas informacion acerca de los apendices, y
           como los traductores deben escribirlos. Para aplicar un apendice a
           un documento traducido, simplemente introduzca su nombre de fichero
           en esta funcion y ya esta ;)

           Esta funcion devuelve un entero no nulo en caso de error.

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados
   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 anade un elemento al matriz como el primer elemento del a matriz.
        * Perl pop devuelve el ultimo elemento de la matriz y lo elimina de la matriz.
        * Perl push anade un elemento a la matriz como el ultimo elemento de la matriz.

       El primer par trata la entrada, mientras que el segundo trata la
       salida. Truco mnemotenico: en la entrada, esta interesado en la primera
       linea, lo que ofrece shift, y en la salida desea insertar el resultado
       al final, como hace push.

       shiftline()
           Esta funcion devuelve la primera linea para su analisis y la
           referencia correspondiente (en forma de matriz), de la matriz
           "@{$self->{TT}{doc_in}}", y elimina estos dos primeros elementos de
           matriz. Aqui, la referencia es proporcionada por la cadena
           "$filename:$linenum".

       unshiftline($$)
           Devuelve la modificacion <<shift>> de la ultima linea <<shifted>>
           del documento de entrada y su referencia a la cabecera de
           "{$self->{TT}{doc_in}}".

       pushline($)
           Inserta una linea nueva al final de "{$self->{TT}{doc_out}}".

       popline()
           Extrae la ultma linea insertada al final de
           "{$self->{TT}{doc_out}}".

   Marcar cadenas como traducibles
       Se proporciona una funcion para tratar el texto que se debe traducir.

       translate($$$)
           Argumentos obligatorios:

           - Una cadena a traducir

           - La referencia a esa cadena (por ejemplo, la posicion en el
             fichero de entrada)

           - El tipo de esta cadena (es decir la descripcion textual de su rol
             estructural; utilizada en Locale::Po4a::Po::gettextization();
             consulte tambien la seccion Gettextizacion: ?como funciona? en
             po4a(7))

           Esta funcion tambien puede tomar algunos argumentos adicionales.
           Estos deben estar en una tabla de elementos asociativos (<<hash>>).
           Por ejemplo:

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

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

           wrapcol
               la columna en la que debemos ajustar (predeterminado: el valor
               de wrapcol especificado durante la creacion de TransTractor o
               76).

               El valor negativo se restara del valor predeterminado.

           comment
               Un comentario adicional para anadir a la entrada.

           Acciones:

           - Inserta la cadena, referencia y escribe en <<po_out>>.

           - Devuelve la traduccion de la cadena (como aparece en <<po_in>>)
             de forma que el analizador pueda construir el fichero
             <<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 paso la opcion de verbosidad durante la creacion del
           TransTractor.

       debug()
           Devuelve si se paso la opcion de depuracion de fallos durante la
           creacion del TransTractor.

       get_in_charset()
           Esta funcion devuelve el conjunto de caracteres que se proporciono
           como conjunto de caracteres maestro

       get_out_charset()
           Esta funcion 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 encontro).

           Utilizara el juego de caracteres especificado en la linea de
           ordenes. Si no se ha especificado, utilizara el juego de caracteres
           del PO de entrada, y si el PO de entrada aun tiene el <<CHARSET>>
           predefinido, devolvera el juego de caracteres del documento de
           entrada, para que no se realice ninguna codificacion.

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 unicos cambios necesarios en la interfaz
       son:

       - tomar una tabla <<hash>> como <<po_in_name>> (una lista por idioma)

       - anadir un argumento a <<translate>> para indicar el idioma de destino

       - hacer una funcion <<pushline_all>>, que haria 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)
                                 });

       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>
        Omar Campagne <ocampagne@gmail.com>

perl v5.38.2                      2024-06-26 LOCALE::PO4A::TRANSTRACTOR.3PM(1)