Provided by:
po4a_0.34-2_all 
NOMBRE
Locale::Po4a::TransTractor - Generic trans(lator ex)tractor.
DESCRIPCION
El objetivo del proyecto po4a (po para todo) es facilitar la
traducciA~Xn (y mA~Xs interesante, el mantenimiento de las
traducciones) usando las herramientas de gettext en A~Xreas dA~Xnde no
eran de esperar, como en la documentaciA~Xn.
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 traducciA~Xn en el documento de
salida.
MA~Xs formalmente, toma los siguientes parA~Xmetros como entrada:
- un documento a traducir ;
- un archivo po que contiene las traducciones a usar.
Como salida produce:
- otro archivo po, resultante de la extracciA~Xn 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.
AquA~ hay una representaciA~Xn grA~Xfica de A~Xsto:
Documento de entrada -\ /---> Documento de salida
\ / (traducido)
+-> funciA~Xn parse() --+
/ \
po de entrada --------/ \---> po de salida
(extraA~do)
FUNCIONES QUE TU ANALIZADOR DEBE IMPLEMENTAR
parse()
AquA~ es dA~Xnde se hace todo el trabajo: el anA~Xlisis de los
documentos de entrada, la generaciA~Xn de la salida, y la
extracciA~Xn de las cadenas traducibles. Es realmente simple usando
las funciones presentadas en la secciA~Xn "FUNCIONES INTERNAS"
mA~Xs abajo. VA~Xase la sinopsis, que presenta un ejemplo.
Esta funciA~Xn se llama desde la funciA~Xn process() de abajo, pero
si elijes usar la funciA~Xn new(), y aA~Xadir contenido manualmente
a tu documento, deberA~Xs llamar A~Xsta funciA~Xn manualmente.
docheader()
Esta funciA~Xn devuelve la cabecera que debemos aA~Xadir al
documento creado, tratada de forma que sea un comentario para el
lenguaje destino Para ver las ventajas de esto, ver la secciA~Xn
"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 lA~nea actual en la entrada,
# y poner el pA~Xrrafo 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 pA~Xrrafo (traducido)
$documento->pushline( "<p>"
. $documento->translate($parrafo,$parraref)
);
next PARRAFO;
} else {
# AA~Xadimos al pA~Xrrafo
$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 interfA~cie presentada en la siguiente secciA~Xn.
INTERFICIE PUBLICA para scripts que usen tu analizador
Constructor
process(%)
Esta funciA~Xn puede hacer todo lo que quiera hacer con un
documento po4a en una invocaciA~Xn:. Sus parA~Xmetros 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 apA~Xndices 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~X 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~X 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 traducciA~Xn
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~X las cadenas extraA~das del
documento de entrada.
addendum (@)
List of filenames where we should read the addenda from.
addendum_charset ($)
Juego de caracteres del apA~Xndice.
new(%)
Crea un nuevo documento Po4a. Las opciones aceptadas (que deben
estar en un hash):
verbose ($)
Ajusta el nivel de informaciA~Xn extra.
debug ($)
Ajusta la depuraciA~Xn.
manipulando archivos de documento
read($)
AA~Xade otro documento de entrada al final del existente
actualmente. El parA~Xmetro es el nombre del archivo a leer.
Cabe destacar que esto no analiza nada. Debes usar la funciA~Xn
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($)
AA~Xade el contenido del archivo (cuyo nombre es pasado como
parA~Xmetro) 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 estadA~sticas sobre la traducciA~Xn hecha hasta
ahora. Estas no son las mismas estadA~sticas que las que muestra
msgfmt --statistic. AquA~ las estadA~sticas son sobre el uso
reciente del archivo po, mientras que msgfmt informa del estado del
archivo. Esto es una envoltura de la funciA~Xn
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 apA~Xndices
addendum($)
Consulte po4a(7) para mA~Xs informaciA~Xn sobre quA~X son los
apA~Xndices, y cA~Xmo los traductores deben escribirlos. Para
aplicar un apA~Xndice a un documento traducido, simplemente pasa su
nombre de archivo a A~Xsta funciA~Xn y ya estA~X ;)
Esta funciA~Xn 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. MnemA~Xnica:
en la entrada, estA~Xs interesado en la primera lA~nea, lo que obtiene
shift, y en la salida se quiere insertar el resultado al final, como
hace push.
shiftline()
Esta funciA~Xn devuelve la prA~Xxima lA~nea de doc_in para ser
analizada, y su referencia (empaquetado como un array).
unshiftline($$)
Devuelve una lA~nea del documento de entrada y su referencia.
pushline($)
Inserta una nueva lA~nea al doc_out.
popline()
Extrae la A~Xltima linea insertada al doc_out.
Marcando cadenas como traducibles
Se proporcionan una funciA~Xn para tratar el texto que debe ser
traducido.
translate($$$)
ParA~Xmetros obligatorios:
- Una cadena a traducir
- La referencia a esa cadena (p.e., la posiciA~Xn en el archivo de
entrada)
- El tipo de A~Xsta cadena (p.e., la descripciA~Xn textual de la
estructura ; utilizada en Locale::Po4a::Po::gettextization() ;
ver tambiA~Xn la secciA~Xn GettextizaciA~Xn: cA~Xmo funciona?) en
po4a(7).
Esta funciA~Xn tambiA~Xn puede tomar algunos parA~Xmetros extra.
Estos deben estar en un hash. Por ejemplo:
$self->translate("cadena","referencia","tipo",
'wrap' => 1);
wrap
booleano indicando si podemos considerar que los espacios en
blanco de la cadena son despreciables. En ese caso, la
funciA~Xn canoniza la cadena antes de buscar su traducciA~Xn o
extraerla, y justifica la traducciA~Xn.
wrapcol
La columna en la que se debe hacer el salto de lA~nea (defecto:
76).
comment
Un comentario extra para aA~Xadir a la entrada.
Acciones:
- Inserta la cadena, referencia y tipo a po_out.
- Devuelve la traducciA~Xn 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 pasA~X la opciA~Xn verbose durante la creaciA~Xn del
TransTractor.
debug()
Devuelve si se pasA~X la opciA~Xn debug durante la creaciA~Xn del
TransTractor.
detected_charset($)
Esto informa al TransTractor que se ha detectado un nuevo juego de
caracteres (el primer parA~Xmetro) en el documento de entrada.
Habitualmente se puede encontrar en la cabecera del documento. Solo
permanecerA~X el primer juego de carA~Xcteres, ya venga de los
parA~Xmetros de process() o sea detectado del documento.
get_out_charset()
Esta funciA~Xn 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~X el juego de caracteres especificado en la linea de
comandos. Si no se ha especificado, utilizarA~X el juego de
caracteres del po de entrada, y si el po de entrada aA~Xn tiene el
"CHARSET" por defecto, devolverA~X el juego de caracteres del
documento de entrada, para que no se realice ninguna
codificaciA~Xn.
recode_skipped_text($)
Esta funciA~Xn devuelve el texto pasado como parA~Xmetro
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 sA~ lo es
cuando se salta alguna cadena del documento de entrada y quiere
mantener la consistencia del documento de salida con la
codificaciA~Xn 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 A~Xnicos cambios necesarios en la
interfA~cie son:
- take a hash as po_in_name (a list per language)
- aA~Xadir un parA~Xmetro a translate para indicar el idioma destino
- hacer una funciA~Xn pushline_all, que harA~a un pushline de su
contenido para todos los idiomas, usando una sintaxi parecida al map:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($linea,$ref,$langcode)
});
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>