Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::TransTractor

NOMBRE

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

DESCRIPCIÓN

El objetivo del proyecto po4a («po for all», po para todo) es facilitar la traducción (y más interesante, el mantenimiento de las traducciones) usando las herramientas de gettext en áreas donde 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 fichero 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 fichero po que contiene las traducciones a usar.

Como salida produce:

-

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

Aquí tiene una representación gráfica:

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

FUNCIONES QUE SU 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 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á 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, véase la sección «Educar a los programadores sobre las traducciones», en po4a(7).

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--; ) {
                # No es la primera vez que vemos <p>. 
                # Devuelve la línea actual a la entrada,
                # y pon el párrafo construido en la salida.
                $self->unshiftline($line,$lref);
               
                # Ahora que tenemos el documento creado, lo traducimos:
                #   - Eliminamos el tag principal
                $paragraph =~ s/^<p>//s;
 
                #   - Ponemos en la salida la etiqueta inicial (sin traducir) y el 
                #     resto del párrafo (traducido)
                $self>pushline(  "<p>"
                                    . $document->translate($paragraph,$parraref)
                                    );
 
                next PARAGRAPH;
            } else {
                # Añadir al párrafo.
                $paragraph .= $line;
                $pararef = $lref unless(length($pararef));
            }
 
            # Reiniciar el bucle
            ($line,$lref)=$self->shiftline();
        }
 ¿       # ¿No se obtuvo una línea definida? Fin del fichero de entrada.
        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.

INTERFAZ PÚBLICA para scripts que usen su analizador

Constructor

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 hash. ACCIONES:

a.

Lectura de todos los ficheros po especificados en po_in_name

b.

Lectura del documento original especificado en file_in_name

c.

Análisis del documento

d.

Lectura y aplicación de todos los apéndices especificados

e.

Escribir el documento traducido en file_out_name (si se da)

f.

Escribir 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 ($)

Juego de caracteres usado en el documento de entrada (si no se especifica, se intentará detectar del documento de entrada)

file_out_name ($)

Nombre del fichero 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 ficheros po de entrada, y que contienen la traducción que se usará para traducir el documento.

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.

addendum (@)

Lista de los nombres de los ficheros de los que se deben leer los apéndices.

addendum_charset ($)

Juego de caracteres de los apéndices.

new(%)

Crear un nuevo documento Po4a. Las opciones aceptadas (que deben estar en una tabla hash):

verbose ($)

Configurar el nivel de verbosidad.

debug ($)

Configurar la depuración.

Manipular ficheros de documentos.

read($)

Añadir otro documento de entrada al final del ya existente. El argumento es el nombre del fichero a leer.

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.

write($)

Escribir el documento traducido al fichero dado.

Manipular ficheros po

readpo($)

Añadir el contenido de un fichero (cuyo nombre se introduce como argumento) al po de entrada existente. El contenido anterior no se desecha.

writepo($)

Escribir el fichero po extraido al nombre de fichero dado.

stats()

Devolver algunas estadísticas sobre el punto actual de la traducción en curso ahora. 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:

     [uso normal del documento po4a...]
 
     ($porcentaje,$aciertos,$solicitudes) = $documento->stats();
     print "Se han encontrado traducciones para el $porcentaje\%  ($aciertos de $solicitudes) de cadenas.\n";
 
 

Manipular apéndices

addendum($)

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

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

Obtener entrada, proporcionar 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 segundo trata la salida. Mnemónica: en la entrada, está 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 su análisis, y su referencia (empaquetado como un vector).

unshiftline($$)

Devolver una línea del documento de entrada y su referencia.

pushline($)

Insertar una nueva línea al doc_out.

popline()

Extraer la última linea insertada al doc_out.

Marcar cadenas como traducibles

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

translate($$$)

Argumentos obligatorios:

-

Una cadena a traducir

-

La referencia a esa cadena (p.ej., la posición en el fichero de entrada).

-

El tipo de ésta cadena (p.ej., la descripción textual de la estructura ; utilizada en Locale::Po4a::Po::gettextization(); véase también la sección Gettextización: ¿cómo funciona?) en po4a(7).

Esta función también puede tomar algunos argumentos adicionales. Estos deben estar en una tabla 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 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 (por omisión: 76).

comment

Un comentario adicional para añadir a la entrada.

Acciones:

-

Inserta la cadena, referencia y escribe en po_out.

-

Devolver la traducción de la cadena (encontrada en po_in) de forma que el analizador pueda construir el doc_out.

-

Tratar 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 de verbosidad durante la creación del TransTractor.

debug()

Devuelve si se pasó la opción de depuración de fallos durante la creación del TransTractor.

detected_charset($)

Esto informa al TransTractor que se ha detectado un nuevo juego de caracteres (el primer argumento) en el documento de entrada. Habitualmente se puede encontrar en la cabecera del documento. Solo permanecerá el primer juego de caracteres, ya venga de los argumentos de «process()» o si se detectó en el documento.

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» 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 recodificado introducido como argumento, desde el juego de caracteres del documento de entrada al del documento de salida. No es necesario 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 en los ficheros «.desktop».

Para tratar este problema, los únicos cambios necesarios en la interfaz son:

-

tomar una tabla hash como po_in_name (una lista por idioma)

-

añadir un argumento a «translate» para indicar el idioma de destino

-

hacer una función pushline_all, que haría un pushline de su contenido para todos los idiomas, usando una sintaxis parecida al 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>