NOMBRE¶

DESCRIPCIÓN¶

-

un documento a traducir;

-

un fichero PO que contiene las traducciones a usar.

-

otro fichero PO, resultado de la extracción 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.

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

FUNCIONES QUE SU ANALIZADOR DEBERÍA 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. Consulte 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á invocar ésta función manualmente.

docheader()

Esta función devuelve la cabecera que deberíamos añadir al documento creado, tratada de forma que sea un comentario para el lenguaje destino. Para ver las ventajas de esto, consulte la sección Educar a los programadores sobre las traducciones, en po4a(7).

SINOPSIS¶

 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 la etiqueta inicial
               $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;
   }
 }

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 de elementos asociativos («hash»). ACCIONES:

new(%)

Crea un nuevo documento po4a. Las opciones aceptadas (que deben estar en una tabla «hash»):

Manipula ficheros de documentos.¶

read($)

Añade 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($)

Escribe el documento traducido al fichero dado.

Manipula ficheros PO¶

readpo($)

Añade 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 extraído al nombre de fichero dado.

stats()

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

shiftline()

Esta función devuelve la próxima línea de «doc_in» a analizar, y su referencia (empaquetado como un vector, «array»).

unshiftline($$)

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

pushline($)

Inserta una nueva línea en «doc_out».

popline()

Extrae la última linea insertada en «doc_out».

Marcar cadenas como traducibles¶

translate($$$)

Argumentos obligatorios:

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

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» predefinido, 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¶

-

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 a «map»:

 

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

AUTORES¶

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