po4av0.70

PO4A

Section: Herramientas de po4a (7)
Updated: 2024-01-29
Index Return to Main Contents
 

NOMBRE

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

Introducción

po4a (PO para todo) facilita el mantenimiento de traducción de documentación utilizando las clásicas herramientas gettext. La característica de po4a principal es que desacopla la traducción del contenido desde su estructura documental.

Este documento sirve como una introducción para el proyecto po4a con un enfoque en usuarios potenciales considerando si utiliza esta herramienta y en la curioso deseo de entender por qué las cosas son de la manera que son.  

¿Por qué po4a?

La filosofía de Free Software , es hacer que la tecnología está disponible a cada uno. Pero la licencia no es la única consideración: el software libre no traducido es inútil para los hablantes no ingleses. Por lo tanto, aún hay tarea que hacer para crear software disponible para todos.

Esta situación es bien entendida por muchos proyectos y cada uno ahora está convencido de la necesidad de traducir todo. Aún, las traducciones actuales representan un enorme esfuerzo de muchos individuales, heridos por pequeñas dificultades técnicas.

Agradecidamente, el software libre se beneficia de un nivel decente de traducción gracias al maravilloso conjunto de herramientas gettext. Éste puede extraer las cadenas a traducir de un programa, presentarlas en un formato uniforme a los traductores, y luego usar el resultado de su trabajo durante la ejecución para mostrar los mensajes traducidos al usuario.

En cuanto a la documentación, sin embargo, la situación sigue siendo un tanto decepcionante. Al principio, traducir documentación puede parecer más fácil que traducir un programa, ya que parece que basta con copiar el archivo fuente de la documentación y empezar a traducir el contenido. Sin embargo, cuando se modifica la documentación original, hacer un seguimiento de las modificaciones se convierte rápidamente en una pesadilla para los traductores. Si se hace manualmente, esta tarea es desagradable y propensa a errores.

Las traducciones obsoletas suelen ser peores que la ausencia de traducción. Los usuarios finales pueden ser engañados por documentación que describe un comportamiento antiguo del programa. Además, no pueden interactuar directamente con los mantenedores porque no hablan inglés. Asimismo, el mantenedor no puede solucionar el problema porque no conoce todos los idiomas a los que se traduce su documentación. Estas dificultades, a menudo causadas por herramientas deficientes, pueden minar la motivación de los traductores voluntarios, lo que agrava aún más el problema.

La ambición del proyecto po4a es facilitar el trabajo de los traductores de la documentación. En particular, crea traducciones de documentación mantenibles.

La idea es reutilizar y adaptar el enfoque de gettext a este campo. Al igual que con gettext, los textos se extraen de sus ubicaciones originales y se presentan a los traductores como catálogos de traducción PO. Los traductores pueden aprovechar las herramientas clásicas de gettext para controlar el trabajo a realizar, colaborar y organizarse como equipos. po4a inyecta entonces las traducciones directamente en la estructura de la documentación para producir archivos fuente traducidos que pueden procesarse y distribuirse igual que los archivos en inglés. Cualquier párrafo que no se traduzca se deja en inglés en el documento resultante, asegurando que los usuarios finales nunca vean una traducción obsoleta en la documentación.

Esto automatiza la mayor parte del trabajo de mantenimiento de la traducción. Descubrir los párrafos que necesitan una actualización resulta muy fácil, y el proceso se automatiza por completo cuando los elementos se reordenan sin más modificaciones. La verificación específica también puede utilizarse para reducir la posibilidad de errores de formato que darían lugar a un documento roto.

Por favor, lea también las Preguntas frecuentes, más abajo en éste documento, para una lista más completa de las ventajas y desventajas de este enfoque al problema.  

Formatos compatibles

Actualmente se han implementado satisfactoriamente algunos tipos de formato de texto:
man (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.
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.
 

Cómo utilizar po4a

La forma más sencilla de utilizar esta herramienta en su proyecto es escribir un fichero de configuración para el programa po4a, e interactuar únicamente con este programa. Consulte su documentación, en po4a(1). El resto de esta sección proporciona más detalles para los usuarios avanzados de po4a que quieran profundizar en su comprensión.  

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.

Las transiciones con corchetes como "[po4a updates po]" representan la ejecución de una herramienta po4a mientras que las transiciones con corchetes como "{ update of master.doc }" representan una modificación manual de los archivos del proyecto. 

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}   |     {actualización de master.doc }           :
     :           |                     |                        :
   XX.doc     |                                                       
 (opcional)    |                   master.doc ->-------->------>+
     :      |                  (nuevo)                                   
     V                         |                                      
  [po4a-gettextize]  doc.XX.po -->+  |
          |      (antiguo)     |                                        
          |       ^                                                  
          | [po4a actualizaciones po]                                         
          V         |                              V
   translation.pot    ^                                              
          | doc. XX.po | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
          |         |                                               
   { translation } | | |
          | ^ V V
          | | {edición manual} |
          | | | |
          V | V V
      doc.XX.po --->---->+<---<-- doc.XX.po addendum master.doc
      (inicial) (actualizado) (optativo) (actualizado) (actualizado)
          :                          |            |             |
          :                                                          
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V                         V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a actualiza las traducciones]
                                                  |
                                                  V
                                                XX.doc
                                             (actualizado)

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>

Aquí, po4a busca la primera línea que coincida con "<sección"> después de la línea que coincida con "Sobre este documento" en la traducción, y añade el apéndice antes de esa línea ya que proporcionamos un límite de inicio, es decir, un límite que marca el comienzo de la siguiente sección. Así que esta línea de cabecera requiere colocar el apéndice después de la sección que contiene "Acerca de este documento", e indicar a po4a que una sección empieza con una línea que contiene la etiqueta "<sección">. Esto es equivalente al ejemplo anterior porque lo que realmente quiere es añadir este apéndice después de "/sección"> o antes de "<<sección">.

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.
•
Pase el argumento -vv a po4a para entender cómo se añaden los anexos a la traducción. También puede ayudar ejecutar po4a en modo depuración para ver la cadena de datos interna real cuando su anexo no se aplica.

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

Esto funciona porque la siguiente linea que encaja con beginboundary «/^=head1/» después de la sección «NOMBRE», es la que declara los autores. Por lo tanto, se colocará el apéndice entre ambas secciones. Tenga en cuenta que si se añade posteriormente otra sección entre NAME y AUTHOR, po4a ubicará de forma indebida el apéndice antes de la sección nueva.

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

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

¿Cómo funciona?

Este capítulo le da una breve visión general del funcionamiento interno de po4a, para que se sienta más seguro a la hora de ayudarnos a mantenerlo y mejorarlo. También puede ayudarle a entender por qué no hace lo que esperaba, y cómo resolver sus problemas.  

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: 

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

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.

Uno de los problemas específicos surge de las codificaciones de archivos y los marcadores BOM. Los analizadores sintácticos simples pueden olvidarse de este problema, que es manejado por "TransTractor::read()" (utilizado internamente para obtener las líneas de un documento de entrada), pero los módulos que dependen de un analizador sintáctico externo deben asegurarse de que todos los archivos se leen con una capa de decodificación PerlIO apropiada. Lo más fácil es abrir el fichero tú mismo, y proporcionar un filehandle o directamente la cadena completa a tu parser externo. Mira en "Pod::read()" y "Pod::parse()" para ver un ejemplo. El contenido leído por el TransTractor se ignora, pero se pasa un nuevo filehandle al analizador externo. La parte importante es el modo "<:encoding($charset)" que se pasa a la función perl open().  

Objetos Po

La clase Locale::Po4a::Po(3pm) se encarga de cargar y usar ficheros PO y POT. Básicamente, puede leer un fichero, añadir entradas, obtener traducciones con el método gettext(), escribir el PO en un fichero. Funciones más avanzadas como fusionar un fichero PO contra un fichero POT o validar un fichero se delegan a msgmerge y msgfmt respectivamente.  

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.  

Proyectos de código abierto que utilizan po4a

Aquí hay una lista muy parcial de proyectos que usan po4a en producción para su documentación. Si desea añadir su proyecto a la lista, envíenos un correo electrónico (o una Merge Request).
•
adduser (man): herramienta de gestión de usuarios y grupos.
•
apt (man, docbook): Gestor de paquetes Debian.
•
aptitude (docbook, svg): gestor de paquetes basado en la terminal para Debian
•
F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): catálogo instalable de aplicaciones FOSS (Software libre y de código abierto) para la plataforma Android.
•
git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): sistema distribuido de control de versiones para el seguimiento de cambios en el código fuente.
•
Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

Este proyecto proporciona una infraestructura para traducir muchas páginas de manual a diferentes idiomas, listas para su integración en varias de las principales distribuciones (Arch Linux, Debian y derivados, Fedora).

•
Stellarium <https://github.com/Stellarium/stellarium> (HTML): un planetario libre de código abierto para su ordenador. po4a se utiliza para traducir las descripciones de la cultura celeste.
•
Jamulus <https://jamulus.io/> (markdown, yaml, HTML): una aplicación FOSS para interferir en línea en tiempo real. La documentación del sitio web se mantiene en varios idiomas utilizando po4a.
•
Otro tema a solucionar: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>
 

Preguntas frecuentes

 

¿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?

De hecho, po4a-updatepo y po4a-translate están obsoletos en favor de po4a. La razón es que, aunque po4a puede utilizarse como sustituto de estos scripts, hay mucha duplicación de código. Los scripts individuales tienen alrededor de 150 líneas de código mientras que el programa po4a tiene 1200 líneas, por lo que hacen mucho además de las funciones internas comunes. La duplicación de código resulta en errores que ocurren en ambas versiones y necesitan dos correcciones. Un ejemplo de tal duplicación son los errores #1022216 en Debian y el problema #442 en GitHub que tenían exactamente la misma solución, pero uno en po4a y el otro 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.

 

VÉASE TAMBIÉN

•
La documentación de la herramienta todo en uno que debes utilizar: po4a(1).
•
La documentación del script individual po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).
•
Los scripts de ayuda adicionales: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).
•
Loa analizadores de cada formato, en particular para ver las opciones aceptadas por cada uno de ellos: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).
•
La implementación de la infraestructura central: Locale::Po4a::TransTractor(3pm) (particularmente importante para entender la organización del código), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Consulte también el archivo CONTRIBUTING.md en el código fuente.
 

AUTORES

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

TRADUCCION

 Jordi Vilalta <jvprat@gmail.com>
 Omar Campagne <ocampagne@gmail.com>

 

Index

NOMBRE
Introducción
¿Por qué po4a?
Formatos compatibles
Cómo utilizar po4a
Esquema detallado del flujo de trabajo po4a
Iniciar un nuevo proyecto de traducción
Actualización de traducciones y documentos
Al utilizar adenda para agregar texto adicional para traducciones
¿Cómo funciona?
TransTractors y arquitectura de proyectos
Analizadores sintácticos de formatos específicos
Objetos Po
Contribuir a po4a
Proyectos de código abierto que utilizan po4a
Preguntas frecuentes
¿Cómo se pronuncia po4a?
¿Por qué están obsoletos los scripts individuales?
¿Qué hay de las otras herramientas de traducción de documentación que usan gettext?
RESUMEN de las ventajas de la metodología basada en gettext
VÉASE TAMBIÉN
AUTORES
TRADUCCION
This document was created by using the manual pages.
Time: 00:28:42 GMT, January 29, 2024
català Deutsch English Esperanto español français hrvatski Magyar Italiano 日本語 Bokmål Nederlands polski Português Português (Brasil) Русский српски језик український 简体中文 简体中文 (how to set the default document language)