Provided by:
po4a_0.41-1ubuntu1_all 
NOMBRE
po4a - Un marco de trabajo para traducir documentacion y otro material
Introducci'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.
Tabla de contenidos
Este documento esta organizado de la siguiente forma:
1 cPorque deberia usar po4a? cPara que sirve?
Este capitulo introductorio explica la motivacion del proyecto y su
filosofia. Deberia leerlo primero si esta en el proceso de
evaluacion de po4a para sus propias traducciones.
2 cComo usar po4a?
Este capitulo es como un manual de referencia, donde se intenta
contestar a las preguntas de los usuarios y se ofrece una idea
general del proceso. Le introducira al metodo de trabajo con po4a y
sirve como documentacion introductoria a las herramientas
especificas.
cComo empezar una nueva traduccion?
cComo transformar la traduccion de vuelta a un fichero de
documentacion?
cComo actualizar una traduccion con po4a?
cComo convertir una traduccion ya existente a po4a?
cComo anadir texto adicional a las traducciones (como el nombre del
traductor)?
cComo hacer todo esto con una sola invocacion al programa?
cComo configurar po4a?
3 cComo funciona?
Este capitulo ofrece una breve explicacion del funcionamiento
interno de po4a, de forma que se pueda sentir mas seguro para
ayudarnos a desarrollar y mejorar el programa. Tambien le puede
ayudar a entender porque no hace lo que esperaba, y como solucionar
sus problemas.
4 Preguntas frecuentes
Este capitulo agrupa las preguntas frecuentes. De hecho, la mayoria
de preguntas actuales se pueden formular asi: <<cPorque se ha
disenado de esta manera, y no otra?>> Si piensa que po4a no es la
solucion ideal para la traduccion de documentacion, deberia
considerar leer esta seccion. Si no responde a su pregunta,
contacte con nosotros en la lista de correo
<po4a-devel@lists.alioth.debian.org>. Queremos escuchar su opinion.
5 Notas especificas acerca de los modulos
Este capitulo presenta los puntos especificos de cada modulo desde
el punto de vista tanto del traductor como del autor original. Lea
esto para aprender la sintaxis que se encontrara cuando traduzca
textos con un modulo, o las reglas que debe seguir en el documento
original para facilitar la vida del traductor.
Actualmente esta seccion no forma parte de este documento. En
realidad esta en la documentacion de cada modulo. Esto permite
asegurar que la informacion esta actualizada al mantener la
documentacion y el codigo juntos.
'cPorqu'e debo usar po4a? 'cPara qu'e sirve?
Me gusta la idea del software de codigo abierto, lo que hace posible
que todo el mundo pueda acceder al software y a su codigo fuente. Pero
al ser frances soy bien consciente de que la licencia no es la unica
restriccion a la libertad del software: los programas libres no
traducidos son inservibles para gente de habla no inglesa, y todavia
nos queda bastante tarea para hacerlos disponibles para todos.
La percepcion de esta situacion por los responsables del software libre
ha mejorado drasticamente en los ultimos tiempos. Nosotros, como
traductores, hemos ganado la primera batalla y hemos convencido a todo
el mundo de la importancia de las traducciones. Pero por desgracia,
esta era la parte facil. Ahora tenemos que ponernos a trabajar y
empezar a traducir.
Actualmente, el software libre se beneficia de un nivel decente de
traduccion gracias al maravilloso conjunto de herramientas gettext.
Este puede extraer las cadenas a traducir de un programa, presentarlas
en un formato uniforme a los traductores, y luego usar el resultado de
su trabajo durante la ejecucion para mostrar los mensajes traducidos al
usuario.
Pero la situacion es bastante diferente para la documentacion.
Demasiado a menudo, la documentacion traducida no es suficientemente
visible (no se distribuye como parte del programa), solo lo esta
parcialmente, o no esta actualizada. La ultima situacion es la peor de
todas. Para los usuarios, las traducciones anticuadas pueden ser peor
que si no existiera la traduccion si describen viejos comportamientos
del programa que ya no se usan.
El problema a solucionar
Traducir documentacion no es muy dificil en si misma. Los textos son
bastante mas largos que los mensajes de programa, y por lo tanto tardan
mas en traducirse, pero no se necesitan conocimientos tecnicos para
hacerlo. La parte dificil llega cuando se debe mantener el trabajo al
dia. Detectar que partes han cambiado y se necesitan actualizar es muy
dificil, conduce a errores y es bastante desagradable. Creo que esto
explica porque tantas de las traducciones de documentacion que hay por
ahi estan anticuadas.
Las respuestas de po4a
Por ello, el objetivo de po4a es poder mantener la traduccion de
documentacion al dia. La idea es reusar la metodologia de gettext en
este nuevo campo. Al igual que con gettext, los textos se extraen de su
ubicacion original para ser presentados en un formato uniforme a los
traductores. Las herramientas clasicas de gettext ayudan a actualizar
el trabajo cuando aparece una nueva version del original. Pero a
diferencia del modelo clasico de gettext, las traducciones se devuelven
a la estructura del documento original de forma que se puedan procesar
y distribuir igual que la version en ingles.
Gracias a esto, descubrir que partes del documento han cambiado y se
necesitan actualizar se vuelve muy facil. Otro punto fuerte es que las
herramientas haran practicamente toda la tarea cuando la estructura del
documento original se reorganice y algunos capitulos se reubiquen,
junten o separen. Al extraer el texto a traducir de la estructura del
documento, tambien le mantiene lejos de la complejidad del formateo de
texto y reduce las oportunidades de danar el documento (aunque no le
prevenga completamente de hacerlo).
Por favor, lea tambien las Preguntas frecuentes, mas abajo en este
documento, para una lista mas completa de las ventajas y desventajas de
este enfoque al problema.
Formatos compatibles
Actualmente se han implementado satisfactoriamente algunos tipos de
formato de texto:
man
El clasico formato de las paginas de manual, usado por un gran numero
de programas. La compatibilidad con po4a es bienvenida ya que el
formato es algo dificil de usar, y no muy amistoso para los
principiantes. El modulo Locale::Po4a::Man(3pm) es tambien compatible
con el formato mdoc, empleado en las paginas de manual BSD (bastante
comunes en Linux).
pod
Este es el formato <<Perl Online Documentation>> (Documentacion en
linea de Perl). El lenguaje y sus mismas extensiones estan documentados
asi, igual que la mayoria de scripts de Perl. Hace muy facil mantener
la documentacion cerca del codigo al integrarlos en el mismo fichero.
Facilita la vida del programador, pero por desgracia, no la del
traductor.
sgml
Aunque hoy en dia XML practicamente lo haya sustituido, este formato
aun se usa habitualmente para documentos mas extensos que algunas
pantallas, y le permite hacer libros completos. Actualizar una
traduccion de documentos tan largos puede ser realmente un infierno. A
menudo diff se vuelve inutil cuando se ha sangrado (<<indented>>) otra
vez el texto original despues de una actualizacion. Afortunadamente,
po4a le puede ayudar en ese proceso.
Actualmente, solo son compatibles los DTD de DebianDoc y de DocBook,
pero anadir compatibilidad con uno nuevo es realmente facil. Incluso es
posible usar po4a con un DTD desconocido de SGML sin cambiar el codigo
introduciendo la informacion necesaria en la linea de ordenes. Consulte
Locale::Po4a::Sgml(3pm) para mas detalles.
TeX / LaTeX
El formato LaTeX es un formato de documentacion usado principalmente en
el mundo del Software Libre y para publicaciones. Se probo el modulo
Locale::Po4a::LaTeX(3pm) con la documentacion de Python, un libro y
algunas presentaciones.
texinfo
Toda la documentacion de GNU esta escrita en este formato (es incluso
un requisito para ser un proyecto oficial de GNU). La compatibilidad de
Locale::Po4a::Texinfo(3pm) en po4a esta en sus inicios. Por favor,
remita informes de fallo y peticiones de funcionalidades.
xml
El formato XML sirve de base para muchos formatos de documentacion.
Actualmente, el formato DTD de DocBook es compatible con po4a. Para mas
detalles, consulte Locale::Po4a::Docbook(3pm).
otros
po4a tambien puede tratar algunos formatos raros o especificos, tales
como la documentacion de las opciones de compilacion de nucleos 2.4.x o
los diagramas producidos por la herramienta dia. Anadir uno nuevo es a
menudo una tarea muy sencilla, y la tarea principal es conseguir un
analizador para el formato escogido. Consulte
Locale::Po4a::TransTractor(3pm) para mas informacion.
Formatos no compatibles
Desafortunadamente, po4a no es compatible con varios formatos de
documentacion.
Nos gustaria anadir la compatibilidad de po4a con un grupo de otros
formatos, y no solo de documentacion. De hecho, queremos cubrir todos
los <<vacios del mercado>> dejados por las herramientas clasicas de
gettext. Esto incluye descripciones de paquetes (deb y rpm), preguntas
de los scripts de instalacion de paquetes, el registro de cambios de
los paquetes, y todos los formatos especificos usados por programas
tales como escenarios de juegos o los ficheros de recursos de wine.
'cC'omo usar po4a?
Este capitulo es como un manual de referencia, donde se intenta
contestar a las preguntas de los usuarios y se ofrece una idea general
del proceso. Le introducira al metodo de trabajo con po4a y sirve como
documentacion introductoria a las herramientas especificas.
Visi'on esquem'atica
El siguiente esquema ofrece una vision global del proceso de traduccion
de documentacion usando po4a. No se asuste por su aparente complejidad,
esto se debe a que aqui se representa el proceso completo. Una vez que
haya convertido su proyecto a po4a solo sera relevante la parte derecha
del grafico.
Observe que original.doc se toma como un ejemplo de la documentacion a
traducir, y que traducci'on.doc es el texto traducido correspondiente.
La extension podria ser .pod, .xml o .sgml dependiendo del formato.
Cada parte del dibujo se explicara con detalle en las siguientes
secciones.
original.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{traduccion} | { actualizacion de original.doc } :
: | | :
XX.doc | V V
(opcional) | original.doc ->------->----->+
: | (new) |
V V | |
[po4a-gettextize] doc.XX.po--->+ | |
| (antiguo) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
traduccion.pot ^ V |
| | doc.XX.po |
| | (<<fuzzy>> (difusa)) |
{ traduccion } | | |
| ^ V V
| | {edicion manual} |
| | | |
V | V V
doc.XX.po --->---->+<---<---- doc.XX.po apendice original.doc
(inicial) (actualizado) (opcional) (actualizado)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.doc
(actualizado)
En la parte izquierda se muestra la conversion de una traduccion que no
usa po4a a este sistema. En la parte superior derecha se representa la
accion del autor original (actualizar la documentacion). En la parte
central derecha se simbolizan las acciones automaticas de po4a. Se
extrae el nuevo material, y se compara con la traduccion existente. Se
encuentran las partes que no han cambiado, y se usa la traduccion
previa. Las partes parcialmente modificadas tambien se conectan con la
traduccion anterior, pero se anade un marcador indicando que la
traduccion se debe actualizar. La parte inferior de la figura muestra
como se construye el documento formateado.
En realidad, como traductor, la unica operacion manual que debe hacer
es la parte marcada como {edicion manual}. Si, lo siento, pero po4a le
ayuda a traducir. No traduce nada por usted...
'cC'omo empezar una nueva traducci'on?
Esta seccion presenta los pasos necesarios para iniciar una nueva
traduccion con po4a. Los refinamientos involucrados en la conversion de
un proyecto existente a este sistema se detallan en la seccion
pertinente.
Para iniciar una nueva traduccion utilizando po4a, debe seguir los
siguientes pasos:
- Extraccion del texto que se tiene que traducir del documento
<original.doc> a una nueva plantilla de traduccion <traducci'on.pot>
(el formato de gettext). Para ello, use el programa po4a-gettextize
de la siguiente manera:
$ po4a-gettextize -f <formato> -m <original.doc> -p <traduccion.pot>
Naturalmente, <formato> es el formato usado en el documento
original.doc. Tal como es de esperar, la salida va a traducci'on.pot.
para mas detalles sobre las opciones existentes consulte
po4a-gettextize(1).
- Ahora toca traducir lo que se debe traducir. Para ello, debe
renombrar el fichero POT a doc.XX.po, por ejemplo (donde XX es el
codigo ISO639 del idioma al que este traduciendo, por ejemplo fr para
el frances), y edite el fichero resultante. A menudo es una buena
idea no llamar al fichero XX.po para evitar confusiones con la
traduccion de los mensajes de programa, pero esto depende del
usuario. No se olvide de actualizar las cabeceras de los ficheros PO,
son importantes.
La traduccion en si misma se puede hacer con el modo PO de Emacs,
Lokalize (basado en KDE), Gtranslator (basado en GNOME), o cualquier
programa que prefiera. Incluso el clasico vi puede bastar, aunque no
tenga un modo especializado para esta tarea.
Si desea aprender mas, definitivamente necesita consultar la
documentacion de gettext, disponible en el paquete gettext-doc.
'cC'omo transformar la traducci'on de vuelta a un fichero de documentaci'on?
Una vez que haya terminado la traduccion, querra obtener la
documentacion traducida para distribuirla a los usuarios junto con el
original. Para ello, utilice el programa po4a-translate(1) de la
siguiente manera (XX es el codigo del idioma):
$ po4a-translate -f <formato> -m <original.doc> -p <doc-XX.po> -l <XX.doc>
Al igual que antes, <formato> es el formato usado en el documento
original.doc. Pero esta vez, el fichero PO introducido con el parametro
-p es parte de la entrada. Esta es su traduccion. La salida va a
XX.doc.
Para mas detalles consulte po4a-translate(1) .
'cC'omo actualizar una traducci'on con po4a?
Para actualizar su traduccion cuando el fichero de origen original.doc
cambie, use el programa po4a-updatepo(1) de la siguiente manera:
$ po4a-updatepo -f <formato> -m <nuevo_original.doc> -p <doc_antiguo.XX.po>
Para mas detalles consulte po4a-updatepo(1).
Naturalmente, los nuevos parrafos del documento no se traduciran
magicamente en el fichero PO con esta operacion, y necesitara
actualizar el fichero PO manualmente. Asi mismo, puede que tenga que
rehacer las traducciones de los parrafos que se hayan modificado un
poco. Para asegurar que no pasara ninguna por alto, se marcan como
<<fuzzy>> (difusas) durante el proceso, y debera quitar esta marca
manualmente antes de que pueda usar la traduccion con po4a-translate.
Al igual que para la traduccion inicial, aqui lo mejor es usar su
editor PO favorito.
Una vez su fichero PO este otra vez actualizado, sin ninguna cadena por
traducir ni cadenas difusas, puede generar el fichero de documentacion
traducido, tal y como se explico en la seccion anterior.
'cC'omo convertir una traducci'on ya existente a po4a?
A menudo, usted acostumbraba a traducir manualmente el documento
felizmente hasta que llego una reorganizacion del documento de origen
original.doc. Entonces, despues de algunos intentos fracasados con diff
o herramientas similares, desea pasarse a po4a. Pero, por supuesto, no
quiere perder su traduccion en el proceso. No se preocupe, las
herramientas de po4a tambien tienen en cuenta este caso, se llama
<<gettextizacion>>.
La condicion mas importante es que tanto el documento traducido como el
original tengan la misma estructura de manera que las herramientas
puedan encajar los contenidos correctamente.
Si esta de suerte (es decir, si las estructuras de ambos documentos
encajan a la perfeccion), todo funcionara a la perfeccion y habra
terminado en unos segundos. En caso contrario, debera entender porque
este proceso tiene un nombre tan feo, y deberia estar preparado para un
poco de trabajo sucio. En cualquier caso, recuerde que este es el
precio a pagar para obtener luego la comodidad de po4a. Y la mejor
parte es que solo debera hacer esto una vez.
No puedo enfatizarlo mas. Para facilitar el proceso es importante
encontrar la version exacta que se uso para la traduccion. La mejor
situacion se da cuando anoto que revision del VCS se uso para la
traduccion y que no se modifico durante el proceso de traduccion, de
forma que pueda usarla.
No funcionara bien si usa el texto original actualizado con una
traduccion vieja. Es un proceso posible, pero mas dificil y en realidad
se debe evitar en la medida que sea posible. De hecho, imagino que si
no consigue encontrar el texto original otra vez, la mejor solucion es
encontrar a alguien que haga la gettextizacion por usted (pero por
favor, que no sea yo ;).
Quiza este siendo demasiado dramatico en este punto. Aunque las cosas
vayan mal, sigue siendo mucho mas rapido que traducirlo todo otra vez.
Yo hice la gettextizacion de la traduccion al frances existente de la
documentacion de Perl en un dia, a pesar de que las cosas fueron mal.
Eran mas de dos megabytes de texto, y una traduccion nueva hubiera
podido durar como minimo meses.
Permitame explicar primero las bases del proceso, y luego ya volveremos
a los indicaciones para conseguirlo cuando el proceso vaya mal. Para
facilitar la comprension usaremos el ejemplo anterior una vez mas:
Una vez que tiene el anticuado original.doc, que encaja con el XX.doc
traducido, puede ejecutar la gettextizacion directamente sobre el
fichero PO doc.XX.po sin realizar una traduccion manual del fichero
traducci'on.pot:
$ po4a-gettextize -f <formato> -m <original_anticuado.doc> -l <XX.doc> -p <doc.XX.po>
Si esta de suerte, eso es todo. Ha convertido su vieja traduccion a
po4a y ya puede iniciar la tarea de actualizacion en el momento.
Simplemente siga el proceso explicado unas secciones antes para
sincronizar su fichero PO con el documento original mas reciente, y
actualizar la traduccion de acuerdo al mismo.
Tenga en cuenta que aunque parezca que todo ha ido bien, aun queda
lugar para los errores en este proceso. El caso es que po4a no es capaz
de entender el texto para asegurarse de que la traduccion se refiere al
original dado. Es por ello que las cadenas se marcan como difusas
(<<fuzzy>>) durante el proceso. Debe comprobar cuidadosamente cada
cadena antes de eliminar esas marcas.
A menudo las estructuras de los documentos no encajan a la perfeccion,
impidiendo que po4a-gettextize realice su tarea. Llegados a este punto,
todo el proceso se traslada a la edicion de los ficheros para hacer
encajar sus malditas estructuras.
Le puede ayudar leer la seccion Gettextizaci'on: 'cC'omo funciona?, mas
abajo. La comprension del funcionamiento interno del proceso le ayudara
a hacerlo funcionar. El punto bueno es que po4a-gettextize da mucha
informacion cuando algo no va bien. Primero, apunta donde se encontro
la discrepancia de estructuras en los documentos. Luego le mostrara las
cadenas que no encajan, su posicion en el texto, y el tipo de cada una.
Ademas, el fichero PO generado hasta el momento se guardara en
gettextization.failed.po.
- Elimine todas las partes anadidas de las traducciones, como
secciones donde se especifica el nombre del traductor, o los
agradecimientos de gente que colaboro con la traduccion. Los
apendices, descritos en la siguiente seccion, le permitiran volver
a anadir estos contenidos.
- No dude en editar tanto el original como la traduccion. Lo mas
importante es conseguir el fichero PO. Ya tendra tiempo de
actualizarlo luego. Dicho esto, es preferible editar la traduccion
cuando se pueden editar ambos, ya que facilita las cosas cuando
haya finalizado la gettextizacion.
- Si es necesario, elimine algunas partes del original si no estaban
traducidas. Cuando mas adelante sincronice el PO con el documento,
volveran por si solas.
- Si cambio un poco la estructura (para juntar dos parrafos, o
dividir alguno), deshaga esos cambios. Si hay problemas con el
original, deberia informar al autor original del texto. Arreglarlo
solo en la traduccion solo ofrece la solucion a una parte de la
comunidad. Y ademas, es imposible cuando se usa po4a ;)
- A veces el contenido del parrafo encaja, pero su tipo no. Arreglar
eso depende mucho del formato. En POD y man, a menudo es culpa de
que una de las dos lineas empieza con un espacio y la otra no. En
estos formatos, este parrafo no se podria justificar y su tipo
cambiaria. Simplemente elimine el espacio y ya esta. Tambien puede
tratarse de un error tipografico en el nombre de la etiqueta.
De manera parecida, dos parrafos se podrian fusionar en un POD
cuando la linea de separacion contiene algunos espacios, o cuando
no hay una linea de separacion antes de la linea =item y del
contenido del elemento (<<item>>).
- A veces, hay un asincronia entre ficheros y la traduccion se
empareja con un parrafo original equivocado. Este es un signo de
que el problema real ya existia en los ficheros. Compruebe
gettextization.failed.po para ver cuando empieza la asincronismo, y
arreglelo ahi.
- A veces le puede dar la impresion de que po4a omitio algunas partes
del texto, ya sea del original o de la traduccion.
gettextization.failed.po indica que ambos encajaban correctamente,
y luego fallo porque intento encajar un parrafo con el anterior (o
posterior) con el correcto, como si el correcto hubiera
desaparecido. Maldiga po4a como yo hice la primera vez que me paso.
Abundantemente.
Esta desafortunada situacion se debe a que el mismo parrafo se
repite a lo largo del documento. En ese caso, no se crea una nueva
entrada en el fichero PO, sino que se anade una nueva referencia a
la ya existente.
Por lo tanto, cuando el mismo parrafo aparece dos veces en el
original pero no esta traducido exactamente igual en cada
aparicion, tendra la sensacion de que desaparecio un parrafo del
original. Simplemente elimine la traduccion nueva. Si cree que la
segunda traduccion es mejor, eliminela de donde esta, y pongala en
el lugar de la primera.
En caso contrario, si dos parrafos parecidos pero diferentes se
tradujeron de la misma forma le puede dar la impresion de que
desaparecio un parrafo de la traduccion. La solucion es anadir una
cadena de relleno al parrafo original (algo como <<soy diferente>>)
para solucionarlo. No se asuste. Estas cosas desapareceran durante
la sincronizacion, y cuando el texto anadido sea suficientemente
corto, gettext encajara su traduccion con el texto existente
(marcandola como difusa, pero no importa, ya que todas las cadenas
se marcan como difusas durante la gettextizacion).
Con un poco de suerte estos trucos le ayudaran a realizar su
gettextizacion y a obtener su preciado fichero PO. Ahora esta preparado
para sincronizar su fichero y empezar la traduccion. Tenga en cuenta
que en textos grandes la primera sincronizacion puede tardar mucho
tiempo.
Por ejemplo, el primer po4a-updatepo de la traduccion al frances de la
documentacion de Perl (un fichero PO de 5.5 Mb) tomo alrededor de dos
dias enteros en una maquina G5 a 1Ghz. Si, 48 horas. Pero las
siguientes veces tan solo tardaba una docena de segundos en mi viejo
portatil. Esto se debe a que la primera vez la mayoria de msgid del
fichero PO no encajaban con ninguno de los del fichero POT. Esto obliga
a gettext a buscar la cadena mas parecida usando un costoso algoritmo
de proximidad de cadenas.
'cC'omo a~nadir texto adicional a las traducciones (como el nombre del
traductor)?
Debido al enfoque de gettext, esto se vuelve mas dificil en po4a que
antes, cuando simplemente se editaba el nuevo fichero paralelamente al
original. Pero sigue siendo posible, gracias a los llamados ap'endices
(<<addenda>>).
Para ayudar a la comprension, considere los apendices como unos parches
aplicados al documento traducido despues del proceso. Son bastante
diferentes que los parches habituales (solo tienen una linea de
contexto, que puede incluir una expresion regular de Perl y unicamente
pueden anadir texto, sin eliminar nada), pero la funcionalidad es la
misma.
Su objetivo es permitir al traductor anadir contenido adicional al
documento que no esta traducido a partir documento original. El uso mas
habitual es anadir una seccion sobre la misma traduccion, listando los
colaboradores y explicando como informar de los errores en la
traduccion.
El apendice (addendum) se debe proporcionar como un fichero separado.
La primera linea forma una cabecera que indica el lugar del documento
resultante donde se debe colocar. El resto del contenido del fichero
apendice se anadira literalmente cual en la posicion determinada en el
documento resultante.
La cabecera tiene una sintaxis muy rigida: debe empezar con la cadena
PO4A-HEADER:, seguida por una lista de campos llave=valor separados por
un punto y coma (;). Los espacios en blanco SON importantes. Tenga en
cuenta que no puede usar el caracter de punto y coma (;) en los
valores, y que las comillas no ayudan en este caso.
Una vez mas, suena espantoso, pero los ejemplos proporcionados a
continuacion deberian ayudarle a encontrar la forma de escribir la
linea de cabecera que necesita. Para ilustrar la discusion, suponga que
desea anadir una seccion llamada <<Acerca de esta traduccion>> despues
de la denominada <<Acerca de este documento>>.
Aqui estan las posibles llaves de la cabecera:
position (obligatoria)
Una expresion regular. El apendice se ubicara cerca de la linea que
coincida con esta expresion regular. Tenga en cuenta que estamos
hablando del documento traducido, no del original. Si hay mas de
una linea que coincida con esta expresion (o ninguna), la adicion
fallara. Siempre es mejor informar de un error que insertar el
apendice en el sitio equivocado.
Esta linea se llama punto de ubicaci'on (<<position>>). El punto
donde se insertara el apendice se llama punto de inserci'on
(<<insertion>>). Estos dos puntos estan muy proximos, pero no son
iguales. Por ejemplo, si desea una nueva seccion, es mas facil
definir el punto de ubicaci'on con el titulo de la seccion anterior,
y explicarle a po4a donde termina la seccion (recuerde que el punto
de ubicaci'on viene dado por la expresion regular, que debe
coincidir con una unica linea).
La ubicacion del punto de inserci'on respecto al punto de ubicacion
esta controlado por los campos mode, beginboundary y endboundary,
explicados a continuacion.
En nuestro caso tendriamos:
position=<title>Acerca de este documento</title>
mode (obligatorio)
Puede ser tanto before (antes) o after (despues), especificando la
posicion del apendice, relativa al punto de ubicaci'on.
Ya que queremos que la seccion nueva se situe debajo de la que
hemos emparejado, tenemos:
mode=after
beginboundary (inicio del limite, usado solo con mode=after, y
obligatorio en ese caso)
endboundary (fin del limite, idem)
Expresion regular que encaja con el final de la seccion que precede
a la posicion del apendice.
Con mode=after, el punto de inserci'on esta despues del punto de
ubicaci'on, ipero no justamente despues! Esta situado al final de la
seccion que empieza en el punto de ubicaci'on, es decir, antes o
despues de la linea encajada por el argumento ???boundary,
dependiendo de si uso beginboundary o endboundary.
En nuestro caso, podemos decidirnos por indicar el final de la
seccion que queremos emparejar anadiendo:
endboundary=</section>
o indicar el principio de la siguiente seccion indicando:
beginboundary=<section>
En ambos casos, nuestro apendice se ubicara despues de </section> y
antes de <section>. La primera opcion es mejor ya que funcionara
aunque se reorganice el documento.
Las dos formas existen debido a que los formatos de documentacion
son diferentes. En algunos de ellos, hay una forma de marcar el
final de una seccion (tal como </section>, que ya hemos usado),
mientras que otros no marcan explicitamente el final de una seccion
(como con el formato man). En el primer caso, es preferible encajar
boundary con el final de secci'on, para que el punto de inserci'on
venga despues. En el segundo caso, debera encajar un boundary con
el principio de la siguiente secci'on para que el punto de inserci'on
venga justo antes de este.
Puede parecer criptico, pero espero que los siguientes ejemplos le
iluminen.
Para resumir el ejemplo usado hasta el momento, si desea insertar una
seccion llamada <<Acerca de esta traduccion>> despues de la seccion
<<Acerca de este documento>> en un documento SGML, debe usar una de
estas lineas de cabecera:
PO4A-HEADER: mode=after; position=Acerca de este documento; endboundary=</section>
PO4A-HEADER: mode=after; position=Acerca de este documento; beginboundary=<section>
Si desea anadir algo despues de la siguiente seccion de nroff:
.SH "AUTORES"
deberia poner un position que encaje esta linea, y un beginboundary
que encaje con el principio de la siguiente seccion (es decir ^\.SH).
El apendice se anadiria despu'es del punto de ubicaci'on e
inmediatamente antes de la primera linea que encaje con
beginboundary. Esto es:
PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH
Si desea anadir algo dentro de una seccion (como despues de <<Copyright
Big Dude>>) en vez de anadir una seccion completa, introduzca un
"position" que encaje con esta linea, e introduzca un beginboundary que
encaje con cualquier linea.
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
Si desea anadir algo al final del documento, especifique un position
que encaje con cualquier linea del documento (pero solo una linea. po4a
no procedera si no es unica), y ponga un endboundary que no encaje con
nada. No utilice cadenas simples como "EOF", sino las que tengan menos
probabilidad de salir en el documento.
PO4A-HEADER:mode=after;position=<title>Acerca de</title>;beginboundary=BoundaryFalsoDePo4a
En cualquier caso, recuerde que se tratan de expresiones regulares. Por
ejemplo, si desea encajar con el final de una seccion de nroff que
termina con la linea
.fi
no utilice .fi como endboundary, porque esto encajara con <<el[
fi]chero>>, que obviamente no es lo que espera. El endboundary correcto
en este caso seria: ^\.fi$.
Si el apendice no se ubica donde esperaba, pruebe introduciendo el
parametro -vv a las herramientas para que le expliquen que hacen al
colocar el apendice.
Ejemplo m'as detallado
Documento original (en formato POD):
|=head1 NOMBRE
|
|relleno - un programa de relleno
|
|=head1 AUTOR
|
|yo
Luego, el siguiente apendice asegurara que se anade una seccion (en
espanol) sobre el traductor al final del fichero.
|PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head
|
|=head1 TRADUCTOR
|
|yo
Para poner su apendice antes del AUTOR, utilice la siguiente cabecera:
PO4A-HEADER:mode=after;position=NOMBRE;beginboundary=^=head1
Esto funciona porque la siguiente linea que encaja con beginboundary
<</^=head1/>> despues de la seccion <<NOMBRE>>, es la que declara los
autores. Por lo tanto, se colocara el apendice entre ambas secciones.
'cC'omo hacer todo esto con una sola invocaci'on al programa?
El uso de po4a ha demostrado que puede dar lugar a errores ya que debe
invocar dos programas distinto en el orden adecuado (po4a-updatepo y
luego po4a-translate), y cada uno necesita mas de 3 argumentos. Ademas,
era dificil con este sistema usar solo un fichero PO para todos los
documentos cuando se usaba mas de un formato.
El programa po4a(1) se diseno para solucionar esas dificultades. Una
vez que haya convertido su proyecto a este sistema, puede escribir un
sencillo fichero de configuracion explicando donde estan los ficheros
de traduccion (PO y POT), donde estan los documentos originales, sus
formatos y donde se deberian guardar las traducciones.
Luego, una simple invocacion a po4a(1) con este fichero como argumento
asegura que los ficheros PO se sincronicen con el documento original, y
que los documentos traducidos se generan correctamente. Por supuesto,
le interesara invocar este programa dos veces: una antes de editar el
fichero PO para actualizarlo, y otra para obtener los documentos
traducidos totalmente actualizados. Pero solo necesita recordar una
orden.
'cC'omo configurar po4a?
Los modulos de po4a tienen opciones (especificados con la opcion -o),
que se pueden usar para modificar el comportamiento del modulo.
Tambien es posible configurar un modulo o modulos nuevos, derivados o
modificados mediante la insercion de un modulo en lib/Locale/Po4a/, y
anadiendo lib a las rutas especificadas en los entornos PERLLIB o
PERL5LIB. Por ejemplo:
PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg
Nota: el nombre real del directorio <</lib>> no es importante.
'cC'omo funciona?
Este capitulo ofrece una breve explicacion del funcionamiento interno
de po4a, de forma que se pueda sentir mas seguro para ayudarnos a
desarrollar y mejorar el programa. Tambien le puede ayudar a entender
porque no hace lo que esperaba, y como solucionar sus problemas.
Visi'on general
La arquitectura de po4a esta orientada a objetos (en Perl. Muy pulcro,
cno?). El antecesor de todas las clases de analizadores se llama
TransTractor. Este extrano nombre viene del hecho de que se encarga al
mismo tiempo de traducir el documento (<<translate>>) y de extraer las
cadenas (<<extract>>).
Mas formalmente, toma un documento a traducir, ademas del fichero PO
que contiene las traducciones a usar como entrada mientras produce dos
salidas separadas: Otro fichero PO (resultado de la extraccion de las
cadenas traducibles del documento de entrada), y un documento traducido
(con la misma estructura que el de entrada, pero con las cadenas
traducibles reemplazadas por el contenido del PO de entrada). Esta es
una representacion grafica de este proceso:
Documento de entrada -\ /---> Documento de salida
\ TransTractor:: / (traducido)
+-->-- parse() ------+
/ \
PO de entrada --------/ \---> PO de salida
(extraido)
Esta pequeno hueso es el nucleo de toda la arquitectura de po4a. Si
omite el PO de entrada y el documento de salida, obtiene
po4a-gettextize. Si proporciona ambas entradas y descarta el PO de
salida, obtiene po4a-translate.
TransTractor::parse() es una funcion virtual integrada en cada modulo.
Aqui hay un pequeno ejemplo que muestra como funciona. Analiza una
lista de parrafos, cada uno empezando con <p>.
1 sub parse {
2 PARAGRAPH: while (1) {
3 $my ($paragraph,$pararef,$line,$lref)=("","","","");
4 $my $first=1;
5 while (($line,$lref)=$document->shiftline() && defined($line)) {
6 if ($line =~ m/<p>/ && !$first--; ) {
7 $document->unshiftline($line,$lref);
8
9 $paragraph =~ s/^<p>//s;
10 $document->pushline("<p>".$document->translate($paragraph,$pararef));
11
12 next PARAGRAPH;
13 } else {
14 $paragraph .= $line;
15 $pararef = $lref unless(length($pararef));
16 }
17 }
18 return; # cNo obtuvo una linea definida? Fin del fichero de entrada.
19 }
20 }
En la linea 6, encontramos <p> por segunda vez. Esta es la senal de que
hemos encontrado el siguiente parrafo. Debemos entonces devolver la
linea obtenida de vuelta al documento (linea 7) y enviar el parrafo
construido hasta el momento a las salidas. Despues de eliminar el <p>
inicial en la linea 9, insertamos la concatenacion de esta etiqueta
junto con la traduccion del resto del parrafo.
La funcion <<translate()>> esta muy bien. Envia su argumento al fichero
PO de salida (extraccion) y devuelve su traduccion tal y como es en el
fichero PO de entrada (traduccion). Ya que se usa como parte del
argumento de <<pushline()>>, esta traduccion acaba en el documento de
salida.
cComo mola, no? Es posible construir un modulo completo de po4a en
menos de 20 lineas si el formato es suficientemente simple...
Encontrara mas acerca de esto en Locale::Po4a::TransTractor(3pm).
Gettextizaci'on: 'cC'omo funciona?
La idea aqui es tomar el documento original y su traduccion, y
considerar que la enesima cadena extraida de la traduccion es la
traduccion de la enesima cadena extraida del original. Para que
funcione, ambos ficheros deben compartir exactamente la misma
estructura. Por ejemplo, si los ficheros tienen la siguiente
estructura, es muy poco probable que la cuarta cadena de la traduccion
(de tipo 'capitulo') sea la traduccion de la cuarta cadena del original
(de tipo 'parrafo').
Original Traduccion
capitulo capitulo
parrafo parrafo
parrafo parrafo
parrafo capitulo
capitulo parrafo
parrafo parrafo
Para ello, los analizadores de po4a se utilizan tanto con el fichero
original como con el traducido para extraer los ficheros PO, y luego se
construye un tercer fichero PO a partir de ellos tomando las cadenas
del segundo como traducciones de las del primero. Para comprobar que
las cadenas que juntamos se correspondan, los analizadores de
documentos de po4a deben dar informacion sobre el tipo sintactico de
las cadenas extraidas en el documento (todos los que hay lo hacen, el
suyo tambien lo deberia hacer). Esa informacion se utiliza despues para
asegurar que ambos documentos tienen la misma sintaxis. En el ejemplo
anterior, nos permitiria detectar que la cuarta cadena es un parrafo en
un caso, y el titulo de un capitulo en el otro e informar del problema.
En teoria, seria posible detectar el problema, y resincronizar los
ficheros posteriormente (al igual que diff). Pero no esta claro que
deberiamos hacer con las cadenas antes de las asincronias, y a veces
podria producir malos resultados. Es por ello que la implementacion
actual no intenta resincronizar nada, e informa extensamente del fallo
cuando algo va mal, requiriendo la modificacion manual de los ficheros
para arreglar el problema.
Incluso con estas precauciones, las cosas se pueden estropear muy
facilmente. Es por ello que todas las traducciones encontradas asi se
marcan como difusas, para asegurar que el traductor las repase y
corrija.
Ap'endice (<<Addendum>>): 'cC'omo funciona?
Bueno, esto es muy simple. El documento traducido no se escribe
directamente al disco, sino que se mantiene en memoria hasta que se
insertan todos los apendices. Los algoritmos involucrados son mas bien
sencillos. Buscamos una linea que encaje con la expresion regular de la
ubicacion, e insertamos el apendice antes del mismo si estamos en
mode=before. De no ser asi, buscamos la siguiente linea que encaje con
el <<boundary>> (limite) e insertamos el apendice a continuacion de
esta linea si es un endboundary o antes de esta linea si es un
beginboundary.
Preguntas frecuentes
Este capitulo agrupa las preguntas frecuentes. De hecho, la mayoria de
preguntas actuales se pueden formular asi: <<cPorque se ha disenado de
esta manera, y no otra?>> Si piensa que po4a no es la solucion ideal
para la traduccion de documentacion, deberia considerar leer esta
seccion. Si no responde a su pregunta, contacte con nosotros en la
lista de correo <po4a-devel@lists.alioth.debian.org>. Queremos escuchar
su opinion.
'cPorqu'e traducir cada p'arrafo por separado?
Si, en po4a, cada parrafo se traduce por separado (de hecho, cada
modulo lo decide, pero todos los existentes lo hacen, y el suyo tambien
deberia hacerlo). Hay dos ventajas principales al hacerlo asi:
o Cuando se ocultan las partes tecnicas del documento, el traductor no
puede alterarlas. Cuantas menos marcas presentemos al traductor,
menos errores podra hacer.
o El hecho de dividir el documento ayuda a aislar los cambios en el
documento original. Este proceso facilita encontrar que partes de la
traduccion se necesitan actualizar cuando se modifica el documento
original.
Incluso con estas ventajas, a algunas personas no les gusta la idea de
traducir cada parrafo por separado. Aqui hay algunas respuestas que les
puedo dar:
o Este enfoque ha demostrado resultados satisfactorios en el proyecto
KDE y permite a sus miembros producir la cantidad mas grande de
documentacion traducida y actualizada que conozco.
o Los traductores pueden seguir usando el contexto para traducir, ya
que las cadenas del fichero PO estan en el mismo orden que las del
documento original. Por ello, traducir secuencialmente facilita la
comparacion use o no po4a. Y en cualquier caso, la mejor forma de
obtener el contexto sigue siendo convertir el documento a un formato
imprimible, ya que los textos formateados son, en mi opinion,
ilegibles.
o Este enfoque es el que usan los traductores profesionales. Estoy de
acuerdo en que ellos tienen diferentes objetivos que los traductores
de codigo abierto. Por ejemplo, la actualizacion es habitualmente
menos importante para ellos ya que el contenido cambia muy poco.
'cPorqu'e no realizar las divisiones a nivel de oraci'on (o m'as peque~nas)?
A veces las herramientas de traduccion profesionales dividen los
documentos a nivel de frases para maximizar la reusabilidad de las
traducciones previas, y acelerar el proceso. El problema es que la
misma frase puede tener varias traducciones, dependiendo del contexto.
Los parrafos son por definicion mas largos que las frases. Con un poco
de suerte se puede asegurar que si se tiene el mismo parrafo en dos
documentos, tendran el mismo significado (y traduccion), sin importar
el contexto en cada caso.
Dividirlo en partes mas pequenas que frases seria muy malo. Podria
tomar mucho tiempo explicar el motivo aqui, pero si le interesa puede
consultar la pagina de manual de Locale::Maketext::TPJ13(3pm) (que
viene con la documentacion de Perl), por ejemplo. Brevemente, cada
idioma tiene sus reglas de sintaxis especificas, y no hay forma de
construir frases encajando partes de frases para todos los idiomas
existentes (incluso para 5 de los 10 idiomas mas hablados, o incluso
menos).
'cPorqu'e no se pone el original como comentario junto con la traducci'on (o
de otra forma)?
A simple vista, gettext no parece estar adaptado a todos los tipos de
traducciones. Por ejemplo, no parecia adaptado a debconf, la interfaz
que usan todos los paquetes de Debian para sus interacciones con el
usuario durante la instalacion. En ese caso, los textos a traducir eran
muy cortos (una docena de lineas para cada paquete) y era muy dificil
poner la traduccion en un fichero especifico ya que tiene que estar
disponible antes de la instalacion del paquete.
Es por ello que el desarrollador de debconf decidio implementar otra
solucion, donde las traducciones se situasen en el mismo fichero que el
original. Esto es bastante atractivo. Uno podria incluso desear hacerlo
en XML, por ejemplo. Tendria esta aspecto:
<section>
<title lang="en">My title</title>
<title lang="es">Mi titulo</title>
<para>
<text lang="en">My text.</text>
<text lang="es">Mi texto.</text>
</para>
</section>
Pero fue tan problematico que se termino usando una implementacion
basada en PO. En el fichero, solo se puede editar el original, y las
traducciones se deben hacer en los ficheros PO extraidos de la
plantilla original (y devueltos al paquete en tiempo de compilacion).
El sistema antiguo se considero obsoleto debido a varios problemas:
o problemas de mantenimiento
Si varios traductores envian un parche a la vez, fusionarlos es
dificil.
cComo detectaria los cambios en el original que se deban aplicar a
las traducciones? Para poder usar diff, se debe tener en cuenta que
version del original se tradujo. Es decir, necesita un fichero PO
en su fichero ;)
o problemas de codificacion
La solucion es viable cuando solo se utilizan idiomas europeos,
pero la introduccion del Coreano, Ruso y/o Arabe realmente complica
el asunto. La solucion seria UTF, pero aun hay algunos problemas
con el.
Ademas, estos problemas son dificiles de detectar (es decir, solo
los lectores Coreanos detectaran que falla la codificacion del
Coreano [por culpa del traductor ruso])
gettext soluciona todos estos problemas a la vez.
,iPero gettext no se dise~n'o para este uso!
Es cierto, pero hasta el momento nadie ha propuesto una solucion mejor.
La unica alternativa conocida es la traduccion manual, con todos los
problemas de mantenimiento.
'cQu'e hay de las otras herramientas de traducci'on de documentaci'on que usan
gettext?
Hasta donde yo se, solo hay dos de ellas:
poxml
Esta es la herramienta desarrollada por la gente de KDE para tratar
DocBook XML. Me parece que este fue el primer programa que extrajo
cadenas de texto a traducir desde la documentacion a ficheros PO, e
inyectarlas de vuelta despues de la traduccion.
Unicamente puede tratar XML, y solo un DTD en particular. Estoy
bastante insatisfecho con el tratamiento que hacen de las listas,
que terminan en un unico msgid. Cuando la lista crece, el bloque se
hace dificil de tratar.
po-debiandoc
Este programa hecho por Denis Barbier es un tipo de precursor del
modulo SGML de po4a, que mas o menos lo deja obsoleto. Como su
nombre indica, unicamente trata el DTD de DebianDoc, que es mas o
menos un DTD anticuado.
Las principales ventajas de po4a sobre ellos son la facilidad de
adicion de contenidos extra (que es aun peor ahi) y la habilidad de
realizar la gettextizacion.
Educar a los desarrolladores sobre la traducci'on
Al intentar traducir documentacion o programas, se puede encontrar con
tres tipos de problemas; linguisticos (no todo el mundo habla dos
lenguas), tecnicos (por eso existe po4a) y relacionales/humanos. No
todos los desarrolladores entienden la necesidad de traducir las cosas.
Incluso los concienciados podrian ignorar como se facilita el trabajo a
los traductores. Para ayudar en este tema, po4a trae bastante
documentacion a la que se puede acudir.
Otro punto importante es que cada fichero traducido empieza con un
breve comentario que indica que es el fichero, y como usarlo. Esto
deberia ayudar a los pobres desarrolladores que sufren avalanchas de
ficheros en diferentes idiomas que no entienden, y ayudarles a
tratarlos correctamente.
En el proyecto po4a, la documentacion traducida ya no se considera como
ficheros de fuentes. Como los ficheros SGML son habitualmente ficheros
de fuentes, es un fallo habitual. Es por ello que todos los ficheros
presentan esta cabecera:
| *****************************************************
| * GENERATED FILE, DO NOT EDIT *
| * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
| *****************************************************
|
| This file was generated by po4a-translate(1). Do not store it (in VCS,
| for example), but store the PO file used as source file by po4a-translate.
|
| In fact, consider this as a binary, and the PO file as a regular source file:
| If the PO gets lost, keeping this translation up-to-date will be harder ;)
Asi mismo, los ficheros PO regulares de gettext solo necesitan ser
copiados al directorio po/. Pero 'este no es el caso de los PO tratados
por po4a. Aqui el mayor riesgo es que el desarrollador elimine las
traducciones existentes del programa con la traduccion de su
documentacion. (Ambos no se pueden almacenar en el mismo fichero PO,
porque el programa necesita instalar su traduccion en un fichero mo,
mientras que la documentacion solo utiliza su traduccion en tiempo de
compilacion). Es por esto que los ficheros PO producidos por el modulo
po-debiandoc contienen la siguiente cabecera:
#
# ADVISES TO DEVELOPERS:
# - you do not need to manually edit POT or PO files.
# - this file contains the translation of your debconf templates.
# Do not replace the translation of your program with this !!
# (or your translators will get very upset)
#
# ADVISES TO TRANSLATORS:
# If you are not familiar with the PO format, gettext documentation
# is worth reading, especially sections dedicated to this format.
# For example, run:
# info -n '(gettext)PO Files'
# info -n '(gettext)Header Entry'
#
# Some information specific to po-debconf are available at
# /usr/share/doc/po-debconf/README-trans
# or http://www.debian.org/intl/l10n/po-debconf/README-trans
#
RESUMEN de las ventajas de la metodolog'ia basada en gettext
o Las traducciones no se guardan junto con el original, lo que hace
posible la deteccion de traducciones anticuadas.
o Las traducciones se guardan en ficheros separados unos de otros, lo
que impide que traductores de diferentes idiomas interfieran en su
trabajo tanto al enviar parches, como a nivel de codificacion de
ficheros.
o Esta basado internamente en gettext (pero po4a ofrece una interfaz
muy simple de forma que no necesita entender el funcionamiento
interno para usarlo). De esa forma no tenemos que reinventar la
rueda, y debido a su uso extendido podemos imaginar que estas
herramientas estan mas o menos libres de fallos.
o Para el usuario final nada ha cambiado (aparte de que, probablemente,
las traducciones estarian mejor actualizadas :). El fichero de
documentacion resultante es exactamente el mismo.
o No hace falta que los traductores aprendan una nueva sintaxis de
fichero, y sus editores favoritos de ficheros PO (como el modo PO de
Emacs, Lokalize o Gtranslator) serviran a la perfeccion.
o gettext ofrece una manera simple de conseguir estadisticas sobre que
esta hecho, que se deberia repasar y actualizar, y lo que queda por
hacer. Puede encontrar algunos ejemplos en estas direcciones:
- http://kv-53.narod.ru/kaider1.png
- http://www.debian.org/intl/l10n/
Pero no todo es bonito, y este enfoque tambien tiene algunas
desventajas con las que debemos lidiar.
o Los apendices son... extranos a primera vista.
o No puede adaptar el texto traducido a su gusto, como dividir parrafos
por aqui, y juntar esos dos alli. Pero por supuesto, si hay algun
problema con el original deberia remitir un informe de fallo.
o Incluso con una interfaz facil, sigue siendo una nueva herramienta
que la gente debe aprender.
Uno de mis suenos es integrar de alguna forma po4a con Gtranslator o
Lokalize. Cuando se abre un fichero SGML, se extraen las cadenas
automaticamente. Al guardar se guarda un fichero SGML traducido en el
disco. Si consiguieramos hacer un modulo para MS Word (TM) (o al
menos RTF) incluso podrian usarlo traductores profesionales.
AUTORES
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
