Provided by:
po4a_0.41-1ubuntu1_all 
NOMBRE
Locale::Po4a::TransTractor - Trans(lator ex)tractor generico (traductor
extractor).
DESCRIPCI'ON
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 areas donde no eran
de esperar, 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 DEBER'IA 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>"
. $document->translate($paragraph,$parraref)
);
next PARAGRAPH;
} else {
# Anadir al parrafo.
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reiniciar el bucle
($line,$lref)=$self->shiftline();
}
c # cNo 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 P'UBLICA 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 ($)
El juego de caracteres usado en el documento de entrada (si no
se especifica, se intentara detectar del documento de entrada)
file_out_name ($)
Nombre del fichero donde se debe escribir el documento de
salida.
file_out_charset ($)
El 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
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 (que deben
estar en una tabla <<hash>>):
verbose ($)
Configura el nivel de verbosidad.
debug ($)
Configura la depuracion.
Manipula ficheros de documentos.
read($)
Anade 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 funcion
<<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($)
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";
Manipular ap'endices
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.
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. Mnemonica:
en la entrada, esta 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>> a analizar, y
su referencia (empaquetado como un vector, <<array>>).
unshiftline($$)
Devolver una linea del documento de entrada y su referencia.
pushline($)
Inserta una nueva linea en <<doc_out>>.
popline()
Extrae la ultima linea insertada en <<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 (p. ej., la descripcion textual de la
estructura ; utilizada en Locale::Po4a::Po::gettextization();
consulte tambien la seccion Gettextizaci'on: 'cc'omo 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 se debe hacer el salto de linea (por
omision: 76).
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.
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
permanecera el primer juego de caracteres, ya venga de los
argumentos de <<process()>> o si se detecto en el 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 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.
recode_skipped_text($)
Esta funcion 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 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 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>