blib::man::TransTractor(3pm)

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

DESCRIPCION
El objetivo del proyecto po4a (po para todo) es facilitar la traduccion (y mas interesante, el mantenimiento de las traducciones) usando las herramientas de gettext en areas donde no eran de esperar, como en la documentacion.

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

Mas formalmente, toma los siguientes parametros como entrada:

-   un documento a traducir ;

-   un archivo po que contiene las traducciones a usar.

Como salida produce:

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

Aqui hay una representacion grafica de esto:

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

FUNCIONES QUE TU ANALIZADOR DEBE 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. Vease la sinopsis, que presenta un ejemplo.

    Esta funcion se llama desde la funcion process() de abajo, pero si elijes usar la funcion new(), y an~adir contenido manualmente a tu documento, deberas llamar esta funcion manualmente.

docheader()
    Esta funcion devuelve la cabecera que debemos an~adir al documento creado, tratada de forma que sea un comentario para el lenguaje destino Para ver las ventajas de esto, ver la seccion "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 linea actual en la entrada,
               #  y poner el parrafo 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 parrafo (traducido)
               $documento->pushline(  "<p>"
                                   . $documento->translate($parrafo,$parraref)
                                   );

               next PARRAFO;
           } else {
               # An~adimos al parrafo
               $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 interficie presentada en la siguiente seccion.

INTERFICIE PUBLICA para scripts que usen tu analizador

  Constructor

process(%)
    Esta funcion puede hacer todo lo que quiera hacer con un documento po4a en una invocacion:. Sus parametros 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 apendices 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 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 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 traduccion 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 las cadenas extraidas del documento de entrada.

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

    addendum_charset ($)
        Juego de caracteres del apendice.

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

    verbose ($)
        Ajusta el nivel de informacion extra.

    debug ($)
        Ajusta la depuracion.

  manipulando archivos de documento

read($)
    An~ade otro documento de entrada al final del existente actualmente. El parametro es el nombre del archivo a leer.

    Cabe destacar que esto no analiza nada. Debes usar la funcion 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($)
    An~ade el contenido del archivo (cuyo nombre es pasado como parametro) 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 estadisticas sobre la traduccion hecha hasta ahora. Estas no son las mismas estadisticas que las que muestra msgfmt --statistic. Aqui las estadisticas son sobre el uso reciente del archivo po, mientras que msgfmt informa del estado del archivo. Esto es una envoltura de la funcion 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 apendices

addendum($)
    Consulte po4a(7) para mas informacion sobre que son los apendices, y como los traductores deben escribirlos. Para aplicar un apendice a un documento traducido, simplemente pasa su nombre de archivo a esta funcion y ya esta ;)

    Esta funcion 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. Mnemonica: en la entrada, estas interesado en la primera linea, lo que obtiene shift, y en la salida se quiere insertar el resultado al final, como hace push.

shiftline()
    Esta funcion devuelve la proxima linea de doc_in para ser analizada, y su referencia (empaquetado como un array).

unshiftline($$)
    Devuelve una linea del documento de entrada y su referencia.

pushline($)
    Inserta una nueva linea al doc_out.

popline()
    Extrae la ultima linea insertada al doc_out.

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

translate($$$)
    Parametros obligatorios:

    -   Una cadena a traducir

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

    -   El tipo de esta cadena (p.e., la descripcion textual de la estructura ; utilizada en Locale::Po4a::Po::gettextization() ; ver tambien la seccion Gettextizacion: como funciona?) en po4a(7).

    Esta funcion tambien puede tomar algunos parametros 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 funcion canoniza la cadena antes de buscar su traduccion o extraerla, y justifica la traduccion.

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

    comment
        Un comentario extra para an~adir a la entrada.

    Acciones:

    -   Inserta la cadena, referencia y tipo a po_out.

    -   Devuelve la traduccion 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 paso la opcion verbose durante la creacion del TransTractor.

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

detected_charset($)
    Esto informa al TransTractor que se ha detectado un nuevo juego de caracteres (el primer parametro) en el documento de entrada. Habitualmente se puede encontrar en la cabecera del documento. Solo permanecera el primer juego de caracteres, ya venga de los parametros de process() o sea detectado del documento.

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 haya encontrado).

    Utilizara el juego de caracteres especificado en la linea de comandos. Si no se ha especificado, utilizara el juego de caracteres del po de entrada, y si el po de entrada aun tiene el "CHARSET" por defecto, devolvera el juego de caracteres del documento de entrada, para que no se realice ninguna codificacion.

recode_skipped_text($)
    Esta funcion devuelve el texto pasado como parametro 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 si lo es cuando se salta alguna cadena del documento de entrada y quiere mantener la consistencia del documento de salida con la codificacion 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 unicos cambios necesarios en la interficie son:

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

-   an~adir un parametro a translate para indicar el idioma destino

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