Provided by: po4a_0.36.1-1_all bug

NOMBRE

       po4a - marco de trabajo para traducir documentación y otro material

Introducción

       El objetivo del proyecto po4a (po para todo) es facilitar la traducción
       (y más interesante, el mantenimiento de las traducciones) usando las
       herramientas de gettext en áreas dónde no eran de esperar, como en la
       documentación.

Tabla de contenidos

       Este documento está organizado de la siguiente forma:

       1 ¿Porqué debo usar po4a? ¿Para qué sirve?
           Este capítulo introductorio explica la motivación del proyecto y su
           filosofía. Debería leerlo primero si está en el proceso de
           evaluación de po4a para sus propias traducciones.

       2 ¿Cómo usar po4a?
           Este capítulo es como un manual de referencia, dónde se intenta
           contestar las preguntas de los usuarios, y se le ofrece una idea
           general del proceso. Le introduce al método de trabajo con po4a y
           sirve como documentación introductoria de las herramientas
           específicas.

           ¿Cómo empezar una nueva traducción?
           ¿Cómo transformar la traducción de vuelta a un archivo de
           documentación?
           ¿Cómo actualizar una traducción con po4a?
           ¿Cómo convertir una traducción ya existente a po4a?
           ¿Cómo añadir texto extra en las traducciones (como el nombre del
           traductor)?
           ¿Cómo hacer todo esto en una sola invocación a programa?
           HOWTO customize po4a?
       3 ¿Cómo funciona?
           Este capítulo ofrece una breve explicación del funcionamiento
           interno de po4a, de forma que se pueda sentir más seguro para
           ayudarnos a mantenerlo y mejorarlo. También le puede ayudar a
           entender porqué no hace lo que esperaba, y cómo solucionar sus
           problemas.

       4 Preguntas Frecuentes
           Este capítulo agrupa las Preguntas Frecuentes. De hecho, la mayoria
           de preguntas actuales se pueden formular así: "¿Porqué se ha
           diseñado así, y no así?" Si piensa que po4a no es la solución ideal
           para la traducción de documentación, debería considerar leer ésta
           sección. Si no responde su pregunta, contacte con nosotros en la
           lista de correo <po4a-devel@lists.alioth.debian.org>. Queremos
           escuchar su opinión.

       5 Notas específicas de los módulos
           Este capítulo presenta los puntos específicos de cada módulo desde
           el punto de vista tanto del traductor como del autor original. Lea
           esto para aprender la sintaxis que se encontrará cuando traduzca
           textos con un módulo, o las reglas que debe seguir en el documento
           original para facilitar la vida del traductor.

           Actualmente ésta sección no forma parte de éste documento. En
           realidad está en la documentación de cada módulo. Esto permite
           asegurar que la información está actualizada al mantener la
           documentación y el código juntos.

       6 Fallos conocidos y características solicitadas
           Unos cuantos aún :(

¿Porqué debo usar po4a? ¿Para qué sirve?

       Me gusta la idea del software de código abierto, lo que hace posible
       que todo el mundo pueda acceder al software y a su código fuente. Pero
       al ser francés soy bien consciente de que la licencia no es la única
       restricción de la libertad del software: los programas libres no
       traducidos son inservibles para gente de habla no inglesa, y todavía
       queda bastante faena para hacerlos disponibles para todos.

       La percepción de ésta situación por los responsables del software libre
       ha mejorado drásticamente 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, ésta era la
       parte fácil. Ahora tenemos que ponernos en marcha y empezar a traducir.

       Actualmente, el software libre se beneficia de un nivel decente de
       traducción, 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 ejecución para mostrar los mensajes traducidos
       al usuario.

       Pero la situación es bastante diferente para la documentación.
       Demasiado a menudo, la documentación traducida no es suficientemente
       visible (no se distribuye como parte del programa), sólo lo está
       parcialmente, o no está actualizada. La última situación es la peor de
       todas. Para los usuarios, las traducciones anticuadas pueden ser peor
       que si no existiera la traducción, si describen viejos comportamientos
       del programa que ya no se usan.

   El problema a solucionar
       Traducir documentación no es muy difícil por sí solo. Los textos son
       bastante más largos que los mensajes de programa, y por lo tanto,
       tardan más en traducirse, pero no se necesitan conocimientos técnicos
       para hacerlo. La parte difícil llega cuando se debe mantener el
       trabajo. Detectar qué partes han cambiado y se necesitan actualizar es
       muy difícil, lleva a errores y es bastante desagradable. Creo que ésto
       explica porqué tantas de las traducciones de documentación que hay por
       ahí están anticuadas.

   Las respuestas de po4a
       Luego, el objetivo de po4a es hacer la traducción de documentación
       mantenible. La idea es reusar la metodología de gettext en éste nuevo
       campo. Como en gettext, los textos se extraen de su localización
       original, para ser presentados en un formato uniforme a los
       traductores. Las herramientas clásicas de gettext ayudan a actualizar
       el trabajo cuando aparece una nueva versión del original. Pero a
       diferencia del modelo clásico de gettext, las traducciones son
       reinyectadas en la estructura del documento original de forma que
       pueden ser procesadas y distribuidas igual que la versión inglesa.

       Gracias a esto, descubrir qué partes del documento han cambiado y se
       necesita actualizar se vuelve muy fácil. Otro punto fuerte es que las
       herramientas harán prácticamente toda la faena cuando la estructura del
       documento original se reorganice y cuando algunos capítulos se muevan,
       se junten o se separen. Al extraer el texto a traducir de la estructura
       del documento, también le mantiene lejos de la complejidad del formateo
       de texto y reduce las oportunidades de dañar el documento (aunque no le
       prevenga completamente de hacerlo).

       Por favor, lea también las "Preguntas Frecuentes" más abajo en éste
       documento para una lista más completa de ventajas y desventajas de esta
       solución.

   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 Documentación Online de Perl. El lenguaje y sus
       mismas extensiones están documentadas así, igual que la mayoría de
       scripts de Perl. Hace muy fácil mantener la documentación cerca del
       código al mezclarlos en el mismo archivo. Facilita la vida del
       programador, pero por desgracia, no la del traductor.

       sgml

       Aunque hoy en día casi haya sido sustituido por XML, éste formato aún
       es usado habitualmente para documentos más extensos que algunas
       pantallas. Este permite hacer libros completos. Actualizar una
       traducción de documentos tan largos puede ser realmente un infierno. A
       menudo diff se vuelve inútil cuando se ha reindentado el texto original
       después de la actualización. Afortunadamente, po4a le puede ayudar en
       ese proceso.

       Actualmente, sólo están soportados los DTDs de debiandoc y de docbook,
       pero añadir soporte para uno nuevo es realmente fácil. Incluso es
       posible usar po4a en un dtd desconocido de sgml sin cambiar el código,
       pasando la información necesaria en la línea de comandos. Consulte
       Locale::Po4a::Sgml(3pm) para más 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 también puede tratar algunos formatos raros o específicos, tal
       como la documentación de las opciones de compilación del kernel 2.4.x o
       los diagramas producidos por la herramienta dia. Añadir uno nuevo
       acostumbra a ser una tarea muy fácil y la tarea principal es conseguir
       un analizador para su formato. Consulte Locale::Po4a::TransTractor(3pm)
       para más información.

   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.

¿Cómo usar po4a?

       Este capítulo es como un manual de referencia, dónde se intenta
       contestar las preguntas de los usuarios, y se le ofrece una idea
       general del proceso. Le introduce al método de trabajo con po4a y sirve
       como documentación introductoria de las herramientas específicas.

   Visión esquemática
       The following schema gives an overview of the process of translating
       documentation using po4a. Do not be afraid by its apparent complexity,
       it comes from the fact that the whole process is represented here. Once
       you converted your project to po4a, only the right part of the graphic
       is relevant.

       Note that "master.doc" is taken as an example for the documentation to
       be translated and "translation.doc" is the corresponding translated
       text.  The suffix could be ".pod", ".xml", or ".sgml" depending on its
       format. Each part of the picture will be detailed in the next sections.

                                          master.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
       {translation}    |         { update of master.doc }             :
            :           |                     |                        :
          XX.doc        |                     V                        V
       (optional)       |                 master.doc ->-------->------>+
            :           |                   (new)                      |
            V           V                     |                        |
         [po4a-gettextize]   doc.XX.po--->+   |                        |
                 |            (old)       |   |                        |
                 |              ^         V   V                        |
                 |              |     [po4a-updatepo]                  |
                 V              |           |                          V
          translation.pot       ^           V                          |
                 |              |         doc.XX.po                    |
                 |              |         (fuzzy)                      |
          { translation }       |           |                          |
                 |              ^           V                          V
                 |              |     {manual editing}                 |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<---- doc.XX.po   addendum     master.doc
             (initial)                   (up-to-date) (optional)   (up-to-date)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                                  [po4a-translate]
                                                         |
                                                         V
                                                       XX.doc
                                                   (up-to-date)

       En la parte izquierda se muestra la conversión de una traducción que no
       usa po4a a este sistema. Arriba de la parte derecha se representa la
       acción del autor original (actualizar la documentación). En medio de la
       parte derecha se simbolizan las acciones automáticas de po4a. Se extrae
       el nuevo material, y se compara con la traducción existente. Se
       encuentran las partes que no han cambiado, y se usa la traducción
       previa. Las partes parcialmente modificadas también se conectan con la
       traducción anterior, pero se añade un marcador indicando que la
       traducción se debe actualizar. La parte de abajo de la figura muestra
       como se construye el documento formateado.

       Actualmente, como traductor, la única operación manual que debe hacer
       es la parte marcada como {edición manual}. Si, lo siento, pero po4a le
       ayuda a traducir. No traduce nada sólo...

   ¿Cómo empezar una nueva traducción?
       Esta sección presenta los pasos necesarios para iniciar una nueva
       traducción con po4a. Los refinamientos involucrados en la conversión de
       un proyecto existente al este sistema se detallan en la sección
       pertinente.

       Para iniciar una nueva traducción utilizando po4a, debe seguir los
       siguientes pasos:

       - Extract the text which have to be translated from the original
         <master.doc> document into a new translation template
         <translation.pot> file (the gettext format). For that, use the
         po4a-gettextize program this way:

           $ po4a-gettextize -f <formato> -m <principal.doc> -p <traducción.pot>

         <format> is naturally the format used in the master.doc document. As
         expected, the output goes into translation.pot.  Please refer to
         po4a-gettextize(1) for more details about the existing options.

       - 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 código ISO639
         del idioma al que esté traduciendo, por ejemplo "fr" para el
         francés), y edite el fichero resultante. A menudo es buena idea no
         llamar al fichero XX.po para evitar confusiones con la traducción de
         los mensajes de programa, pero eso es cosa suya.  No se olvide de
         actualizar las cabeceras de los ficheros po, son importantes.

         La traducción en sí 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 clásico vi puede bastar, aunque no
         tenga un modo especializado para esta tarea.

         Si quiere aprender más, definitivamente debe consultar la
         documentación de gettext, disponible en el paquete gettext-doc.

   ¿Cómo transformar la traducción de vuelta a un archivo de documentación?
       Una vez haya terminado la traducción, querrá obtener la documentación
       traducida para distribuirla a los usuarios junto con el original. Para
       eso, utilice el programa po4a-translate(1) así (donde XX es el código
       del idioma):

         $ po4a-translate -f <format> -m <master.doc> -p <doc.XX.po> -l <XX.doc>

       As before, <format> is the format used in the master.doc document. But
       this time, the po file provided with the -p flag is part of the input.
       This is your translation. The output goes into XX.doc.

       Consulte po4a-translate(1) para más detalles.

   ¿Cómo actualizar una traducción con po4a?
       To update your translation when the original master.doc file has
       changed, use the po4a-updatepo(1) program like that:

         $ po4a-updatepo -f <format> -m <new_master.doc> -p <old_doc.XX.po>

       (Consulte po4a-updatepo(1) para más detalles)

       Naturalmente, los nuevos párrafos del documento no se traducirán
       mágicamente en el fichero "po" con esta operación, y necesitará
       actualizar el fichero "po" manualmente. Asimismo, puede tener que
       rehacer las traducciones de los párrafos que se hayan modificado un
       poco. Para asegurar que no se olvidará ninguna, se marcan como
       "difusas" durante el proceso, y deberá quitar la marca manualmente
       antes que se pueda usar la traducción en po4a-translate.  Igual que
       para la traducción inicial, aquí lo mejor es usar su editor po
       favorito.

       Una vez su fichero "po" esté otra vez actualizado, sin ninguna cadena
       por traducir ni cadenas difusas, puede generar el fichero de
       documentación traducido, tal como se ha explicado en la sección
       anterior.

   ¿Cómo convertir una traducción ya existente a po4a?
       Often, you used to translate manually the document happily until a
       major reorganization of the original master.doc document happened.
       Then, after some unpleasant tries with diff or similar tools, you want
       to convert to po4a.  But of course, you don’t want to loose your
       existing translation in the process. Don’t worry, this case is also
       handled by po4a tools and is called gettextization.

       La condición más 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 está de suerte (es decir, si las estructuras de ambos documentos
       encajan a la perfección), todo funcionará a la perfección y habrá
       terminado en unos segundos. En caso contrario, deberá entender porqué
       este proceso tiene un nombre tan feo, y deberí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 deberá hacer esto una vez.

       No puedo emfatizarlo más. Para facilitar el proceso, es importante
       encontrar la versión exacta que se usó en la traducción. La mejor
       situación se da cuando se anotó qué revisión del cvs se usó para la
       traducción y no se modificó durante el proceso de traducción, de forma
       que pueda usarla.

       No funcionará bien si usa el texto original actualizado con una
       traducción vieja. Es un proceso posible, pero más difí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 solución es encontrar
       a alguien que haga la gettextización por usted (pero por favor, que no
       sea yo ;).

       Quizá sea demasiado catastrófico. Aunque las cosas vayan mal, sigue
       siendo mucho más rápido que traducirlo todo otra vez. Yo hice la
       gettextización de la traducción al francés existente de la
       documentación de Perl en un día, a pesar de que las cosas fueron mal.
       Eran más de dos megabytes de texto, y una traducción nueva hubiera
       podido durar como mínimo meses.

       Let me explain the basis of the procedure first and I will come back on
       hints to achieve it when the process goes wrong. To ease comprehension,
       let’s use above example once again.

       Once you have the old master.doc again which matches with the
       translation XX.doc, the gettextization can be done directly to the po
       file doc.XX.po without manual translation of translation.pot file:

        $ po4a-gettextize -f <format> -m <old_master.doc> -l <XX.doc> -p <doc.XX.po>

       Si está de suerte, eso es todo. Ha convertido su vieja traducción a
       po4a y ya puede empezar con la tarea de actualización. Simplemente siga
       el proceso explicado unas secciones antes para sincronizar su fichero
       po con el documento original más nuevo, y actualice la traducción según
       convenga.

       Tenga en cuenta que aunque parezca que todo ha ido bien, aún 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 traducción 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 perfección,
       impidiendo a po4a-gettextize realizar su tarea. Llegados a este punto,
       todo el juego se traslada a la edición de los ficheros para hacer
       encajar sus malditas estructuras.

       Le puede ayudar leer la sección "Gettextización: ¿Cómo funciona?" de
       más abajo. La comprensión del funcionamiento interno del proceso le
       ayudará a hacerlo funcionar. El punto bueno es que po4a-gettextize da
       mucha información cuando algo no va bien. Primero, apunta dónde se
       encontró la discrepancia de estructuras en los documentos. Luego le
       mostrará las cadenas que no encajan, su posición en el texto, y el tipo
       de cada una. Además, el fichero po generado hasta el momento se
       guardará 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 colaboró con la traducción. Los apéndices, descritos
           en la siguiente sección, le permitirán volver a añadir estos
           contenidos.

       -   No dude de editar tanto el original como la traducción. Lo más
           importante es conseguir el fichero po. Ya tendrá tiempo de
           actualizarlo luego. Una vez dicho esto, es preferible editar la
           traducción cuando se puedan editar ambos, ya que esto facilita las
           cosas una vez se termine la gettextización.

       -   Si es necesario, elimine algunas partes del original si no estaban
           traducidas. Cuando más adelante sincronice el po con el documento,
           volverán por sí solas.

       -   Si cambió un poco la estructura (para juntar dos párrafos, 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 traducción solo ofrece la solución a una parte de la
           comunidad. Y además, es imposible cuando se usa po4a ;)

       -   A veces el contenido del párrafo 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 líneas empieza con un espacio y la otra no. En
           estos formatos, este párrafo no podría justificarse y se volvería
           de un tipo diferente. Simplemente elimine el espacio y ya está.
           También puede tratarse de un error tipográfico en el nombre del
           tag.

           Además, dos párrafos pueden juntarse en el pod cuando la línea de
           separación contiene algunos espacios, o cuando no hay una línea de
           separación antes de la línea =item y del contenido del elemento.

       -   A veces, hay una desincronización entre archivos, y la traducción
           se encaja con un párrafo original equivocado. Este es un signo de
           que ya había un problema antes de juntar los ficheros. Compruebe
           gettextization.failed.po para ver cuando empieza la
           desincronización, y arréglelo allí.

       -   A veces le puede dar la impresión que po4a se comió algunas partes
           del texto, ya sea del original o de la traducción.
           gettextization.failed.po indica que ambos encajaban correctamente,
           y luego falló porque intentó encajar un párrafo con el anterior o
           el posterior al correcto, como si el correcto hubiera desaparecido.
           Maldiga po4a como yo hice la primera vez que me pasó.
           Abundantemente.

           Esta situación se debe a que el mismo párrafo se repite a lo largo
           del documento. En ese caso, no se crea una nueva entrada en el
           fichero po, sino que se le añade una nueva referencia a la ya
           existente.

           Por lo tanto, cuando el mismo párrafo aparece dos veces en el
           original pero no está traducido exactamente igual cada vez, tendrá
           esa sensación de que desapareció un párrafo del original.
           Simplemente elimine la nueva traducción. Si cree que la segunda
           traducción es mejor, quítela de donde está, y sustituya a la
           primera.

           En el caso contrario, si hay dos párrafos parecidos pero diferentes
           que se tradujeron de la misma forma, le puede dar la impresión de
           que desapareció un párrafo de la traducción. La solución es añadir
           una cadena estúpida al párrafo original (algo como "soy diferente")
           para solucionarlo. No se asuste. Estas cosas desaparecerán durante
           la sincronización, y cuando el texto añadido sea suficientemente
           corto, gettext encajara su traducción con el texto existente
           (marcándolo como difuso, pero no importa, ya que todas las cadenas
           se marcan como difusas durante la gettextización).

       Con un poco de suerte estos trucos le ayudarán a realizar su
       gettextización y a obtener su preciado fichero po. Ahora está preparado
       para sincronizar su fichero y empezar la traducción. Tenga en cuenta
       que en textos grandes la primera sincronización puede tardar mucho
       tiempo.

       Por ejemplo, el primer po4a-updatepo de la traducción al francés de la
       documentación de Perl (un fichero po de 5.5 Mb) tomó alrededor de dos
       dias enteros en una máquina 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 mayoría de msgids del
       fichero po no encajan con ninguno de los del fichero pot. Eso obliga a
       gettext a buscar la cadena más parecida usando un costoso algoritmo de
       proximidad de cadenas.

   ¿Cómo añadir texto extra en las traducciones (como el nombre del
       traductor)?
       Debido al uso de gettext, esto se vuelve más difícil en po4a que antes,
       que simplemente se editaba el nuevo fichero paralelamente al original.
       Pero sigue siendo posible, gracias a los llamados apéndices.

       Para ayudar a la comprensión, considere los apéndices como unos parches
       aplicados al documento traducido después del proceso. Son bastante
       diferentes que los parches habituales (solo tienen una línea de
       contexto, que puede incluir una expresión regular de perl, y únicamente
       puede añadir texto, sin eliminar nada), pero las funcionalidades son
       las mismas.

       Su objetivo es permitir al traductor añadir contenido extra al
       documento, que no es traducción del documento original. El uso más
       habitual es añadir una sección sobre la traducción en sí misma,
       listando los colaboradores y explicando como informar de los errores de
       la traducción.

       Los apéndices se deben proporcionar como ficheros a parte. La primera
       línea forma una cabecera que indica el lugar del documento resultante
       donde se debe colocar. El resto del fichero de apéndice se añadirá tal
       cual en la posición determinada del documento resultante.

       La cabecera tiene una sintaxis muy rí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 más, suena espantoso, pero los ejemplos de más abajo deberían
       ayudarle a encontrar la forma de escribir la línea de cabecera que
       necesita. Para ilustrar la discusión, asuma que quiere añadir una
       sección llamada "Sobre esta traducción" después de la llamada "Sobre
       este documento".

       Aquí hay las posibles llaves de la cabecera:

       position (obligatoria)
           una expresión regular. Se colocará el apéndice cerca de la línea
           que encaje con esta expresión regular.  Tenga en cuenta que estamos
           hablando del documento traducido, no del original. Si hay más de
           una linea que encaje (o ninguna), la adición fallará. Siempre es
           mejor dar un error que insertar el apéndice en el sitio equivocado.

           A continuación, esta línea se llamará punto de posicin. El punto
           donde se insertará el apéndice se llamará punto de insercin. Estos
           dos puntos son muy cercanos, pero no iguales. Por ejemplo, si desea
           insertar una nueva sección, es más fácil poner el punto de posicin
           en el título de la sección anterior, y explicarle a po4a donde
           termina la sección (recuerde que el punto de posicin viene dado
           por la expresión regular, que debe encajar una única linea).

           La localización del punto de insercin respecto al punto de
           posición está controlado por los campos "mode", "beginboundary" y
           "endboundary" que se explican a continuación.

           En nuestro caso tendríamos:

                position=<title>Sobre este documento</title>

       mode (obligatoria)
           Puede valer "before" (antes) o "after" (después), especificando la
           posición del apéndice, relativa al punto de posicin.

           Como queremos que la nueva sección se situe debajo de la que hemos
           encajado, tenemos:

                mode=after

       beginboundary (usada sólo cuando mode=after, y obligatoria en este
       caso)
       endboundary (ídem)
           Expresión regular que encaje el final de la sección después del que
           va el apéndice.

           Cuando mode=after, el punto de insercin está después del punto de
           posicin, pero no justamente después! Está situado al final de la
           sección que empieza en el punto de posicin, es decir, antes o
           después de la línea encajada por el parámetro "???boundary",
           dependiendo de si usó "beginboundary" o "endboundary".

           En nuestro caso, podemos decidirnos por indicar el final de la
           sección que encajamos añadiendo:

              endboundary=</section>

           o indicar el principio de la siguiente sección indicando:

              beginboundary=<section>

           En ambos casos, se colocará nuestro apéndice después de </section>
           y antes de <section>. La primera opción es mejor porque funcionará
           aunque se reorganice el documento.

           Las dos formas existen debido a que los formatos de documentación
           son diferentes. En algunos de ellos, hay una forma de marcar el
           final de una sección (tal como el "</section>" que hemos usado),
           mientras que otros no marcan explícitamente el final de una sección
           (como en nroff). En el primer caso, es preferible encajar un
           boundary con el final de seccin, para que el punto de insercin
           venga después. En el segundo caso, deberá encajar un boundary con
           el principio de la siguiente seccin para que el punto de insercin
           venga justo antes suyo.

       Puede parecer oscuro, pero espero que los próximos ejemplos le
       iluminen.

       Para concluir el ejemplo usado hasta el momento, para insertar una
       sección llamada "Sobre esta traducción" después de la sección "Sobre
       este documento" en un documento sgml, debe usar una de estas lí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 añadir algo después de la siguiente sección de nroff:
           .SH "AUTORES"

         Debe poner un "position" que encaje esta linea, y un "beginboundary"
         que encaje el principio de la siguiente sección (es decir "^\.SH").
         Entonces el apéndice se añadirá después del punto de posicin e
         immediatamente antes de la primera línea que encaje el
         "beginboundary". Así es:

          PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH

       Si desea añadir algo dentro de una sección (como después de "Copyright
       Big Dude") en vez de añadir una sección completa, ponga un "position"
       que encaje con esta línea, y ponga un "beginboundary" que encaje
       cualquier linea.
          PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

       Si desea añadir algo al final del documento, especifique un "position"
       que encaje cualquier linea del documento (pero sólo una línea. Po4a no
       procederá si no es única), 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 sección de nroff que termine
       con la línea

         .fi

       no utilice ".fi" como endboundary, porque esto encajará con "el[
       fi]chero", que obviamente no es lo que esperábamos. El endboundary
       correcto en este caso sería: "^\.fi$".

       Si el apéndice no va donde esperaba, pruebe pasando el parámetro -vv a
       las herramientas, para que le explique qué hace al colocar el apéndice.

       Ejemplo ms detallado

       Documento original (en formato pod):

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

       Luego, el siguiente apéndice asegurará que se añade una sección (en
       español) sobre el traductor al final del fichero.

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

       Para poner su apéndice 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/ después de la sección "NAME" (traducido a "NOMBRE" en
       español), es la que declara los autores. Por lo tanto, se colocará el
       apéndice entre ambas secciones.

   ¿Cómo hacer todo esto en una sola invocación 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 más de 3
       parámetros. Además, era difícil con este sistema usar solo un fichero
       po para todos los documentos cuando se usaba más de un formato.

       El programa po4a(1) se diseñó para solucionar esas dificultades. Una
       vez su proyecto se haya convertido al sistema, usted escribe un simple
       fichero de configuración explicando dónde están los ficheros de
       traducción (po y pot), dónde están los documentos originales, sus
       formatos, y dónde 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 interesará
       llamar el programa dos veces: una antes de editar el fichero po para
       actualizarlo, y otra para actualizar completamente los documentos
       traducidos. Pero sólo necesita recordar una línea de comandos.

   HOWTO customize po4a?
       po4a modules have options (specified with the -o option) that can be
       used to change the module behavior.

       It is also possible to customize a module or new / derivative /
       modified modules by putting a module in lib/Locale/Po4a/, and adding
       lib to the paths specified by the PERLLIB or PERL5LIB environment. For
       example:

          PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg

       Note: the actual name of the lib directory is not important.

¿Cómo funciona?

       Este capítulo ofrece una breve explicación del funcionamiento interno
       de po4a, de forma que se pueda sentir más seguro para ayudarnos a
       mantenerlo y mejorarlo. También le puede ayudar a entender porqué no
       hace lo que esperaba, y cómo solucionar sus problemas.

   Visión 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 extraño nombre viene del hecho de que al mismo
       tiempo se encarga de traducir el documento (translate) y de extraer las
       cadenas (extract).

       Más formalmente, toma un documento a traducir además del fichero po que
       contiene las traducciones a usar para producir dos salidas separadas:
       Otro fichero po (resultante de la extracción 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). Aquí hay una
       representación gráfica:

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

       Esta pequeña estructura es el núcleo 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 función virtual implementada por cada
       módulo. Aquí hay un pequeño ejemplo que muestra como funciona. Analiza
       una lista de párrafos, 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 línea definida? Final del archivo de entrada.
        19   }
        20 }

       En la línea 6, encontramos <p> por segunda vez. Esta es la señal de que
       hemos encontrado el siguiente párrafo. Entonces debemos devolver la
       línea obtenida de vuelta al documento (línea 7) y enviar el párrafo que
       hemos construido hacia la salida. Después de eliminar el <p> inicial,
       en la línea 9, insertamos la concatenación del tag con la traducción
       del resto del párrafo.

       Esta función translate() está muy bien. Envía su parámetro hacia el
       fichero po de salida (extracción) y devuelve su traducción como se
       encuentre en el fichero po de entrada (traducción). Como es usada como
       parte del parámetro de pushline(), esta traducción pasa hacia el
       documento de salida.

       Como mola, no? Es posible construir un módulo completo de po4a en menos
       de 20 líneas si el formato es suficientemente simple...

       Encontrará más sobre esto en Locale::Po4a::TransTractor(3pm).

   Gettextización: ¿Cómo funciona?
       La idea aquí es tomar el documento original y su traducción, y
       considerar que la enésima cadena extraida de la traducción es la
       traducción de la enésima 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 traducción
       (de tipo ’capítulo’) sea la traducción de la cuarta cadena del original
       (de tipo ’párrafo’).

           Original         Traducción

         capítulo           capítulo
           párrafo            párrafo
           párrafo            párrafo
           párrafo          capítulo
         capítulo             párrafo
           párrafo            párrafo

       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 información sobre el tipo sintáctico de
       las cadenas extraídas en el documento (todos los que hay lo hacen, el
       suyo también lo tiene que hacer). Luego se utiliza esa información para
       asegurar que ambos documentos tienen la misma sintaxis. En el ejemplo
       anterior, nos permitiría detectar que la cuarta cadena es un párrafo en
       un caso, y un título de capítulo en el otro, y tratarlo como un error.

       En teoria, la detección de este problema sería posible, y se
       resincronizan los ficheros luego (igual que hace diff). Pero no está
       claro qué deberíamos hacer con las cadenas antes de las
       desincronizaciones, y podría producir malos resultados a veces. Es por
       eso que la implementación actual no intenta resincronizar nada, e
       informa extensamente del fallo cuando algo va mal, requiriendo la
       modificación manual de los ficheros para arreglar el problema.

       Incluso con estas precauciones, las cosas se pueden estropear muy
       fácilmente. Es por eso que todas las traducciones encontradas así se
       marcan como difusas, para asegurar que el traductor las repase y las
       corrija.

   Apéndices: ¿Cómo 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 apéndices. Los algoritmos involucrados son sencillos.
       Buscamos una línea que encaje con la expresión regular de posición, e
       insertamos el apéndice antes si estaba en mode=before. Sino, buscamos
       la siguiente linea que encaje en el rango e insertamos el apéndice
       después de esta línea si es un "endboundary" o antes de esta línea si
       es un "beginboundary".

Preguntas Frecuentes

       Este capítulo agrupa las Preguntas Frecuentes. De hecho, la mayoria de
       preguntas actuales se pueden formular así: "¿Porqué se ha diseñado así,
       y no así?" Si piensa que po4a no es la solución ideal para la
       traducción de documentación, debería considerar leer ésta sección. Si
       no responde su pregunta, contacte con nosotros en la lista de correo
       <po4a-devel@lists.alioth.debian.org>. Queremos escuchar su opinión.

   ¿Porqué traducir cada párrafo por separado?
       Si, en po4a, cada párrafo se traduce por separado (de hecho, cada
       módulo lo decide, pero todos los existentes lo hacen, y los suyos deben
       hacerlo también).  Hay dos ventajas principales al hacerlo así:

       · Cuando las partes técnicas del documento se esconden, el traductor no
         se puede confundir con ellas. Como menos marcas presentemos al
         traductor, menos errores podrá hacer.

       · El hecho de cortar el documento ayuda a aislar los cambios en el
         documento original. Cuando se modifica el original, es fácil
         encontrar qué partes de la traducción se necesita actualizar con este
         proceso.

       Incluso con estas ventajas, a alguna gente no le gusta la idea de
       traducir cada párrafo por separado. Aquí 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 más grande de documentación
         traducida y actualizada que conozco.

       · Los traductores aún pueden usar el contexto para traducir, ya que las
         cadenas del fichero po están 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 leíbles, en mi opinión.

       · Los traductores profesionales utilizan esta aproximación. Estoy de
         acuerdo en que ellos tienen diferentes objetivos que los traductores
         de código abierto. Por ejemplo, el mantenimiento les es a menudo
         menos crítico, ya que el contenido cambia muy poco.

   ¿Porqué no realizar las divisiones a nivel de frases (o menores)?
       A veces las herramientas de traducción 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 párrafos son por definición más largos que las frases. Con un poco
       de suerte se podrá asegurar que si se tiene el mismo párrafo en dos
       documentos, tendrán el mismo significado (y traducción), sin importar
       el contexto de cada caso.

       Partirlo en partes más pequeñas que frases sería muy malo. Podría tomar
       mucho tiempo explicar el motivo aquí, pero si le interesa puede
       consultar la página de manual de Locale::Maketext::TPJ13(3pm) (que
       viene con la documentación de Perl), por ejemplo. Brevemente, cada
       idioma tiene sus reglas de sintaxis específicas, y no hay forma de
       construir frases encajando partes de frases para todos los idiomas
       existentes (incluso para 5 de los 10 idiomas más hablados, o incluso
       menos).

   ¿Porqué no se pone el original como comentario junto con la traducción (o
       de otra forma)?
       A simple vista, gettext no parece estar adaptado a todos los tipos de
       traducciones. Por ejemplo, no parecía adaptado a debconf, la interfaz
       que usan todos los paquetes de Debian para sus interacciones con el
       usuario durante la instalación. En ese caso, los textos a traducir eran
       muy cortos (una docena de lineas para cada paquete), y era muy difícil
       poner las traducciones en un fichero específico ya que tiene que estar
       disponible antes de la instalación del paquete.

       Es por eso que los desarrolladores de debconf decidieron implementar
       otra solución, donde las traducciones estuvieran situadas en el mismo
       fichero que el original. Es bastante atractivo. Se podría querer
       hacerlo en xml, por ejemplo. Tendrí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 problemático que se terminó usando una implementación
       basada en po. Solo se puede editar el original en el archivo, y las
       traducciones se deben hacer en los ficheros po extraídos del patrón
       principal (y vueltos al paquete en tiempo de compilación). El sistema
       antiguo se consideró obsoleto debido a varios problemas:

       ·   problemas de mantenimiento

           Si varios traductores envían un parches a la vez, es difícil de
           juntarlos.

           ¿Como detectará los cambios en el original, que se deban aplicar a
           las traducciones? Para poder usar diff, se debe tener en cuenta qué
           version del original se tradujo. Es decir, se necesita un fichero
           po en su fichero ;)

       ·   problemas de codificación

           La solución es viable cuando solo se utilizan idiomas europeos,
           pero la introducción del Koreano, Ruso y/o Arabe complica realmente
           la cosa. La solución sería UTF, pero aún hay algunos problemas con
           él.

           Además, estos problemas son difíciles de detectar (es decir, solo
           los lectores Koreanos detectarán que falla la codificación del
           Koreano [por culpa del traductor ruso])

       gettext soluciona todos estos problemas a la vez.

   ¡Pero gettext no se diseñó para este uso!
       Es cierto, pero hasta el momento nadie ha propuesto una solución mejor.
       La única alternativa conocida es la traducción manual, con todos los
       problemas de mantenimiento.

   ¿Qué hay de las otras herramientas de traducción de documentación que usan
       gettext?
       Hasta donde yo sé, sólo 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 después de la traducción.

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

       po-debiandoc
           Este programa hecho por Denis Barbier es un tipo de precursor del
           módulo sgml de po4a, que más o menos lo deja obsoleto. Como su
           nombre indica, únicamente trata el dtd de debiandoc, que además es
           un dtd anticuado.

       Las principales ventajas de po4a sobre ellos son la facilidad de
       adición de contenidos extra (que es aún peor allí) y la habilidad de
       realizar la gettextización.

   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 qué es el fichero, y como usarlo. Esto
       deberí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 aproximación 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.

       · Está 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 están más o menos libres de fallos.

       · No ha cambiado nada para el usuario final (a parte de que
         probablemente las traducciones estarán mejor mantenidas :). El
         fichero de documentación 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) servirán a la perfección.

       · 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 aproximación también tiene algunas
       desventajas con las que debemos cargar.

       · Los apéndices son... extraños a primera vista.

       · No puede adaptar el texto traducido a su gusto, como partir párrafos
         por aquí, y juntar esos dos allí. Pero según como, si está en
         desacuerdo con el original, debería informarlo como un bug, de todas
         formas.

       · Incluso con una interfaz fácil, sigue siendo una nueva herramienta
         que la gente debe aprender.

         Uno de mis sueños es integrar de alguna forma po4a con gtranslator o
         kbabel. Cuando se abra un archivo sgml, se extraen las cadenas
         automáticamente. Al guardar se guarda un fichero sgml traducido en el
         disco. Si consiguiéramos hacer un módulo para MS Word (TM) (o al
         menos para RTF) incluso podrían usarlo traductores profesionales.

Fallos conocidos y características solicitadas

       El asunto más importante (a parte de los módulos faltantes) es el trato
       de las codificaciones. La forma de hacerlo es añadiendo el pragma UTF8
       de perl y recodificando las cadenas en la salida, pero aún no está
       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>