Guía de Traducción de la Documentación

Esta guía explica cómo traducir la documentación de CryptoBot Python a diferentes idiomas.

Descripción General

La documentación utiliza el soporte de internacionalización (i18n) de Sphinx con sphinx-intl para gestionar las traducciones. Los archivos de traducción se almacenan en formato .po (Portable Object) bajo docs/locale/<language>/LC_MESSAGES/.

Idiomas Disponibles

Idiomas actualmente soportados:

Inglés (en) - Predeterminado
Español (es) - Traducción completa

Requisitos Previos

Instale las dependencias de documentación:

uv sync --extra docs

O directamente:

pip install sphinx sphinx-intl sphinx-rtd-theme myst-parser

Inicio Rápido: Agregar un Nuevo Idioma

1. Generate Translation Templates

Primero, genere los archivos .pot (Portable Object Template):

cd docs
make gettext

Esto crea archivos de plantilla en _build/gettext/.

2. Create Translation Catalog

Cree archivos .po para su idioma (por ejemplo, francés):

cd docs
make update-po LANG=fr

Esto crea archivos locale/fr/LC_MESSAGES/*.po.

3. Translate Content

Edite los archivos .po en locale/fr/LC_MESSAGES/ y complete los campos msgstr:

#: ../../index.md:1
msgid "Welcome to CryptoBot Python's documentation!"
msgstr "Bienvenue dans la documentation de CryptoBot Python!"

Directrices de Traducción:

Traduzca solo los campos msgstr
Mantenga los bloques de código, URLs e identificadores técnicos sin cambios
Preserve el formato markdown
Mantenga una terminología consistente

4. Build Translated Documentation

Compile la documentación en su idioma de destino:

cd docs
make html-lang LANG=fr

El HTML traducido estará en _build/html/fr/.

Actualizar Traducciones Existentes

Cuando la documentación en inglés cambie, actualice los archivos de traducción:

cd docs
make update-po LANG=es

Esto actualiza los archivos .po con nuevas cadenas preservando las traducciones existentes. Las cadenas sin traducir o actualizadas se marcarán como «fuzzy» y necesitarán revisión.

Comandos del Makefile

El docs/Makefile proporciona varios comandos de traducción:

`make gettext`

Genera archivos de plantilla .pot a partir de la documentación fuente.

cd docs
make gettext

`make update-po LANG=<language>`

Actualiza o crea archivos .po para un idioma específico.

::

`make html-lang LANG=<language>`

Compila la documentación HTML en un idioma específico.

::

Ubicación de salida: _build/html/<language>/

Estructura de Archivos

::

Flujo de Trabajo de Traducción

Para Nuevos Traductores

Haga un fork del repositorio

Cree los archivos de traducción:

cd docs
make update-po LANG=<your_language>

Traduzca:
- Edite los archivos .po en locale/<your_language>/LC_MESSAGES/
- Use un editor de .po como Poedit o cualquier editor de texto
- Enfóquese en los campos msgstr
Pruebe su traducción:
```
make html-lang LANG=<your_language>
```
- Abra _build/html/<your_language>/index.html en un navegador
Envíe un pull request con sus traducciones

Para Mantenedores

Cuando se actualice la documentación:

Regenere las plantillas:
```
cd docs
make gettext
```
Actualice todos los catálogos de idiomas:
```
::
```
Revise las traducciones marcadas como fuzzy:
- Busque #, fuzzy en los archivos .po
- Actualice o confirme estas traducciones
- Elimine el marcador #, fuzzy cuando termine

Compile y verifique todos los idiomas:

make html-lang LANG=es
make html-lang LANG=fr

Mejores Prácticas

Calidad de Traducción

Consistencia: Use terminología consistente en todo momento
Contexto: Considere el contexto técnico al traducir
Lenguaje natural: Traduzca el significado, no palabra por palabra
Preservación de código: Nunca traduzca:
- Código Python
- Nombres de variables/funciones
- URLs
- Instrucciones de línea de comandos
- Endpoints de la API

Patrones Comunes

Comentarios de código en ejemplos:

msgid "# Create a client"
msgstr "# Crear un cliente"

Contenido mixto (mantener código sin cambios):

msgid "Call `client.create_invoice()` to create invoices"
msgstr "Llama a `client.create_invoice()` para crear facturas"

URLs y enlaces:

msgid "See [documentation](https://example.com) for details"
msgstr "Ver [documentación](https://example.com) para detalles"

Herramientas

Editores de .po Recomendados

Poedit - Multiplataforma, fácil de usar
Lokalize - Herramienta de traducción de KDE
GTranslator - Herramienta de traducción de GNOME
Editores de texto - VS Code, vim, emacs con resaltado de sintaxis

Validación

Verifique errores en los archivos .po:

msgfmt --check locale/es/LC_MESSAGES/index.po

Integración con Read the Docs

El proyecto está configurado para compilar documentación multilingüe en Read the Docs:

Configuración: .readthedocs.yaml
Los archivos de traducción se generan durante el proceso de compilación
La documentación en español se compila y publica automáticamente

Contribuir con Traducciones

¡Las traducciones son bienvenidas! Así es como puede contribuir:

Revise las traducciones existentes en el directorio locale/
Cree un issue anunciando su traducción
Siga el flujo de trabajo descrito arriba
Envíe un pull request
Los mantenedores revisarán y harán merge

Lista de Verificación de Traducción

Todos los archivos .po actualizados
No quedan marcadores #, fuzzy
La documentación compila sin errores
Las páginas traducidas se muestran correctamente
Los ejemplos de código funcionan como se espera
Los enlaces y referencias funcionan

Solución de Problemas

Errores de Compilación

Error: unsupported locale setting

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
make html-lang LANG=es

Error: sphinx-intl no encontrado

::

La Traducción No Aparece

Verifique que se generaron los archivos .mo:
```
ls locale/es/LC_MESSAGES/*.mo
```
Recompile desde cero:
```
make clean
make html-lang LANG=es
```
Verifique el código de idioma en el encabezado msgstr

Recursos

¿Preguntas?

Para preguntas o problemas con las traducciones:

Abra un issue en GitHub
Contacte a los mantenedores
Revise los archivos .po existentes para ver ejemplos