Manejo de la traducción con archivos .po

[cychitivav]

Hola, estuve explorando la solución que está en https://www.sphinx-doc.org/en/master/usage/advanced/intl.html y que se mencionó en el issue #3249 de la documentación original, y me parece que es una forma interesante para hacer traducciones automáticas y luego irlas mejorando con PRs..

He realizado parte de lo que menciono en https://github.com/cychitivav/ros2_documentation/tree/multilanguage, pero quiero primero hacer una discusión al respecto antes de abrir el pull request.

Funcionamiento

La forma sugerida por Sphinx para realizar la traducción es utilizando archivos .po, esto con el fin de evitar modificar y evitar el riesgo de perder contenidos en la documentación original dentro de la carpeta source. A grandes rasgos, el funcionamiento es el siguiente:

En línea de comandos, esto se reduce a:

make gettext
make updatepo
make html # o multiversion

Note: Si se desea realizar pruebas especificar el idioma para evitar que se generen archivos en todos los idiomas. Por ejemplo: make -e LANGUAGES=es html

Otro punto importante es que para mantener los archivos en varios idiomas y evitar que se sobreescribieran, modifiqué la ruta a build/html/es/

Lo único que se debería configurar es el idioma a traducir, cambiando el valor de la variable LANGUAGES dentro del Makefile.

LANGUAGES   = es

Esta versión que cree es multilenguaje, es decir, tiene la opción de generar los html y archivos po para cada lenguaje que se especifique (LANGUAGES = en es fr ....

Archivos PO

Los archivos po son utilizados ampliamente porque es una estructura de catálogo de mensajes, esto quiere decir que para cada mensaje (o cadena de texto) se puede asignar una traducción o equivalencia y sphinx actualiza la documentación con estas traducciones, únicamente especificando el idioma que se desea.

Estructura

Como mencione anteriormente, es una estructura de catálogo y por cada cadena de texto existen estos campos:

#: ../../source/Tutorials/Advanced/Simulators/Gazebo.rst:7
msgid "Setting up a robot simulation (Gazebo)"
msgstr ""

Esto referencia a la línea exacta de la documentación original (#: ...), el mensaje que se quiere traducir (msgid) y la traducción (msgstr). Además, estos mensajes están referenciados por un ID (que se puede agregar al archivo .po si es necesario) con el fin de que al agregar texto a los archivos originales (.rst), no pierdan la referencia, muy similar a como funciona git.

Seguimiento de cambios

Un problema que quizá pueda surgir cuando se actualiza la documentación original, es la pérdida de la traducción. Para esto, la herramienta sphinx-intl permite hacer el seguimiento, pues al actualizar los archivos .pot con make gettext se pueden dar los siguientes casos:

• los msgid no cambian: estos mensajes no se verán afectados y su traducción tampoco.
• se eliminan algunos msgid: Al eliminarse la documentación original, su traducción también.
• Se agregan msgid: claramente no habría traducción para estos archivos, y al generar el html, se mostraría la documentación en inglés.
• Se modifican msgid: Este último caso presenta una funcionalidad adicional, y es que make text utiliza una comparación difusa para saber que tanto cambió la documentación, y si el cambio es mínimo, agrega la bandera fuzzy

  #, fuzzy
  msgid ""
  msgstr ""

  Lo que permitiría guardar la traducción anterior temporalmente hasta actualizarla. Por otro lado, si el cambio es muy drástico, se eliminará la traducción.

Traducción automática

Realicé la traducción de https://docs.ros.org/en/humble/ con google translate y a mi parecer no estan mala, así que aprovechando la estructura de los archivos .po, se podría realizar la traducción automática de cada msgid y subirla al repositorio y realizar modificaciones a traducciones incorrectas mediante PRs, así como lo menciona @olivier-stasse en ros2#3249 (comment).

Ventajas

• Una de las ventajas es que podemos editar sin modificar la documentación original en inglés, lo que podría llegar a escalarse al repositorio principal si se acepta el manejo de las traducciones solo modificando la carpeta locale.
• Como se puede ver, la forma de catalogo hace que las personas con conocimientos no tan técnicos puedan traducir o corregir frases y párrafos cortos.

Action

Para automatizar este proceso se podría dividir en dos tareas:

1. Actualizar los archivos .po cada vez que se realice un cambio en la carpeta source de determinadas ramas
2. Manejar las traducciones faltantes, en dónde veo que hay dos formas de abordarlo
   1. Traducirlas automáticamente con googletrans o una herramienta similar.
   2. Generar un issue o una alerta con los msgid sin traducción o con la bandera fuzzy

Esta primera acción ya la implementé aquí, y para la segunda parte ya actualicé la acción para encontrar los mensajes sin traducir:

# msgfmt --check --statistics locale/es/LC_MESSAGES/Installation.po 
30 translated messages.

# msgfmt --check --statistics locale/es/LC_MESSAGES/Tutorials/Advanced/FastDDS-Configuration.po 
0 translated messages, 82 untranslated messages.

Pero aún falta el manejo de estos archivos, y espero su opinión al respecto.

[cychitivav]

Me parece que hacer una traducción automática y luego mejorarlas con PRs es una buena forma, aunque no me gustaría que se perdiera el trabajo ya realizado por la comunidad. Así que estaba en la tarea de pasar los archivos .rst traducidos a los .po.

Procedimiento

1. Generar los archivos po de la versión original y la traducida.
2. Copiar el msgid de la versión traducida y pegarla en los msgstr de la versión original.

Para esto utilicé la librería polib de Python, en el siguiente código:

import polib
import glob2


files = glob2.glob(r'traducidos/**/*.po')

for f in files:
    print(f, 'locale/es/LC_MESSAGES/'+f.replace('traducidos/',''))
    po_traducido = polib.pofile(f)
    po_ingles = polib.pofile('locale/es/LC_MESSAGES/'+f.replace('traducidos/',''))

    for e_t, e_i in zip(po_traducido, po_ingles):
        e_i.msgstr = e_t.msgid

    po_ingles.save()

Resultados

Antes de pasar todos los archivos, busqué los que estaban traducidos y sin conflictos de merge:

.
├── Citations.po
├── Contact.po
├── Installation
│   ├── Alternatives
│   │   ├── Latest-Development-Setup.po
│   │   ├── RHEL-Development-Setup.po
│   │   ├── RHEL-Install-Binary.po
│   │   ├── Ubuntu-Development-Setup.po
│   │   ├── Ubuntu-Install-Binary.po
│   │   ├── Windows-Development-Setup.po
│   │   └── macOS-Development-Setup.po
│   ├── Alternatives.po
│   ├── DDS-Implementations
│   │   ├── Install-Connext-Security-Plugins.po
│   │   ├── Install-Connext-University-Eval.po
│   │   ├── Working-with-Eclipse-CycloneDDS.po
│   │   ├── Working-with-GurumNetworks-GurumDDS.po
│   │   └── Working-with-eProsima-Fast-DDS.po
│   ├── DDS-Implementations.po
│   ├── Maintaining-a-Source-Checkout.po
│   ├── RHEL-Install-RPMs.po
│   ├── Testing.po
│   ├── Ubuntu-Install-Debians.po
│   └── Windows-Install-Binary.po
├── Installation.po
├── Related-Projects
│   ├── Intel-ROS2-Projects.po
│   └── Nvidia-ROS2-Projects.po
├── The-ROS2-Project
│   ├── Contributing
│   │   ├── Code-Style-Language-Versions.po
│   │   ├── Contributing-To-ROS-2-Documentation.po
│   │   ├── Developer-Guide.po
│   │   ├── Migration-Guide-Python.po
│   │   ├── Migration-Guide.po
│   │   ├── Quality-Guide.po
│   │   └── Windows-Tips-and-Tricks.po
│   └── Contributing.po
├── Tutorials
│   ├── Beginner-CLI-Tools
│   │   ├── Introducing-Turtlesim
│   │   │   └── Introducing-Turtlesim.po
│   │   ├── Understanding-ROS2-Parameters
│   │   │   └── Understanding-ROS2-Parameters.po
│   │   └── Understanding-ROS2-Topics
│   │       └── Understanding-ROS2-Topics.po
│   ├── Demos
│   │   ├── Content-Filtering-Subscription.po
│   │   ├── Intra-Process-Communication.po
│   │   ├── Logging-and-logger-configuration.po
│   │   ├── Managed-Nodes.po
│   │   ├── Quality-of-Service.po
│   │   ├── Real-Time-Programming.po
│   │   ├── Rosbag-with-ROS1-Bridge.po
│   │   └── dummy-robot-demo.po
│   └── Intermediate
│       └── Launch
│           ├── Creating-Launch-Files.po
│           ├── Launch-Main.po
│           ├── Launch-system.po
│           └── Using-Event-Handlers.po
└── index.po

14 directories, 48 files

Pero al actualizar los archivos po y generar el html, se producieron incongruencias así que eliminé los archivos con problemas, obteniendo:

.
├── Citations.po
├── Contact.po
├── Installation
│   ├── Alternatives
│   │   └── Latest-Development-Setup.po
│   ├── Alternatives.po
│   ├── DDS-Implementations
│   │   ├── Install-Connext-University-Eval.po
│   │   ├── Working-with-Eclipse-CycloneDDS.po
│   │   └── Working-with-eProsima-Fast-DDS.po
│   ├── Maintaining-a-Source-Checkout.po
│   └── Testing.po
├── Installation.po
├── Related-Projects
│   ├── Intel-ROS2-Projects.po
│   └── Nvidia-ROS2-Projects.po
├── The-ROS2-Project
│   ├── Contributing
│   │   ├── Code-Style-Language-Versions.po
│   │   ├── Migration-Guide-Python.po
│   │   ├── Quality-Guide.po
│   │   └── Windows-Tips-and-Tricks.po
│   └── Contributing.po
├── Tutorials
│   ├── Demos
│   │   ├── Content-Filtering-Subscription.po
│   │   ├── Intra-Process-Communication.po
│   │   ├── Managed-Nodes.po
│   │   ├── Quality-of-Service.po
│   │   ├── Real-Time-Programming.po
│   │   ├── Rosbag-with-ROS1-Bridge.po
│   │   └── dummy-robot-demo.po
│   └── Intermediate
│       └── Launch
│           ├── Launch-Main.po
│           ├── Launch-system.po
│           └── Using-Event-Handlers.po
└── index.po

10 directories, 28 files

Si se llegaran a utilizar los archivos po, se perderían 20 archivos ya traducido; además de necesitar revisar los 28 archivos que pasé.

Note: Cabe aclarar que me preocupa la autoría de las traducciones y me gustaría buscar una forma de solucionarlo.

[fmrico]

Gracias por ampujar esto :)

Mi duda aquí es cómo se gestiona que haya un cambio en el documento original en inglés 🤔

[JimmyTzuc]

Los conflictos a la hora de hacer un merge no seran bastantes? Es decir, yo levanto un PR, pero antes que yo haga merge alguien mas lo hizo y en mi rama ademas de estar desactualizada tendra conflictos por los archivos .mo que basicamente son los archivos .po ya compilados, entonces me toca como dev o traslator resolver conflictos antes de merge.

[JimmyTzuc]

Encontre esta documentacion igual, es con .mo y .po tambien: https://babel.pocoo.org/en/latest/

[jsduenass]

Hola @cychitivav

Me parece muy interesante tu iniciativa en la ultima reunión de ROS en español se dio luz verde para probar esta alternativa. Sin embargo la idea no es afectar lo que ya se ha venido trabajando hasta el momento. La idea es aprovechar que salio una nueva versión iron y hacer una prueba piloto sobre esta. He creado la rama feat/translate/iron sobre la cual podemos realizar las pruebas.

Cualquier cosa de los pasos a seguir podemos seguir discutiendolo en este issue y se se ve la necesidad podemos crear un post en discourse.

Saludos y gracias por proponer esta idea

[fmrico]

Creo que se comentó usar un branch creado desde una de las ramas de distros. Por ejemplo, iron-po

[jsduenass]

Creo que se comentó usar un branch creado desde una de las ramas de distros. Por ejemplo, iron-po

Si exacto, por el momento la llame feat/translate/iron pero si quieres podemos llamarla bajo otra convensión sea feat/po-files/iron o iron-po.