Provided by:
po4a_0.23-1_all 
NOMBRE
Po4a TransTractor - Trans(lator ex)tractor genérico (traductor
extractor).
DESCRIPCION
El objetivo del proyecto po4a (po para todo) es facilitar la traducción
(y más interesante, el mantenimiento de las traducciones) usando las
herramientas de gettext en áreas dónde 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 archivo 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 archivo po que contiene las traducciones a usar.
Como salida produce:
- otro archivo 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 archivo po suministrado en la entrada.
Aquà hay una representación gráfica de ésto:
Documento de entrada -\ /---> Documento de salida
\ / (traducido)
+-> función parse() --+
/ \
po de entrada --------/ \---> po de salida
(extraÃdo)
FUNCIONES QUE TU 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 se llama desde la función process() de abajo, pero si
elijes usar la función new(), y añadir contenido manualmente a tu
documento, deberás 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, ver la sección "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 lÃnea actual en la entrada,
# y poner el párrafo 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 párrafo (traducido)
$documento->pushline( "<p>"
. $documento->translate($parrafo,$parraref)
);
next PARRAFO;
} else {
# Añadimos al párrafo
$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 interfÃcie presentada en la siguiente sección.
INTERFICIE PUBLICA para scripts que usen tu analizador
Constructor
process(%)
Esta función puede hacer todo lo que quiera hacer con un documento
po4a en una invocación:. Sus parámetros 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 apéndices 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 intentará 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 usará 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 traducción 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 contendrá las cadenas extraÃdas del documento
de entrada.
addendum (@)
List of filenames where we should read the addenda from.
addendum_charset ($)
Juego de caracteres del apéndice.
new(%)
Crea un nuevo documento Po4a. Las opciones aceptadas (que deben
estar en un hash):
verbose ($)
Ajusta el nivel de información extra.
debug ($)
Ajusta la depuración.
manipulando archivos de documento
read($)
Añade otro documento de entrada al final del existente actualmente.
El parámetro es el nombre del archivo a leer.
Cabe destacar que esto no analiza nada. Debes usar la función
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($)
Añade el contenido del archivo (cuyo nombre es pasado como
parámetro) 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 estadÃsticas sobre la traducción hecha hasta
ahora. Estas no son las mismas estadÃsticas que las que muestra
msgfmt --statistic. Aquà las estadÃsticas son sobre el uso reciente
del archivo po, mientras que msgfmt informa del estado del archivo.
Esto es una envoltura de la función 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 apéndices
addendum($)
Consulte po4a(7) para más información sobre qué son los apéndices,
y cómo los traductores deben escribirlos. Para aplicar un apéndice
a un documento traducido, simplemente pasa su nombre de archivo a
é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
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. Mnemónica:
en la entrada, estás 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 ser
analizada, y su referencia (empaquetado como un array).
unshiftline($$)
Devuelve una lÃnea del documento de entrada y su referencia.
pushline($)
Inserta una nueva lÃnea al doc_out.
popline()
Extrae la última linea insertada al doc_out.
Marcando cadenas como traducibles
Se proporcionan una función para tratar el texto que debe ser
traducido.
translate($$$)
Parámetros obligatorios:
- Una cadena a traducir
- La referencia a esa cadena (p.e., la posición en el archivo de
entrada)
- El tipo de ésta cadena (p.e., la descripción textual de la
estructura ; utilizada en Locale::Po4a::Po::gettextization() ;
ver también la sección Gettextización: cómo funciona?) en
po4a(7).
Esta función también puede tomar algunos parámetros 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 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 (defecto:
76).
comment
Un comentario extra para añadir a la entrada.
Acciones:
- Inserta la cadena, referencia y tipo a po_out.
- Devuelve la traducción 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 pasó la opción verbose durante la creación del
TransTractor.
debug()
Devuelve si se pasó la opción debug durante la creación del
TransTractor.
detected_charset($)
Esto informa al TransTractor que se ha detectado un nuevo juego de
caracteres (el primer parámetro) en el documento de entrada.
Habitualmente se puede encontrar en la cabecera del documento. Solo
permanecerá el primer juego de carácteres, ya venga de los
parámetros de process() o sea detectado del documento.
get_out_charset()
Esta función 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).
Utilizará el juego de caracteres especificado en la linea de
comandos. 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 pasado como parámetro 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 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 los archivos .desktop.
Para tratar este problema, los únicos cambios necesarios en la
interfÃcie son:
- take a hash as po_in_name (a list per language)
- añadir un parámetro a translate para indicar el idioma destino
- hacer una función pushline_all, que harÃa 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>