Traducción de documentación utilizando Sphinx

Sphinx es una herramienta para crear documentos bonitos. Utiliza sintaxis simple de reStructuredText y puede generar la salida en muchos formatos. Si estás buscando un ejemplo, esta documentación es también creada utilizándola. El complemento más útil para utilizar Sphinx es el servicio Leer los Docs, que creará y publicará tu documentación de forma libre.

No me centraré en la redacción de la documentación en sí, si necesitas ayuda con eso, solo tienes que seguir las instrucciones del sitio web de Sphinx. Una vez que tengas la documentación lista, traducirla es bastante fácil, ya que Sphinx incluye soporte para ello y lo explica muy bien en su Internacionalización. Solo hay que configurar unas pocas directivas e invocar la herramienta sphinx-intl.

Si utilizas el servicio Read the Docs, puedes empezar a crear documentación traducida en Read the Docs. Su Localization and Internationalization cubre prácticamente todo lo que necesitas: crear otro proyecto, establecer su idioma y vincularlo desde el proyecto principal como una traducción.

Ahora solo tienes que traducir el contenido de la documentación. Sphinx genera un archivo PO para cada directorio o archivo de nivel superior, lo que puede suponer una gran cantidad de archivos para traducir (dependiendo de los ajustes de gettext_compact). Puedes importar el archivo index.po a Weblate como componente inicial y, a continuación, configurar el complemento Detección de componentes para que detecte automáticamente todos los demás.

Configuración de componentes

Nombre de componente

Documentation

Máscara de archivos

docs/locales/*/LC_MESSAGES/index.po

Plantilla para traducciones nuevas

docs/locales/index.pot

Formato de archivo

Archivo PO de gettext

Indicadores de traducción

rst-text
Configuración de detección de componentes

Expresión regular utilizada para relacionar con los archivos de traducción

docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po

Personalizar el nombre del componente

Documentation: {{ component|title }}

Definir el archivo de base para traducciones nuevas

docs/locales/{{ component }}.pot

Consejo

¿Preferías que Sphinx genere solo un único archivo PO? Desde Sphinx 3.3.0, puedes hacerlo utilizando:

gettext_compact = "docs"

Puede encontrar varios proyectos de documentación siendo traducidos utilizando este planteamiento: