po4a

Autres langues

Langue: es

Autres versions - même langue

Version: 2008-11-05 (ubuntu - 08/07/09)

Autres sections - même nom

Section: 7 (Divers)

Sommaire

NOMBRE

po4a - marco de trabajo para traducir documentaciA~Xn y otro material

IntroducciA~Xn

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.

Tabla de contenidos

Este documento estA~X organizado de la siguiente forma:
1 AXPorquA~X debo usar po4a? AXPara quA~X sirve?
Este capA~tulo introductorio explica la motivaciA~Xn del proyecto y su filosofA~a. DeberA~a leerlo primero si estA~X en el proceso de evaluaciA~Xn de po4a para sus propias traducciones.
2 AXCA~Xmo usar po4a?
Este capA~tulo es como un manual de referencia, dA~Xnde se intenta contestar las preguntas de los usuarios, y se le ofrece una idea general del proceso. Le introduce al mA~Xtodo de trabajo con po4a y sirve como documentaciA~Xn introductoria de las herramientas especA~ficas.
AXCA~Xmo empezar una nueva traducciA~Xn?
AXCA~Xmo transformar la traducciA~Xn de vuelta a un archivo de documentaciA~Xn?
AXCA~Xmo actualizar una traducciA~Xn con po4a?
AXCA~Xmo convertir una traducciA~Xn ya existente a po4a?
AXCA~Xmo aA~Xadir texto extra en las traducciones (como el nombre del traductor)?
AXCA~Xmo hacer todo esto en una sola invocaciA~Xn a programa?
3 AXCA~Xmo funciona?
Este capA~tulo ofrece una breve explicaciA~Xn del funcionamiento interno de po4a, de forma que se pueda sentir mA~Xs seguro para ayudarnos a mantenerlo y mejorarlo. TambiA~Xn le puede ayudar a entender porquA~X no hace lo que esperaba, y cA~Xmo solucionar sus problemas.
4 Preguntas Frecuentes
Este capA~tulo agrupa las Preguntas Frecuentes. De hecho, la mayoria de preguntas actuales se pueden formular asA~: ``AXPorquA~X se ha diseA~Xado asA~, y no asA~?'' Si piensa que po4a no es la soluciA~Xn ideal para la traducciA~Xn de documentaciA~Xn, deberA~a considerar leer A~Xsta secciA~Xn. Si no responde su pregunta, contacte con nosotros en la lista de correo <po4a-devel@lists.alioth.debian.org>. Queremos escuchar su opiniA~Xn.
5 Notas especA~ficas de los mA~Xdulos
Este capA~tulo presenta los puntos especA~ficos de cada mA~Xdulo desde el punto de vista tanto del traductor como del autor original. Lea esto para aprender la sintaxis que se encontrarA~X cuando traduzca textos con un mA~Xdulo, o las reglas que debe seguir en el documento original para facilitar la vida del traductor.

Actualmente A~Xsta secciA~Xn no forma parte de A~Xste documento. En realidad estA~X en la documentaciA~Xn de cada mA~Xdulo. Esto permite asegurar que la informaciA~Xn estA~X actualizada al mantener la documentaciA~Xn y el cA~Xdigo juntos.

6 Fallos conocidos y caracterA~sticas solicitadas
Unos cuantos aA~Xn :(

AXPorquA~X debo usar po4a? AXPara quA~X sirve?

Me gusta la idea del software de cA~Xdigo abierto, lo que hace posible que todo el mundo pueda acceder al software y a su cA~Xdigo fuente. Pero al ser francA~Xs soy bien consciente de que la licencia no es la A~Xnica restricciA~Xn de la libertad del software: los programas libres no traducidos son inservibles para gente de habla no inglesa, y todavA~a queda bastante faena para hacerlos disponibles para todos.

La percepciA~Xn de A~Xsta situaciA~Xn por los responsables del software libre ha mejorado drA~Xsticamente recientemente. Nosotros, como traductores, hemos ganado la primera batalla y hemos convencido a todo el mundo de la importancia de las traducciones. Pero por desgracia, A~Xsta era la parte fA~Xcil. Ahora tenemos que ponernos en marcha y empezar a traducir.

Actualmente, el software libre se beneficia de un nivel decente de traducciA~Xn, gracias al maravilloso paquete 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 en tiempo de ejecuciA~Xn para mostrar los mensajes traducidos al usuario.

Pero la situaciA~Xn es bastante diferente para la documentaciA~Xn. Demasiado a menudo, la documentaciA~Xn traducida no es suficientemente visible (no se distribuye como parte del programa), sA~Xlo lo estA~X parcialmente, o no estA~X actualizada. La A~Xltima situaciA~Xn es la peor de todas. Para los usuarios, las traducciones anticuadas pueden ser peor que si no existiera la traducciA~Xn, si describen viejos comportamientos del programa que ya no se usan.

El problema a solucionar

Traducir documentaciA~Xn no es muy difA~cil por sA~ solo. Los textos son bastante mA~Xs largos que los mensajes de programa, y por lo tanto, tardan mA~Xs en traducirse, pero no se necesitan conocimientos tA~Xcnicos para hacerlo. La parte difA~cil llega cuando se debe mantener el trabajo. Detectar quA~X partes han cambiado y se necesitan actualizar es muy difA~cil, lleva a errores y es bastante desagradable. Creo que A~Xsto explica porquA~X tantas de las traducciones de documentaciA~Xn que hay por ahA~ estA~Xn anticuadas.

Las respuestas de po4a

Luego, el objetivo de po4a es hacer la traducciA~Xn de documentaciA~Xn mantenible. La idea es reusar la metodologA~a de gettext en A~Xste nuevo campo. Como en gettext, los textos se extraen de su localizaciA~Xn original, para ser presentados en un formato uniforme a los traductores. Las herramientas clA~Xsicas de gettext ayudan a actualizar el trabajo cuando aparece una nueva versiA~Xn del original. Pero a diferencia del modelo clA~Xsico de gettext, las traducciones son reinyectadas en la estructura del documento original de forma que pueden ser procesadas y distribuidas igual que la versiA~Xn inglesa.

Gracias a esto, descubrir quA~X partes del documento han cambiado y se necesita actualizar se vuelve muy fA~Xcil. Otro punto fuerte es que las herramientas harA~Xn prA~Xcticamente toda la faena cuando la estructura del documento original se reorganice y cuando algunos capA~tulos se muevan, se junten o se separen. Al extraer el texto a traducir de la estructura del documento, tambiA~Xn le mantiene lejos de la complejidad del formateo de texto y reduce las oportunidades de daA~Xar el documento (aunque no le prevenga completamente de hacerlo).

Por favor, lea tambiA~Xn las ``Preguntas Frecuentes'' mA~Xs abajo en A~Xste documento para una lista mA~Xs completa de ventajas y desventajas de esta soluciA~Xn.

Formatos soportados

Actualmente se han implementado satisfactoriamente algunos tipos de formatos de texto:

nroff

The good old manual pages' format, used by so much programs out there. The po4a support is very welcome here since this format is somewhat difficult to use and not really friendly to the newbies. The Locale::Po4a::Man(3pm) module also supports the mdoc format, used by the BSD man pages (they are also quite common on Linux).

pod

Este es el formato de DocumentaciA~Xn Online de Perl. El lenguaje y sus mismas extensiones estA~Xn documentadas asA~, igual que la mayorA~a de scripts de Perl. Hace muy fA~Xcil mantener la documentaciA~Xn cerca del cA~Xdigo al mezclarlos en el mismo archivo. Facilita la vida del programador, pero por desgracia, no la del traductor.

sgml

Aunque hoy en dA~a casi haya sido sustituido por XML, A~Xste formato aA~Xn es usado habitualmente para documentos mA~Xs extensos que algunas pantallas. Este permite hacer libros completos. Actualizar una traducciA~Xn de documentos tan largos puede ser realmente un infierno. A menudo diff se vuelve inA~Xtil cuando se ha reindentado el texto original despuA~Xs de la actualizaciA~Xn. Afortunadamente, po4a le puede ayudar en ese proceso.

Actualmente, sA~Xlo estA~Xn soportados los DTDs de debiandoc y de docbook, pero aA~Xadir soporte para uno nuevo es realmente fA~Xcil. Incluso es posible usar po4a en un dtd desconocido de sgml sin cambiar el cA~Xdigo, pasando la informaciA~Xn necesaria en la lA~nea de comandos. Consulte Locale::Po4a::Sgml(3pm) para mA~Xs detalles.

TeX / LaTeX

The LaTeX format is a major documentation format used in the Free Software world and for publications. The Locale::Po4a::LaTeX(3pm) module was tested with the Python documentation, a book and some presentations.

texinfo

All the GNU documentation is written in this format (that's even one of the requirement to become an official GNU project). The support for Locale::Po4a::Texinfo(3pm) in po4a is still at the beginning. Please report bugs and feature requests.

xml

The XML format is a base format for many documentation formats.

Currently, the docbook DTD is supported by po4a. See Locale::Po4a::Docbook(3pm) for details.

otros

Po4a tambiA~Xn puede tratar algunos formatos raros o especA~ficos, tal como la documentaciA~Xn de las opciones de compilaciA~Xn del kernel 2.4.x o los diagramas producidos por la herramienta dia. AA~Xadir uno nuevo acostumbra a ser una tarea muy fA~Xcil y la tarea principal es conseguir un analizador para su formato. Consulte Locale::Po4a::TransTractor(3pm) para mA~Xs informaciA~Xn.

Formatos no soportados

Unfortunately, po4a still lacks support for several documentation formats.

There is a whole bunch of other formats we would like to support in po4a, and not only documentation ones. Indeed, we aim at plugging all ``market holes'' left by the classical gettext tools. It encompass package descriptions (deb and rpm), package installation scripts questions, package changelogs, and all specialized file formats used by the programs such as game scenarios or wine resource files.

AXCA~Xmo usar po4a?

Este capA~tulo es como un manual de referencia, dA~Xnde se intenta contestar las preguntas de los usuarios, y se le ofrece una idea general del proceso. Le introduce al mA~Xtodo de trabajo con po4a y sirve como documentaciA~Xn introductoria de las herramientas especA~ficas.

VisiA~Xn esquemA~Xtica

El siguiente esquema le da una visiA~Xn global del proceso de traducciA~Xn de documentaciA~Xn usando po4a. No se asuste por su aparente complejidad, eso es debido a que aquA~ se representa el proceso completo. Una vez haya convertido su proyecto a po4a, sA~Xlo es relevante la parte derecha del grA~Xfico. En este ejemplo se habla de sgml, pero es aplicable a todos los mA~Xdulos. Cada parte del dibujo se detallarA~X en las prA~Xximas secciones. 
   fr.sgml  original.sgml ---->--------+------>----------->-------+
      |         |                      |                          |
      V         V        { actualizaciA~Xn del original }           |
      |         |                      |                          |
      +--<---<--+                      V                          |
      |         |              original.new.sgml----->------->----+
      V         V                      |                          |
   [po4a-gettextize]      +--->---->---+                          |
      |         |         |            V                          |
      |         |         |     [po4a-updatepo]                   |
      |         V         ^            |                          V
      V    original.pot   |            V                          |
      |         |         |          fr.po                        |
      |         |         |         (difuso)                      |
      |   { traducciA~Xn }  |            |                          |
      |         |         ^            V                          V
      |         |         |     {ediciA~Xn manual}                  |
      V         V         |            |                          |
      |         |         |            V                          V
      |         |         +--<----   fr.po       apA~Xndice   original.sgml
      +---->----+---->------->--->  (al dia)    (opcional)    (al dA~a) 
                                       |            |             |
                                       v            v             v
                                       +------>-----+------<------+
                                                    |
                                                    v
                                            [po4a-translate]
                                                    |
                                                    V
                                                 fr.sgml
                                                (al dia)

En la parte izquierda se muestra la conversiA~Xn de una traducciA~Xn que no usa po4a a este sistema. Arriba de la parte derecha se representa la acciA~Xn del autor original (actualizar la documentaciA~Xn). En medio de la parte derecha se simbolizan las acciones automA~Xticas de po4a. Se extrae el nuevo material, y se compara con la traducciA~Xn existente. Se encuentran las partes que no han cambiado, y se usa la traducciA~Xn previa. Las partes parcialmente modificadas tambiA~Xn se conectan con la traducciA~Xn anterior, pero se aA~Xade un marcador indicando que la traducciA~Xn se debe actualizar. La parte de abajo de la figura muestra como se construye el documento formateado.

Actualmente, como traductor, la A~Xnica operaciA~Xn manual que debe hacer es la parte marcada como {ediciA~Xn manual}. Si, lo siento, pero po4a le ayuda a traducir. No traduce nada sA~Xlo...

AXCA~Xmo empezar una nueva traducciA~Xn?

Esta secciA~Xn presenta los pasos necesarios para iniciar una nueva traducciA~Xn con po4a. Los refinamientos involucrados en la conversiA~Xn de un proyecto existente al este sistema se detallan en la secciA~Xn pertinente.

Para iniciar una nueva traducciA~Xn utilizando po4a, debe seguir los siguientes pasos:

-
Extraer el texto que se tiene que traducir del documento original a un nuevo archivo pot (el formato de gettext). Para hacerlo puede usar el programa po4a-gettextize asA~: 
   $ po4a-gettextize -f <formato> -m <principal.doc> -p <traducciA~Xn.pot>

<formato> es naturalmente el formato usado en el documento <principal.doc>. Tal como era de esperar, la salida va a <traducciA~Xn.pot>. Consulte po4a-gettextize(1) para mA~Xs detalles sobre las opciones existentes.

-
Ahora toca traducir lo que se deba. Para eso, cambie el nombre del fichero pot a doc.XX.po, por ejemplo (donde XX es el cA~Xdigo ISO639 del idioma al que estA~X traduciendo, por ejemplo ``fr'' para el francA~Xs), y edite el fichero resultante. A menudo es buena idea no llamar al fichero XX.po para evitar confusiones con la traducciA~Xn de los mensajes de programa, pero eso es cosa suya. No se olvide de actualizar las cabeceras de los ficheros po, son importantes.

La traducciA~Xn en sA~ misma se puede hacer con el modo po de Emacs o kbabel (basado en KDE) o gtranslator (basado en GNOME), o cualquier programa que prefiera. Incluso el clA~Xsico vi puede bastar, aunque no tenga un modo especializado para esta tarea.

Si quiere aprender mA~Xs, definitivamente debe consultar la documentaciA~Xn de gettext, disponible en el paquete gettext-doc.

AXCA~Xmo transformar la traducciA~Xn de vuelta a un archivo de documentaciA~Xn?

Una vez haya terminado la traducciA~Xn, querrA~X obtener la documentaciA~Xn traducida para distribuirla a los usuarios junto con el original. Para eso, utilice el programa po4a-translate(1) asA~ (donde XX es el cA~Xdigo del idioma): 
   $ po4a-translate -f <format> -m <master.doc> -p <doc.XX.po> -l <XX.doc>

Igual que antes, <formato> es el formato usado en el documento <principal.doc>. Pero esta vez el fichero po pasado con el parA~Xmetro -p es parte de la entrada. Esta es su traducciA~Xn. La salida va a <XX.doc>

Consulte po4a-translate(1) para mA~Xs detalles.

AXCA~Xmo actualizar una traducciA~Xn con po4a?

Para actualizar su traducciA~Xn cuando el fichero original cambie, use el programa po4a-updatepo(1) asA~: 
   $ po4a-updatepo -f <formato> -m <nuevo_original.doc> -p <existente.XX.po>

(Consulte po4a-updatepo(1) para mA~Xs detalles)

Naturalmente, los nuevos pA~Xrrafos del documento no se traducirA~Xn mA~Xgicamente en el fichero "po" con esta operaciA~Xn, y necesitarA~X actualizar el fichero "po" manualmente. Asimismo, puede tener que rehacer las traducciones de los pA~Xrrafos que se hayan modificado un poco. Para asegurar que no se olvidarA~X ninguna, se marcan como ``difusas'' durante el proceso, y deberA~X quitar la marca manualmente antes que se pueda usar la traducciA~Xn en po4a-translate. Igual que para la traducciA~Xn inicial, aquA~ lo mejor es usar su editor po favorito.

Una vez su fichero "po" estA~X otra vez actualizado, sin ninguna cadena por traducir ni cadenas difusas, puede generar el fichero de documentaciA~Xn traducido, tal como se ha explicado en la secciA~Xn anterior.

AXCA~Xmo convertir una traducciA~Xn ya existente a po4a?

Seguramente usted acostumbraba a traducir manualmente el documento felizmente hasta que llegA~X una reorganizaciA~Xn del documento original. Entonces, despuA~Xs de algunos intentos fracasados con diff o herramientas similares, quiere pasarse a po4a. Pero por supuesto, no quiere perder su proceso de traducciA~Xn. No se preocupe, las herramientas po4a tambiA~Xn tienen en cuenta este caso, se llama gettextizaciA~Xn.

La condiciA~Xn mA~Xs importante es que tanto el documento traducido como el original tengan la misma estructura de forma que las herramientas puedan encajar los contenidos correctamente.

Si estA~X de suerte (es decir, si las estructuras de ambos documentos encajan a la perfecciA~Xn), todo funcionarA~X a la perfecciA~Xn y habrA~X terminado en unos segundos. En caso contrario, deberA~X entender porquA~X este proceso tiene un nombre tan feo, y deberA~a estar preparado para un poco de faena sucia. De cualquier forma, recuerde que este es el precio a pagar para conseguir luego la comodidad de po4a. Y la mejor parte es que solo deberA~X hacer esto una vez.

No puedo emfatizarlo mA~Xs. Para facilitar el proceso, es importante encontrar la versiA~Xn exacta que se usA~X en la traducciA~Xn. La mejor situaciA~Xn se da cuando se anotA~X quA~X revisiA~Xn del cvs se usA~X para la traducciA~Xn y no se modificA~X durante el proceso de traducciA~Xn, de forma que pueda usarla.

No funcionarA~X bien si usa el texto original actualizado con una traducciA~Xn vieja. Es un proceso posible, pero mA~Xs difA~cil, y realmente se debe evitar en la medida que sea posible. De hecho, imagino que si no consigue encontrar el texto original, la mejor soluciA~Xn es encontrar a alguien que haga la gettextizaciA~Xn por usted (pero por favor, que no sea yo ;).

QuizA~X sea demasiado catastrA~Xfico. Aunque las cosas vayan mal, sigue siendo mucho mA~Xs rA~Xpido que traducirlo todo otra vez. Yo hice la gettextizaciA~Xn de la traducciA~Xn al francA~Xs existente de la documentaciA~Xn de Perl en un dA~a, a pesar de que las cosas fueron mal. Eran mA~Xs de dos megabytes de texto, y una traducciA~Xn nueva hubiera podido durar como mA~nimo meses.

PermA~tame explicar primero las bases del proceso, y luego ya volveremos a los trucos para conseguirlo cuando el proceso vaya mal. Para facilitar la comprensiA~Xn, se toma otra vez como ejemplo el mA~Xdulo sgml, pero no importa el formato usado:

Una vez haya conseguido el original viejo, la gettextizaciA~Xn puede ser tan fA~Xcil como:

  $ po4a-gettextize -f <format> -m <old.original> -l <old.translation> -p <doc.XX.po>

Si estA~X de suerte, eso es todo. Ha convertido su vieja traducciA~Xn a po4a y ya puede empezar con la tarea de actualizaciA~Xn. Simplemente siga el proceso explicado unas secciones antes para sincronizar su fichero po con el documento original mA~Xs nuevo, y actualice la traducciA~Xn segA~Xn convenga.

Tenga en cuenta que aunque parezca que todo ha ido bien, aA~Xn 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 traducciA~Xn se refiere al original dado. Es por eso que las cadenas se marcan como ``difusas'' durante el proceso. Debe comprobar cuidadosamente cada cadena antes de eliminar la marca.

A menudo las estructuras de los documentos no encajan a la perfecciA~Xn, impidiendo a po4a-gettextize realizar su tarea. Llegados a este punto, todo el juego se traslada a la ediciA~Xn de los ficheros para hacer encajar sus malditas estructuras.

Le puede ayudar leer la secciA~Xn ``GettextizaciA~Xn: AXCA~Xmo funciona?'' de mA~Xs abajo. La comprensiA~Xn del funcionamiento interno del proceso le ayudarA~X a hacerlo funcionar. El punto bueno es que po4a-gettextize da mucha informaciA~Xn cuando algo no va bien. Primero, apunta dA~Xnde se encontrA~X la discrepancia de estructuras en los documentos. Luego le mostrarA~X las cadenas que no encajan, su posiciA~Xn en el texto, y el tipo de cada una. AdemA~Xs, el fichero po generado hasta el momento se guardarA~X en gettextization.failed.po.

-
Elimine todas las partes extra de las traducciones, como secciones donde se especifique el nombre del traductor, o los agradecimientos de gente que colaborA~X con la traducciA~Xn. Los apA~Xndices, descritos en la siguiente secciA~Xn, le permitirA~Xn volver a aA~Xadir estos contenidos.
-
No dude de editar tanto el original como la traducciA~Xn. Lo mA~Xs importante es conseguir el fichero po. Ya tendrA~X tiempo de actualizarlo luego. Una vez dicho esto, es preferible editar la traducciA~Xn cuando se puedan editar ambos, ya que esto facilita las cosas una vez se termine la gettextizaciA~Xn.
-
Si es necesario, elimine algunas partes del original si no estaban traducidas. Cuando mA~Xs adelante sincronice el po con el documento, volverA~Xn por sA~ solas.
-
Si cambiA~X un poco la estructura (para juntar dos pA~Xrrafos, o partir alguno), deshaga esos cambios. Si se trata de un asunto con el original, debe informar al autor original del texto. Arreglarlo solo en la traducciA~Xn solo ofrece la soluciA~Xn a una parte de la comunidad. Y ademA~Xs, es imposible cuando se usa po4a ;)
-
A veces el contenido del pA~Xrrafo encaja, pero su tipo no. Arreglar eso depende mucho del formato. En pod y nroff, a menudo es culpa de que una de las dos lA~neas empieza con un espacio y la otra no. En estos formatos, este pA~Xrrafo no podrA~a justificarse y se volverA~a de un tipo diferente. Simplemente elimine el espacio y ya estA~X. TambiA~Xn puede tratarse de un error tipogrA~Xfico en el nombre del tag.

AdemA~Xs, dos pA~Xrrafos pueden juntarse en el pod cuando la lA~nea de separaciA~Xn contiene algunos espacios, o cuando no hay una lA~nea de separaciA~Xn antes de la lA~nea =item y del contenido del elemento.

-
A veces, hay una desincronizaciA~Xn entre archivos, y la traducciA~Xn se encaja con un pA~Xrrafo original equivocado. Este es un signo de que ya habA~a un problema antes de juntar los ficheros. Compruebe gettextization.failed.po para ver cuando empieza la desincronizaciA~Xn, y arrA~Xglelo allA~.
-
A veces le puede dar la impresiA~Xn que po4a se comiA~X algunas partes del texto, ya sea del original o de la traducciA~Xn. gettextization.failed.po indica que ambos encajaban correctamente, y luego fallA~X porque intentA~X encajar un pA~Xrrafo con el anterior o el posterior al correcto, como si el correcto hubiera desaparecido. Maldiga po4a como yo hice la primera vez que me pasA~X. Abundantemente.

Esta situaciA~Xn se debe a que el mismo pA~Xrrafo se repite a lo largo del documento. En ese caso, no se crea una nueva entrada en el fichero po, sino que se le aA~Xade una nueva referencia a la ya existente.

Por lo tanto, cuando el mismo pA~Xrrafo aparece dos veces en el original pero no estA~X traducido exactamente igual cada vez, tendrA~X esa sensaciA~Xn de que desapareciA~X un pA~Xrrafo del original. Simplemente elimine la nueva traducciA~Xn. Si cree que la segunda traducciA~Xn es mejor, quA~tela de donde estA~X, y sustituya a la primera.

En el caso contrario, si hay dos pA~Xrrafos parecidos pero diferentes que se tradujeron de la misma forma, le puede dar la impresiA~Xn de que desapareciA~X un pA~Xrrafo de la traducciA~Xn. La soluciA~Xn es aA~Xadir una cadena estA~Xpida al pA~Xrrafo original (algo como ``soy diferente'') para solucionarlo. No se asuste. Estas cosas desaparecerA~Xn durante la sincronizaciA~Xn, y cuando el texto aA~Xadido sea suficientemente corto, gettext encajara su traducciA~Xn con el texto existente (marcA~Xndolo como difuso, pero no importa, ya que todas las cadenas se marcan como difusas durante la gettextizaciA~Xn).

Con un poco de suerte estos trucos le ayudarA~Xn a realizar su gettextizaciA~Xn y a obtener su preciado fichero po. Ahora estA~X preparado para sincronizar su fichero y empezar la traducciA~Xn. Tenga en cuenta que en textos grandes la primera sincronizaciA~Xn puede tardar mucho tiempo.

Por ejemplo, el primer po4a-updatepo de la traducciA~Xn al francA~Xs de la documentaciA~Xn de Perl (un fichero po de 5.5 Mb) tomA~X alrededor de dos dias enteros en una mA~Xquina G5 a 1Ghz. Si, 48 horas. Pero las siguientes veces tan solo tardaba una docena de segundos en mi viejo portatil. Eso es porque la primera vez, la mayorA~a de msgids del fichero po no encajan con ninguno de los del fichero pot. Eso obliga a gettext a buscar la cadena mA~Xs parecida usando un costoso algoritmo de proximidad de cadenas.

AXCA~Xmo aA~Xadir texto extra en las traducciones (como el nombre del traductor)?

Debido al uso de gettext, esto se vuelve mA~Xs difA~cil en po4a que antes, que simplemente se editaba el nuevo fichero paralelamente al original. Pero sigue siendo posible, gracias a los llamados apA~Xndices.

Para ayudar a la comprensiA~Xn, considere los apA~Xndices como unos parches aplicados al documento traducido despuA~Xs del proceso. Son bastante diferentes que los parches habituales (solo tienen una lA~nea de contexto, que puede incluir una expresiA~Xn regular de perl, y A~Xnicamente puede aA~Xadir texto, sin eliminar nada), pero las funcionalidades son las mismas.

Su objetivo es permitir al traductor aA~Xadir contenido extra al documento, que no es traducciA~Xn del documento original. El uso mA~Xs habitual es aA~Xadir una secciA~Xn sobre la traducciA~Xn en sA~ misma, listando los colaboradores y explicando como informar de los errores de la traducciA~Xn.

Los apA~Xndices se deben proporcionar como ficheros a parte. La primera lA~nea forma una cabecera que indica el lugar del documento resultante donde se debe colocar. El resto del fichero de apA~Xndice se aA~XadirA~X tal cual en la posiciA~Xn determinada del documento resultante.

La cabecera tiene una sintaxis muy rA~gida: debe empezar con la cadena ``PO4A-HEADER:'', seguida por una lista de campos ``llave=valor'' separados por punto y coma (;). Los espacios en blanco SON importantes. Tenga en cuenta que no puede usar el caracter punto y coma (;) en los valores, y que las comillas no ayudan.

Una vez mA~Xs, suena espantoso, pero los ejemplos de mA~Xs abajo deberA~an ayudarle a encontrar la forma de escribir la lA~nea de cabecera que necesita. Para ilustrar la discusiA~Xn, asuma que quiere aA~Xadir una secciA~Xn llamada ``Sobre esta traducciA~Xn'' despuA~Xs de la llamada ``Sobre este documento''.

AquA~ hay las posibles llaves de la cabecera:

position (obligatoria)
una expresiA~Xn regular. Se colocarA~X el apA~Xndice cerca de la lA~nea que encaje con esta expresiA~Xn regular. Tenga en cuenta que estamos hablando del documento traducido, no del original. Si hay mA~Xs de una linea que encaje (o ninguna), la adiciA~Xn fallarA~X. Siempre es mejor dar un error que insertar el apA~Xndice en el sitio equivocado.

A continuaciA~Xn, esta lA~nea se llamarA~X punto de posiciA~Xn. El punto donde se insertarA~X el apA~Xndice se llamarA~X punto de inserciA~Xn. Estos dos puntos son muy cercanos, pero no iguales. Por ejemplo, si desea insertar una nueva secciA~Xn, es mA~Xs fA~Xcil poner el punto de posiciA~Xn en el tA~tulo de la secciA~Xn anterior, y explicarle a po4a donde termina la secciA~Xn (recuerde que el punto de posiciA~Xn viene dado por la expresiA~Xn regular, que debe encajar una A~Xnica linea).

La localizaciA~Xn del punto de inserciA~Xn respecto al punto de posiciA~Xn estA~X controlado por los campos "mode", "beginboundary" y "endboundary" que se explican a continuaciA~Xn.

En nuestro caso tendrA~amos:

      position=<title>Sobre este documento</title>
mode (obligatoria)
Puede valer ``before'' (antes) o ``after'' (despuA~Xs), especificando la posiciA~Xn del apA~Xndice, relativa al punto de posiciA~Xn.

Como queremos que la nueva secciA~Xn se situe debajo de la que hemos encajado, tenemos:

      mode=after
beginboundary (usada sA~Xlo cuando mode=after, y obligatoria en este caso)
endboundary (A~dem)
ExpresiA~Xn regular que encaje el final de la secciA~Xn despuA~Xs del que va el apA~Xndice.

Cuando mode=after, el punto de inserciA~Xn estA~X despuA~Xs del punto de posiciA~Xn, pero no justamente despuA~Xs! EstA~X situado al final de la secciA~Xn que empieza en el punto de posiciA~Xn, es decir, antes o despuA~Xs de la lA~nea encajada por el parA~Xmetro "???boundary", dependiendo de si usA~X "beginboundary" o "endboundary".

En nuestro caso, podemos decidirnos por indicar el final de la secciA~Xn que encajamos aA~Xadiendo:

    endboundary=</section>

o indicar el principio de la siguiente secciA~Xn indicando:

    beginboundary=<section>

En ambos casos, se colocarA~X nuestro apA~Xndice despuA~Xs de </section> y antes de <section>. La primera opciA~Xn es mejor porque funcionarA~X aunque se reorganice el documento.

Las dos formas existen debido a que los formatos de documentaciA~Xn son diferentes. En algunos de ellos, hay una forma de marcar el final de una secciA~Xn (tal como el "</section>" que hemos usado), mientras que otros no marcan explA~citamente el final de una secciA~Xn (como en nroff). En el primer caso, es preferible encajar un boundary con el final de secciA~Xn, para que el punto de inserciA~Xn venga despuA~Xs. En el segundo caso, deberA~X encajar un boundary con el principio de la siguiente secciA~Xn para que el punto de inserciA~Xn venga justo antes suyo.

Puede parecer oscuro, pero espero que los prA~Xximos ejemplos le iluminen.

Para concluir el ejemplo usado hasta el momento, para insertar una secciA~Xn llamada "Sobre esta traducciA~Xn" despuA~Xs de la secciA~Xn "Sobre este documento" en un documento sgml, debe usar una de estas lA~neas de cabecera:
  PO4A-HEADER: mode=after; position=Sobre este documento; endboundary=</section>
  PO4A-HEADER: mode=after; position=Sobre este documento; beginboundary=<section>
Si quiere aA~Xadir algo despuA~Xs de la siguiente secciA~Xn de nroff:
   .SH "AUTORES"

Debe poner un "position" que encaje esta linea, y un "beginboundary" que encaje el principio de la siguiente secciA~Xn (es decir "^\.SH"). Entonces el apA~Xndice se aA~XadirA~X despuA~Xs del punto de posiciA~Xn e immediatamente antes de la primera lA~nea que encaje el "beginboundary". AsA~ es:

  PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH
Si desea aA~Xadir algo dentro de una secciA~Xn (como despuA~Xs de "Copyright Big Dude") en vez de aA~Xadir una secciA~Xn completa, ponga un "position" que encaje con esta lA~nea, y ponga un "beginboundary" que encaje cualquier linea.
  PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
Si desea aA~Xadir algo al final del documento, especifique un "position" que encaje cualquier linea del documento (pero sA~Xlo una lA~nea. Po4a no procederA~X si no es A~Xnica), 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 trata de expresiones regulares. Por ejemplo, si desea encajar el final de una secciA~Xn de nroff que termine con la lA~nea

   .fi

no utilice ".fi" como endboundary, porque esto encajarA~X con ``el[ fi]chero'', que obviamente no es lo que esperA~Xbamos. El endboundary correcto en este caso serA~a: "^\.fi$".

Si el apA~Xndice no va donde esperaba, pruebe pasando el parA~Xmetro -vv a las herramientas, para que le explique quA~X hace al colocar el apA~Xndice.

Ejemplo mA~Xs detallado

Documento original (en formato pod):

  |=head1 NAME
  |
  |dummy - a dummy program
  |
  |=head1 AUTHOR
  |
  |me

Luego, el siguiente apA~Xndice asegurarA~X que se aA~Xade una secciA~Xn (en espaA~Xol) sobre el traductor al final del fichero.

  |PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head
  |
  |=head1 TRADUCTOR
  |
  |yo

Para poner su apA~Xndice antes de AUTHOR, utilice la siguiente cabecera:

  PO4A-HEADER:mode=after;position=NOMBRE;beginboundary=^=head1

Esto funciona porque la siguiente linea que encaja el beginboundary /^=head1/ despuA~Xs de la secciA~Xn ``NAME'' (traducido a ``NOMBRE'' en espaA~Xol), es la que declara los autores. Por lo tanto, se colocarA~X el apA~Xndice entre ambas secciones.

AXCA~Xmo hacer todo esto en una sola invocaciA~Xn a programa?

El uso de po4a ha demostrado que puede dar lugar a errores ya que se debe llamar a dos programas diferentes en el orden adecuado (po4a-updatepo y luego po4a-translate), y cada uno necesita mA~Xs de 3 parA~Xmetros. AdemA~Xs, era difA~cil con este sistema usar solo un fichero po para todos los documentos cuando se usaba mA~Xs de un formato.

El programa po4a(1) se diseA~XA~X para solucionar esas dificultades. Una vez su proyecto se haya convertido al sistema, usted escribe un simple fichero de configuraciA~Xn explicando dA~Xnde estA~Xn los ficheros de traducciA~Xn (po y pot), dA~Xnde estA~Xn los documentos originales, sus formatos, y dA~Xnde se deben guardar las traducciones.

Luego, una simple llamada a po4a(1) con este fichero asegura que los ficheros po se sincronicen con el documento original, y que se generan correctamente los documentos traducidos. Por supuesto, le interesarA~X llamar el programa dos veces: una antes de editar el fichero po para actualizarlo, y otra para actualizar completamente los documentos traducidos. Pero sA~Xlo necesita recordar una lA~nea de comandos.

AXCA~Xmo funciona?

Este capA~tulo ofrece una breve explicaciA~Xn del funcionamiento interno de po4a, de forma que se pueda sentir mA~Xs seguro para ayudarnos a mantenerlo y mejorarlo. TambiA~Xn le puede ayudar a entender porquA~X no hace lo que esperaba, y cA~Xmo solucionar sus problemas.

VisiA~Xn general

La arquitectura de po4a es orientada a objetos (en Perl. Muy pulcro, no?). El antecesor de todas las clases analizadoras se llama TransTractor. Este extraA~Xo nombre viene del hecho de que al mismo tiempo se encarga de traducir el documento (translate) y de extraer las cadenas (extract).

MA~Xs formalmente, toma un documento a traducir ademA~Xs del fichero po que contiene las traducciones a usar para producir dos salidas separadas: Otro fichero po (resultante de la extracciA~Xn 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). AquA~ hay una representaciA~Xn grA~Xfica:

    Documento de entrada -\                        /---> Documento de salida
                           \    TransTractor::    /         (traducido)
                            +-->--  parse()  ----+
                           /                       \ 
    po de entrada --------/                         \---> po de salida
                                                            (extraA~do)

Esta pequeA~Xa estructura es el nA~Xcleo 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 funciA~Xn virtual implementada por cada mA~Xdulo. AquA~ hay un pequeA~Xo ejemplo que muestra como funciona. Analiza una lista de pA~Xrrafos, cada uno empezando con <p>

   1 sub parse {
   2   PARRAFO: while (1) {
   3     $my ($parrafo,$parraref,$linea,$lref)=("","","","");
   4     $my $primera=1;
   5     while (($linea,$lref)=$document->shiftline() && defined($linea)) {
   6       if ($line =~ m/<p>/ && !$primera--; ) {
   7         $document->unshiftline($linea,$lref);
   8
   9         $parrafo =~ s/^<p>//s;
  10         $document->pushline("<p>".$document->translate($parrafo,$parraref));
  11
  12         next PARRAFO;
  13       } else {
  14         $parrafo .= $linea;
  15         $parraref = $lref unless(length($parraref));
  16       }
  17     }
  18     return; # No tenemos la lA~nea definida? Final del archivo de entrada.
  19   }
  20 }

En la lA~nea 6, encontramos <p> por segunda vez. Esta es la seA~Xal de que hemos encontrado el siguiente pA~Xrrafo. Entonces debemos devolver la lA~nea obtenida de vuelta al documento (lA~nea 7) y enviar el pA~Xrrafo que hemos construido hacia la salida. DespuA~Xs de eliminar el <p> inicial, en la lA~nea 9, insertamos la concatenaciA~Xn del tag con la traducciA~Xn del resto del pA~Xrrafo.

Esta funciA~Xn translate() estA~X muy bien. EnvA~a su parA~Xmetro hacia el fichero po de salida (extracciA~Xn) y devuelve su traducciA~Xn como se encuentre en el fichero po de entrada (traducciA~Xn). Como es usada como parte del parA~Xmetro de pushline(), esta traducciA~Xn pasa hacia el documento de salida.

Como mola, no? Es posible construir un mA~Xdulo completo de po4a en menos de 20 lA~neas si el formato es suficientemente simple...

EncontrarA~X mA~Xs sobre esto en Locale::Po4a::TransTractor(3pm).

GettextizaciA~Xn: AXCA~Xmo funciona?

La idea aquA~ es tomar el documento original y su traducciA~Xn, y considerar que la enA~Xsima cadena extraida de la traducciA~Xn es la traducciA~Xn de la enA~Xsima 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 traducciA~Xn (de tipo 'capA~tulo') sea la traducciA~Xn de la cuarta cadena del original (de tipo 'pA~Xrrafo'). 
     Original         TraducciA~Xn
 
   capA~tulo           capA~tulo
     pA~Xrrafo            pA~Xrrafo
     pA~Xrrafo            pA~Xrrafo
     pA~Xrrafo          capA~tulo
   capA~tulo             pA~Xrrafo
     pA~Xrrafo            pA~Xrrafo

Para eso, los analizadores de po4a se utilizan tanto para el fichero original como para 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 informaciA~Xn sobre el tipo sintA~Xctico de las cadenas extraA~das en el documento (todos los que hay lo hacen, el suyo tambiA~Xn lo tiene que hacer). Luego se utiliza esa informaciA~Xn para asegurar que ambos documentos tienen la misma sintaxis. En el ejemplo anterior, nos permitirA~a detectar que la cuarta cadena es un pA~Xrrafo en un caso, y un tA~tulo de capA~tulo en el otro, y tratarlo como un error.

En teoria, la detecciA~Xn de este problema serA~a posible, y se resincronizan los ficheros luego (igual que hace diff). Pero no estA~X claro quA~X deberA~amos hacer con las cadenas antes de las desincronizaciones, y podrA~a producir malos resultados a veces. Es por eso que la implementaciA~Xn actual no intenta resincronizar nada, e informa extensamente del fallo cuando algo va mal, requiriendo la modificaciA~Xn manual de los ficheros para arreglar el problema.

Incluso con estas precauciones, las cosas se pueden estropear muy fA~Xcilmente. Es por eso que todas las traducciones encontradas asA~ se marcan como difusas, para asegurar que el traductor las repase y las corrija.

ApA~Xndices: AXCA~Xmo funcionan?

Bien, esto es muy simple. El documento traducido no se escribe directamente al disco, sino que se mantiene en memoria hasta que se aplican todos los apA~Xndices. Los algoritmos involucrados son sencillos. Buscamos una lA~nea que encaje con la expresiA~Xn regular de posiciA~Xn, e insertamos el apA~Xndice antes si estaba en mode=before. Sino, buscamos la siguiente linea que encaje en el rango e insertamos el apA~Xndice despuA~Xs de esta lA~nea si es un "endboundary" o antes de esta lA~nea si es un "beginboundary".

Preguntas Frecuentes

Este capA~tulo agrupa las Preguntas Frecuentes. De hecho, la mayoria de preguntas actuales se pueden formular asA~: ``AXPorquA~X se ha diseA~Xado asA~, y no asA~?'' Si piensa que po4a no es la soluciA~Xn ideal para la traducciA~Xn de documentaciA~Xn, deberA~a considerar leer A~Xsta secciA~Xn. Si no responde su pregunta, contacte con nosotros en la lista de correo <po4a-devel@lists.alioth.debian.org>. Queremos escuchar su opiniA~Xn.

AXPorquA~X traducir cada pA~Xrrafo por separado?

Si, en po4a, cada pA~Xrrafo se traduce por separado (de hecho, cada mA~Xdulo lo decide, pero todos los existentes lo hacen, y los suyos deben hacerlo tambiA~Xn). Hay dos ventajas principales al hacerlo asA~:
•
Cuando las partes tA~Xcnicas del documento se esconden, el traductor no se puede confundir con ellas. Como menos marcas presentemos al traductor, menos errores podrA~X hacer.
•
El hecho de cortar el documento ayuda a aislar los cambios en el documento original. Cuando se modifica el original, es fA~Xcil encontrar quA~X partes de la traducciA~Xn se necesita actualizar con este proceso.

Incluso con estas ventajas, a alguna gente no le gusta la idea de traducir cada pA~Xrrafo por separado. AquA~ hay algunas respuestas que les puedo dar:

•
Esta idea ha mostrado resultados satisfactorios en el proyecto KDE y permite a la gente producir la cantidad mA~Xs grande de documentaciA~Xn traducida y actualizada que conozco.
•
Los traductores aA~Xn pueden usar el contexto para traducir, ya que las cadenas del fichero po estA~Xn en el mismo orden que las del documento original. Traducir secuencialmente es comparable a usar po4a o no. Y en cualquier caso, la mejor forma de obtener el contexto sigue siendo el convertir el documento a un formato imprimible, ya que los textos formateados no son leA~bles, en mi opiniA~Xn.
•
Los traductores profesionales utilizan esta aproximaciA~Xn. Estoy de acuerdo en que ellos tienen diferentes objetivos que los traductores de cA~Xdigo abierto. Por ejemplo, el mantenimiento les es a menudo menos crA~tico, ya que el contenido cambia muy poco.

AXPorquA~X no realizar las divisiones a nivel de frases (o menores)?

A veces las herramientas de traducciA~Xn profesionales parten 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 pA~Xrrafos son por definiciA~Xn mA~Xs largos que las frases. Con un poco de suerte se podrA~X asegurar que si se tiene el mismo pA~Xrrafo en dos documentos, tendrA~Xn el mismo significado (y traducciA~Xn), sin importar el contexto de cada caso.

Partirlo en partes mA~Xs pequeA~Xas que frases serA~a muy malo. PodrA~a tomar mucho tiempo explicar el motivo aquA~, pero si le interesa puede consultar la pA~Xgina de manual de Locale::Maketext::TPJ13(3pm) (que viene con la documentaciA~Xn de Perl), por ejemplo. Brevemente, cada idioma tiene sus reglas de sintaxis especA~ficas, y no hay forma de construir frases encajando partes de frases para todos los idiomas existentes (incluso para 5 de los 10 idiomas mA~Xs hablados, o incluso menos).

AXPorquA~X no se pone el original como comentario junto con la traducciA~Xn (o de otra forma)?

A simple vista, gettext no parece estar adaptado a todos los tipos de traducciones. Por ejemplo, no parecA~a adaptado a debconf, la interfaz que usan todos los paquetes de Debian para sus interacciones con el usuario durante la instalaciA~Xn. En ese caso, los textos a traducir eran muy cortos (una docena de lineas para cada paquete), y era muy difA~cil poner las traducciones en un fichero especA~fico ya que tiene que estar disponible antes de la instalaciA~Xn del paquete.

Es por eso que los desarrolladores de debconf decidieron implementar otra soluciA~Xn, donde las traducciones estuvieran situadas en el mismo fichero que el original. Es bastante atractivo. Se podrA~a querer hacerlo en xml, por ejemplo. TendrA~a esta pinta:

  <section>
   <title lang="en">My title</title>
   <title lang="fr">Mon titre</title>
 
   <para>
    <text lang="en">My text.</text>
    <text lang="fr">Mon texte.</text>
   </para>
  </section>

Pero fue tan problemA~Xtico que se terminA~X usando una implementaciA~Xn basada en po. Solo se puede editar el original en el archivo, y las traducciones se deben hacer en los ficheros po extraA~dos del patrA~Xn principal (y vueltos al paquete en tiempo de compilaciA~Xn). El sistema antiguo se considerA~X obsoleto debido a varios problemas:

•
problemas de mantenimiento

Si varios traductores envA~an un parches a la vez, es difA~cil de juntarlos.

AXComo detectarA~X los cambios en el original, que se deban aplicar a las traducciones? Para poder usar diff, se debe tener en cuenta quA~X version del original se tradujo. Es decir, se necesita un fichero po en su fichero ;)

•
problemas de codificaciA~Xn

La soluciA~Xn es viable cuando solo se utilizan idiomas europeos, pero la introducciA~Xn del Koreano, Ruso y/o Arabe complica realmente la cosa. La soluciA~Xn serA~a UTF, pero aA~Xn hay algunos problemas con A~Xl.

AdemA~Xs, estos problemas son difA~ciles de detectar (es decir, solo los lectores Koreanos detectarA~Xn que falla la codificaciA~Xn del Koreano [por culpa del traductor ruso])

gettext soluciona todos estos problemas a la vez.

AXPero gettext no se diseA~XA~X para este uso!

Es cierto, pero hasta el momento nadie ha propuesto una soluciA~Xn mejor. La A~Xnica alternativa conocida es la traducciA~Xn manual, con todos los problemas de mantenimiento.

AXQuA~X hay de las otras herramientas de traducciA~Xn de documentaciA~Xn que usan gettext?

Hasta donde yo sA~X, sA~Xlo hay dos de ellas:
poxml
Esta es la herramienta desarrollada por la gente de KDE para tratar DocBook XML. Me parecec que este fue el primer programa a extraer cadenas de texto a traducir desde la documentacion a los ficheros po, e inyectarlas de vuelta despuA~Xs de la traducciA~Xn.

Unicamente puede tratar XML, y solo un DTD particular. Estoy bastante insatisfecho con el trato que hacen de las listas, que terminan en un A~Xnico msgid. Cuando la lista crece, el bloque se hace difA~cil de tratar.

po-debiandoc
Este programa hecho por Denis Barbier es un tipo de precursor del mA~Xdulo sgml de po4a, que mA~Xs o menos lo deja obsoleto. Como su nombre indica, A~Xnicamente trata el dtd de debiandoc, que ademA~Xs es un dtd anticuado.

Las principales ventajas de po4a sobre ellos son la facilidad de adiciA~Xn de contenidos extra (que es aA~Xn peor allA~) y la habilidad de realizar la gettextizaciA~Xn.

Educando a los desarrolladores sobre las traducciones

When you try to translate documentation or programs, you face three kinds of problems; linguistics (not everybody speaks two languages), technical (that's why po4a exists) and relational/human. Not all developers understand the necessity of translating stuff. Even when good willed, they may ignore how to ease the work of translators. To help with that, po4a comes with lot of documentation which can be referred to.

Otro punto importante es que cada fichero traducido empieza con un breve comentario indicando quA~X es el fichero, y como usarlo. Esto deberA~a ayudar a los pobres desarrolladores avalanchados con montones de ficheros en diferentes idiomas que no entienden, y ayudarles a tratarlos correctamente.

In the po4a project, translated documents are not source files anymore. Since sgml files are habitually source files, it's an easy mistake. That's why all files present this header:

  |       *****************************************************
  |       *           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 cvs,
  | 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 ;)

Likewise, gettext's regular po files only need to be copied to the po/ directory. But this is not the case of the ones manipulated by po4a. The major risk here is that a developer erases the existing translation of his program with the translation of his documentation. (Both of them can't be stored in the same po file, because the program needs to install its translation as an mo file while the documentation only uses its translation at compile time). That's why the po files produced by the po-debiandoc module contain the following header:

  #
  #  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 aproximaciA~Xn basada en gettext

•
The translations are not stored along with the original, which makes it possible to detect if translations become out of date.
•
The translations are stored in separate files from each other, which prevents translators of different languages from interfering, both when submitting their patch and at the file encoding level.
•
EstA~X basado internamente en "gettext" (pero "po4a" ofrece una interfaz muy simple de forma que no se necesita entender el funcionamiento interno para usarlo). De esa forma no tenemos que reinventar la rueda, y debido a su extenso uso, podemos imaginar que esas erramientas estA~Xn mA~Xs o menos libres de fallos.
•
No ha cambiado nada para el usuario final (a parte de que probablemente las traducciones estarA~Xn mejor mantenidas :). El fichero de documentaciA~Xn resultante es exactamente el mismo.
•
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, kbabel o gtranslator) servirA~Xn a la perfecciA~Xn.
•
Gettext offers a simple way to get statistics about what is done, what should be reviewed and updated, and what is still to do. Some example can be found at those addresses: 
  - http://kbabel.kde.org/img/previewKonq.png
  - http://www.debian.org/intl/l10n/

Pero no todo es bonito, y esta aproximaciA~Xn tambiA~Xn tiene algunas desventajas con las que debemos cargar.

•
Los apA~Xndices son... extraA~Xos a primera vista.
•
No puede adaptar el texto traducido a su gusto, como partir pA~Xrrafos por aquA~, y juntar esos dos allA~. Pero segA~Xn como, si estA~X en desacuerdo con el original, deberA~a informarlo como un bug, de todas formas.
•
Incluso con una interfaz fA~Xcil, sigue siendo una nueva herramienta que la gente debe aprender.

Uno de mis sueA~Xos es integrar de alguna forma po4a con gtranslator o kbabel. Cuando se abra un archivo sgml, se extraen las cadenas automA~Xticamente. Al guardar se guarda un fichero sgml traducido en el disco. Si consiguiA~Xramos hacer un mA~Xdulo para MS Word (TM) (o al menos para RTF) incluso podrA~an usarlo traductores profesionales.

Fallos conocidos y caracterA~sticas solicitadas

El asunto mA~Xs importante (a parte de los mA~Xdulos faltantes) es el trato de las codificaciones. La forma de hacerlo es aA~Xadiendo el pragma UTF8 de perl y recodificando las cadenas en la salida, pero aA~Xn no estA~X hecho.

We would also like to factorise some code (about file insertion) of the sgml module back into the TransTractor so that all modules can benefit from this, but this is not user visible.

AUTORES

  Denis Barbier <barbier,linuxfr.org>
  Martin Quinson (mquinson#debian.org)

TRADUCCION

  Jordi Vilalta <jvprat@gmail.com>