Formatos compatibles

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

man (intérprete maduro)

El clásico formato de las páginas de manual, usado por muchos programas fuera de allí. La compatibilidad con po4a es bienvenida ya que el formato es algo difícil de usar, y no muy amistoso para los principiantes.

El módulo Locale::Po4a::Man(3pm) además admite el formato mdoc, utilizado por las páginas man BSD (no son muy comunes en Linux).

AsciiDoc (intérprete maduro)

Este formato es un formato de margen ligero entendido para facilitar la autoría de documentación. Es utilizado por ejemplo para documentación del sistema git. Esas páginas man son traducidas utilizando po4a.

Vea Locale::Po4a::AsciiDoc para detalles.

pod (intérprete maduro)

Este es el formato «Perl Online Documentation» (Documentación en línea de Perl). El lenguaje y sus mismas extensiones están documentados utilizando este formato junto la suma de muchos guiones Perl existentes. Hace muy fácil mantener la documentación cerca del código al integrarlos en el mismo fichero. Facilita la vida del programador, pero por desgracia, no la del traductor, hasta que utilice po4a.

Vea Locale::Po4a::Pod para detalles.

sgml (intérprete maduro)

Aunque hoy en día XML lo haya sustituido, este formato aún se usa para documentos más extensos que unas pocas pantallas. Incluso se puede utilizar para libros completos. Actualizar documentos de esta longitud puede convertirse en un reto enorme. A menudo diff se vuelve inútil cuando se ha sangrado («indented») otra vez el texto original tras una actualización. Afortunadamente, po4a le puede ayudar tras ese proceso.

Actualmente, sólo son compatibles los DTD de DebianDoc y de DocBook, pero añadir compatibilidad con uno nuevo es realmente fácil. Incluso es posible usar po4a con un DTD desconocido de SGML sin cambiar el código introduciendo la información necesaria en la línea de órdenes. Consulte Locale::Po4a::Sgml(3pm) para más detalles.

TeX / LaTeX (intérprete maduro)

El formato LaTeX es un formato de documentación usado principalmente en el mundo del Software Libre y para publicaciones.

Se probó el módulo Locale::Po4a::LaTeX(3pm) con la documentación de Python, un libro y algunas presentaciones.

texto (intérprete maduro)

El formato Texto es el formato base para muchos formatos que incluyen bloques grandes de texto, incluyendo Markdown, fortunes, sección matter de frente YAML, debian/changelog, y debian/control.

Esto admite el formato común utilizado en Generadores de Sitio Estático, README, y otros sistemas de documentación. Vea Locale::Po4a::Text(3pm) para detalles.

xml y XHML (intérprete probablemente maduro)

El formato XML sirve de base para muchos formatos de documentación.

Actualmente, el formato DTD de DocBook (vea L>Locale::Po4a::DocBook(3pm)> para detalles) y XHTML están admitidos por po4a.

BibTex (intérprete probablemente maduro)

El formato BibTex es utilizado a lo largo de LaTeX para listados de formato de referencias (bibliográficos).

Vea Locale::Po4a::BibTex para detalles.

Docbook (intérprete probablemente maduro)

Un lenguaje añadido basado en XML que utiliza etiquetados semánticos para describir documentos.

Vea Locale::Po4a:Docbook para detalles mayores.

Guide XML (intérprete probablemente maduro)

Un formato de documentación XML. Este módulo fue desarrollado específicamente para ayudar con apoyo y mantenimiento de traducciones de documentación de Linux Gentoo hasta al menos en marzo de 2016 (basado en la Máquina Wayback). Gentoo desde entonces se ha migrado al formato XML DevBook.

Vea Locale::Po4a:Guide para detalles mayores.

Wml (probablemente intérprete maduro)

El XML (Web Markup Language), no mezcla WML con la materia WAP utilizada en celdas de teléfonos. Este módulo depende del módulo XHTML, el mismo que dependo del módulo XML.

Vea Locale::Po4a::Wml para detalles mayores.

Yaml (probablemente intérprete maduro)

Un superconjunto estricto de JSON. YAML se utiliza a menudo como sistemas o proyectos de configuración. YAML está en el núcleo de Ansible de Red Hat.

Vea Locale::Po4a::Yaml para más detalles.

RubyDoc (analizador probablemente maduro)

El formato Ruby Document (RD), originalmente el formato de documentación por defecto para Ruby y los proyectos Ruby antes de convertirse a RDoc en 2002. Aunque aparentemente la versión japonesa del Manual de Referencia de Ruby todavía usa RD.

Vea Locale::Po4a::RubyDoc para detalles mayores.

Halibut (analizador probablemente experimental)

Un sistema de producción de documentación, con elementos similares a TeX, debiandoc-sgml, TeXinfo, y otros, desarrollados por Simon Tatham, el desarrollador de PuTTY.

Vea Locale::Po4a:Halibut para detalles mayores.

Ini (probablemente intérprete experimental)

Formado del archivo de configuración popularizado por MS-DOS.

Vea Locale::Po4a::Ini para detalles más grandes.

texinfo (intérprete altamente experimental)

Toda la documentación de GNU está escrita en este formato (es incluso un requisito para ser un proyecto oficial de GNU). La compatibilidad de Locale::Po4a::Texinfo(3pm) en po4a está en sus inicios. Por favor, remita informes de fallo y peticiones de funcionalidades.

gemtext (very highly experimental parser)

The native plain text format of the Gemini protocol. The extension ".gmi" is commonly used. Support for this module in po4a is still in its infancy. If you find anything, please file a bug or feature request.

Otros formatos admitidos

Po4a también puede tratar algunos formatos raros o específicos, tales como la documentación de las opciones de compilación de núcleos 2.4+ (Locale::Po4a::KernelHelp) o los diagramas producidos por la herramienta (Locale::Po4a:Dia). Añadir un formato nuevo es a menudo una tarea muy sencilla, y la tarea principal es conseguir un intérprete para el formato escogido. Consulte Locale::Po4a::TransTractor(3pm) para más información.

Formatos no compatibles

Desafortunadamente, po4a aún le falta compatibilidad para formatos de documentación. Muchos de ellos serían sencillos de mantener en po4a. Esto incluye formatos no tan solo utilizados para documentación, como descripciones de paquetes (deb y rpm), guiones de instalación de paquetes , boletines del paquete, y todos los formatos de archivos especializados utilizados por los programas tales como escenarios de juegos o los archivos de recursos de wine.

Esquema detallado del flujo de trabajo po4a

Asegúrese de leer po4a(1) antes de esta sección excesivamente detallada para obtener una visión simplificada del flujo de trabajo de po4a. Vuelva aquí cuando quiera obtener la imagen completa que asusta, con casi todos los detalles.

En el siguiente esquema, master.doc es un nombre de ejemplo para la documentación a traducir; XX.doc es el mismo documento traducido al idioma XX mientras que doc.XX.po es el catálogo de traducción para ese documento en el idioma XX. Los autores de la documentación se ocuparán principalmente de master.doc (que puede ser una página de manual, un documento XML, un fichero AsciidDoc, etc); los traductores se ocuparán principalmente del fichero PO, mientras que los usuarios finales sólo verán el fichero XX.doc.

Transitions with square brackets such as "[po4a updates po]" represent the execution of a po4a tool while transitions with curly brackets such as "{update of master.doc}" represent a manual modification of the project's files.

                                   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 updates po]                  |
          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 updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

De nuevo, este esquema es excesivamente complicado. Consulta po4a(1) para obtener una visión simplificada.

La parte izquierda muestra cómo se puede usar po4a-gettextize(1) para convertir un proyecto de traducción existente a la infraestructura po4a. Este script toma un documento original y su contrapartida traducida, e intenta construir el archivo PO correspondiente. Esta conversión manual es bastante engorrosa (consulte la documentación de po4a-gettextize(1) para más detalles), pero solo es necesaria una vez para convertir sus traducciones existentes. Si no tiene ninguna traducción que convertir, puede olvidarse de esto y centrarse en la parte derecha del esquema.

En la parte superior derecha se representa la acción del autor original, que actualiza la documentación. La parte central derecha muestra la actualización automática de los archivos de traducción: se extrae el nuevo material y se compara con la traducción existente. La traducción anterior se utiliza para las partes que no han cambiado, mientras que las partes parcialmente modificadas se conectan a la traducción anterior con un marcador "difuso" que indica que la traducción debe actualizarse. El material nuevo o muy modificado se deja sin traducir.

A continuación, la edición manual muestra la acción de los traductores, que modifican los archivos PO para proporcionar traducciones a cada cadena y párrafo originales. Esto puede hacerse usando un editor específico como el GNOME Translation Editor, Lokalize o poedit de KDE, o usando una plataforma de localización online como weblate o pootle. El resultado de la traducción es un conjunto de archivos PO, uno por idioma. Por favor, consulte la documentación de gettext para más detalles.

La parte inferior de la figura muestra cómo po4a crea un documento fuente traducido a partir del documento original master.doc y el catálogo de traducción doc.XX.po actualizado por los traductores. La estructura del documento se reutiliza, mientras que el contenido original se sustituye por su homólogo traducido. Opcionalmente, se puede utilizar un apéndice para añadir texto adicional a la traducción. Suele utilizarse para añadir el nombre del traductor al documento final. Para más detalles, véase más abajo.

Al invocarlo, po4a actualiza automáticamente tanto los archivos de traducción como los archivos de documentación traducidos.

Iniciar un nuevo proyecto de traducción

Si empieza desde cero, sólo tiene que escribir un fichero de configuración para po4a, y listo. Se crearán las plantillas relevantes para los ficheros que falten, permitiendo a sus colaboradores traducir su proyecto a su idioma. Por favor, consulte po4a(1) para un tutorial de inicio rápido y para todos los detalles.

Si tiene una traducción existente, es decir, un fichero de documentación que se tradujo manualmente, puede integrar su contenido en su flujo de trabajo po4a usando po4a-gettextize. Esta tarea es un poco engorrosa (como se describe en la página de manual de la herramienta), pero una vez que su proyecto se convierta al flujo de trabajo po4a, todo se actualizará automáticamente.

Actualización de traducciones y documentos

Una vez configurado, basta con invocar po4a para actualizar tanto los ficheros PO de traducción como los documentos traducidos. Puede pasar "--no-translations" a po4a para no actualizar las traducciones (actualizando así sólo los ficheros PO) o "--no-update" para no actualizar los ficheros PO (actualizando así sólo las traducciones). Esto corresponde aproximadamente a los scripts individuales po4a-updatepo y po4a-translate que ahora están obsoletos (vea "Por qué están obsoletos los scripts individuales" en las FAQ más abajo).

Al utilizar adenda para agregar texto adicional para traducciones

Agregando texto nuevo para la traducción es probablemente la única cosa que es más fácil en la dirección larga cuando traduzca archivos manualmente :). Esto ocurre cuando desea añadir una sección adicional para el documento traducido, no correspondiente a ningún contenido dentro del documento original. La utilización clásica de caso es dar reconocimientos al equipo de traducción, y para indicar como informar problemas específicos de traducción.

Con po4a, tiene que especificar archivos anexos, que pueden verse conceptualmente como parches aplicados al documento localizado después de procesarlo. Cada anexo debe proporcionarse como un archivo separado, cuyo formato es, sin embargo, muy diferente de los parches clásicos. La primera línea es una línea de encabezamiento, que define el punto de inserción del anexo (con una sintaxis desafortunadamente críptica -- ver más abajo) mientras que el resto del archivo se añade textualmente en la posición determinada.

La línea de encabezado debe comenzar con la cadena PO4A-HEADER:, seguida de una lista de campos clave=valor separados por punto y coma.

Por ejemplo, el siguiente encabezamiento declara un anexo que debe colocarse al final de la traducción.

PO4A-HEADER: mode=eof

Las cosas se complican cuando desea añadir su contenido adicional en medio del documento. La siguiente cabecera declara un anexo que debe colocarse después de la sección XML que contiene la cadena "Acerca de este documento" en la traducción.

PO4A-HEADER: position=Acerca de este documento; mode=after; endboundary=</section>

En la práctica, al intentar aplicar un anexo, po4a busca la primera línea que coincida con el argumento de "posición" (puede ser una regexp). No olvide que po4a considera aquí el documento traducido. Esta documentación está en inglés, pero su línea probablemente debería decir lo siguiente si pretende que su anexo se aplique a la traducción francesa del documento.

PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Una vez encontrada la "posición" en el documento destino, po4a busca la siguiente línea después de la "posición" que coincida con el "endboundary" proporcionado. El anexo se añade justo después de esa línea (porque proporcionamos un endboundary, es decir, un límite que termina la sección actual).

Se podría obtener exactamente el mismo efecto con la siguiente cabecera, que es equivalente:

PO4A-HEADER: position=Acerca de este documento; mode=after; beginboundary=<section>

Here, po4a searches for the first line matching "<section>" after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section>" tag. This is equivalent to the previous example because what you really want is to add this addendum either after "</section>" or before "<section>".

También se puede asignar al modo ( mode) de inserción el valor "before", con una semántica similar: si se combina "mode=before" con un "endboundary", el anexo se situará justo después del límite coincidente, es decir, el último límite potencial antes de "position". Si se combina "mode=before" con "beginboundary", el anexo se situará justo antes del límite coincidente, es decir, el último límite potencial antes de "position".

 Modo   | Tipo límite |     Límite usado      | Punto de inserción relativo al límite
========|===============|========================|=========================================
'before'| 'endboundary' | último antes de 'position' | Justo tras el límite seleccionado
'before'|'beginboundary'| último antes de 'position' | Justo antes del límite seleccionado
'after' | 'endboundary' | primero tras 'position' | Justo tras el límite seleccionado
'after' |'beginboundary'| primero tras 'position' | Justo antes del límite seleccionado
'eof'   |   (ninguno)      |  n/a                   | Fin del archivo

Consejos y trucos sobre los anexos

• Recuerde que se trata de regexp. Por ejemplo, si quiere que coincida con el final de una sección nroff que termina con la línea ".fi", no utilice ".fi" como endboundary, porque esto coincidirá con "el[ fi]chero", que obviamente no es lo que espera. El endboundary correcto en este caso sería: "^\.fi$".
• Los espacios en blanco SÍ son importantes en el contenido de "position" y los límites. Así que las dos líneas siguientes son diferentes. La segunda sólo se encontrará si hay suficientes espacios finales en el documento traducido.

  PO4A-HEADER: position=Acerca de este documento; mode=after; beginboundary=<section>
  PO4A-HEADER: position=Acerca de este documento; mode=after; beginboundary=<section>
  

• Aunque se puede considerar que esta búsqueda de contexto funciona básicamente en cada línea del documento traducido, en realidad funcionan a partir de la cadena de datos interna del documento traducido. Esta cadena de datos interna puede ser un texto que comprende un párrafo de varias líneas, o una etiqueta XML individual. El punto de inserción preciso del apéndice se debe encontrar antes o después de la cadena de datos interna, y no puede encontrarse dentro de la cadena de datos interna.
• Pass the "-vv" argument to po4a to understand how the addenda are added to the translation. It may also help to run po4a in debug mode to see the actual internal data string when your addendum does not apply.

Ejemplos de anexos

• Si desea añadir algo después de la siguiente sección de nroff:

  .SH "AUTORES"
  

  Debe seleccionar un enfoque de dos pasos estableciendo mode=after. A continuación, debe limitar la búsqueda a la línea posterior a AUTHORS con el argumento regex position. A continuación, debe hacer coincidir el comienzo de la siguiente sección (es decir, ^\.SH) con el argumento regex beginboundary. Es decir:

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

• Si desea añadir algo justo después de una línea concreta (por ejemplo después de «Copyright Big Dude») utilice un "position" que encaje con esta línea, mode=after e introduzca un beginboundary que encaje con 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 con 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=Acerca de este documento;beginboundary=FakePo4aBoundary
  

Ejemplo más detallado

Documento original (en formato POD):

|=head1 NOMBRE
|
|relleno - un programa de relleno
|
|=head1 AUTOR
|
|yo

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 anexo antes del AUTOR, utilice la siguiente cabecera:

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

This works because the next line matching the beginboundary "/^=head1/" after the section "NAME" (translated to "NOM" in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between NAME and AUTHOR sections later, po4a will wrongfully put the addenda before the new section.

Para evitarlo, puede lograr el mismo efecto utilizando mode=before:

PO4A-HEADER:mode=before;position=^=head1 AUTHOR

TransTractors y arquitectura de proyectos

En el núcleo del proyecto po4a, la clase Locale::Po4a::TransTractor(3pm) es el ancestro común de todos los analizadores sintácticos de po4a. Este extraño nombre proviene del hecho de que se encarga al mismo tiempo de traducir el documento y de extraer las cadenas.

Más formalmente, toma un documento para traducir más un fichero PO que contiene las traducciones para utilizarlo como entrada, al tiempo que produce dos salidas separadas: Otro fichero PO (resultante de la extracción de cadenas traducibles del documento de entrada), y un documento traducido (con la misma estructura que el de entrada, pero con todas las cadenas traducibles sustituidas por contenido del PO de entrada). He aquí una representación gráfica de esto:

Input document --\                             /---> Output document
                  \      TransTractor::       /       (translated)
                   +-->--   parse()  --------+
                  /                           \
Input PO --------/                             \---> Output PO
                                                    (extracted)

Este pequeño hueso es el núcleo de toda la arquitectura po4a. Si proporciona ambos PO de entrada y no tiene en cuenta el PO de salida, obtiene po4a-translate. Si no tiene en cuenta el documento de salida, obtiene po4a-updatepo. po4a utiliza un primer TransTractor para obtener un fichero POT de salida actualizado (sin tener en cuenta los documentos de salida), llama a msgmerge -U para actualizar los ficheros PO de traducción en disco, y construye un segundo TransTractor con estos ficheros PO actualizados para actualizar los documentos de salida. En resumen, po4a proporciona una solución única para actualizar lo que sea necesario, utilizando un único archivo de configuración.

po4a-gettextize también usa dos TransTractores, pero de otra forma: Construye un TransTractor por idioma, y luego construye un nuevo fichero PO usando los msgids del documento original como msgids, y los msgids del documento traducido como msgstrs. Hay que tener mucho cuidado para asegurarse de que las cadenas emparejadas de esta forma realmente coinciden, como se describe en po4a-gettextize(1).

Analizadores sintácticos de formatos específicos

Todos los analizadores de formato po4a se implementan sobre el TransTractor. Algunos son muy simples, como los de Text, Markdown y AsciiDoc. Cargan las líneas una a una usando TransTractor::shiftline(), acumulan el contenido de los párrafos o lo que sea. Una vez que una cadena está completamente analizada, el analizador usa TransTractor::translate() para (1) añadir esta cadena al fichero PO de salida y (2) obtener la traducción del fichero PO de entrada. El parseador entonces empuja el resultado al fichero de salida usando TransTractor::pushline().

Algunos otros analizadores sintácticos son más complejos porque dependen de un analizador sintáctico externo para analizar el documento de entrada. Los analizadores sintácticos Xml, HTML, SGML y Pod están construidos sobre analizadores sintácticos SAX. Declaran retrollamadas a eventos como "He encontrado un nuevo título cuyo contenido es el siguiente" para actualizar el documento de salida y los archivos POT de salida según el contenido de entrada utilizando TransTractor::translate() y TransTractor::pushline(). El analizador Yaml es similar pero diferente: serializa una estructura de datos producida por el analizador YAML::Tiny. Esta es la razón por la que el módulo Yaml de po4a no declara las líneas de referencia: la localización de cada cadena en el fichero de entrada no la guarda el analizador, por lo que sólo podemos proporcionar "$nombredefichero:1" como localización de la cadena. Los analizadores sintácticos orientados a SAX usan globales y otros trucos para guardar el nombre del fichero y los números de línea de las referencias.

One specific issues arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by TransTractor::read() (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on Pod::read() and Pod::parse() for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.

Objetos Po

The Locale::Po4a::Po(3pm) class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the gettext() method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to msgmerge and msgfmt respectively.

Contribuir a po4a

Incluso si nunca ha contribuido a ningún proyecto de código abierto en el pasado, es bienvenido: estamos dispuestos a ayudarle y guiarle. po4a es mejor mantenido por sus usuarios hoy en día. Como nos falta mano de obra, intentamos hacer el proyecto acogedor mejorando la documentación y las pruebas automáticas para que tenga confianza en contribuir al proyecto. Por favor, consulte el archivo CONTRIBUTING.md para más detalles.

¿Cómo se pronuncia po4a?

Yo personalmente lo pronuncio como pouah https://en.wiktionary.org/wiki/pouah, que es una onomatopeya francesa que usamos en lugar de puaj :) Puede que tenga un extraño sentido del humor :)

¿Por qué están obsoletos los scripts individuales?

Indeed, po4a-updatepo and po4a-translate are deprecated in favor of po4a. The reason is that while po4a can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the po4a program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occuring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in po4a and the other po4a-updatepo.

A largo plazo, me gustaría abandonar los scripts individuales y mantener sólo una versión de este código. Lo seguro es que los scripts individuales no se mejorarán más, por lo que sólo po4a obtendrá las nuevas características. Dicho esto, no hay urgencia de desaprobación. Planeo mantener los scripts individuales tanto como sea posible, y al menos hasta 2030. Si tu proyecto todavía utiliza po4a-updatepo y po4a-translate en 2030, puede que tengas un problema.

También es posible que en algún momento eliminemos la desaprobación de estos scripts, si una refactorización reduce a cero la duplicación de código. Si tienes una idea (o mejor: un parche), tu ayuda será bienvenida.

¿Qué hay de las otras herramientas de traducción de documentación que usan gettext?

Hay unas cuantas. Esta es una lista posiblemente incompleta, y más herramientas se asoman por el horizonte.

poxml

Esta es la herramienta desarrollada por la gente de KDE para tratar DocBook XML. Me parece que este fue el primer programa que extrajo cadenas de texto a traducir desde la documentación a ficheros PO, e inyectarlas de vuelta después de la traducción.

Únicamente puede tratar XML, y solo un DTD en particular. Estoy bastante insatisfecho con el tratamiento 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 es más o menos un DTD anticuado.

xml2po.py

Utilizado por el Equipo de Documentación de GIMP desde 2004, funciona bastante bien aunque, como su nombre indica, sólo con archivos XML y necesita makefiles especialmente configurados.

Sphinx

El Proyecto de Documentación Sphinx también utiliza gettext extensivamente para gestionar sus traducciones. Por desgracia, sólo funciona para unos pocos formatos de texto, rest y markdown, aunque quizá sea la única herramienta que lo hace gestionando todo el proceso de traducción.

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

RESUMEN de las ventajas de la metodología basada en gettext

• Las traducciones no se guardan junto con el original, lo que hace posible la detección de traducciones anticuadas.
• Las traducciones se guardan en ficheros separados unos de otros, lo que impide que traductores de diferentes idiomas interfieran en su trabajo tanto al enviar parches, como a nivel de codificación de ficheros.
• Está basado internamente en gettext (pero po4a ofrece una interfaz muy simple de forma que no necesita entender el funcionamiento interno para usarlo). De esa forma no tenemos que reinventar la rueda, y debido a su uso extendido podemos imaginar que estas herramientas están más o menos libres de fallos.
• Para el usuario final nada ha cambiado (aparte de que, probablemente, las traducciones estarían mejor actualizadas :). 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, Lokalize o Gtranslator) servirán a la perfección.
• gettext ofrece una manera simple de conseguir estadísticas sobre qué está hecho, qué se debería repasar y actualizar, y lo que queda por hacer. Puede encontrar algunos ejemplos en estas direcciones:

  - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
  - http://www.debian.org/intl/l10n/
  

Pero no todo es bonito, y este enfoque también tiene algunas desventajas con las que debemos lidiar.

• Los apéndices son algo extraños a primera vista.
• No puede adaptar el texto traducido a su gusto, como dividir párrafos por aquí, y juntar esos dos allí. Pero por supuesto, si hay algún problema con el original debería remitir un informe de fallo.
• 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 Lokalize. Cuando se abra un fichero, se extraen las cadenas automáticamente, y se puede escribir en el disco un fichero traducido y un fichero PO. Si consiguiéramos hacer un módulo para MS Word (TM) (o al menos RTF) incluso podrían usarlo traductores profesionales.