ogDocumentation/README-i18n.md

Documentación i18n con MkDocs

Este repositorio contiene la documentación multilingüe (español e inglés) gestionada con MkDocs.

1. Estructura del Proyecto

La carpeta principal i18n está organizada de la siguiente manera:

i18n-docu/
├── docs/
│   ├── assets/
│   │   ├── css/
│   │   └── images/
│   ├── en/
│   │   ├── administration/
│   │   ├── developer/
│   │   ├── index_installation.md
│   │   ├── index_release.md
│   │   └── index.md
│   └── es/
│       ├── administration/
│       ├── developer/
│       ├── index_installation.md
│       ├── index_release.md
│       └── index.md
├── requirements.txt
├── setup_venv.sh
└── README.md

• docs/: Contiene todos los archivos de documentación
  • assets/: Recursos estáticos como CSS e imágenes
  • en/: Documentación en inglés
  • es/: Documentación en español

2. Configuración del Entorno

Para configurar el entorno de desarrollo, utiliza el script proporcionado que creará un entorno virtual e instalará todas las dependencias necesarias:

# Desde la carpeta raíz del proyecto i18n-docu
./setup_venv.sh

El script realiza las siguientes acciones:

1. Crea un entorno virtual Python llamado og_venv
2. Activa el entorno virtual
3. Instala todas las dependencias desde requirements.txt

Para activar manualmente el entorno virtual después de la configuración inicial:

source og_venv/bin/activate

3. Iniciando el Servidor MkDocs

Una vez que el entorno virtual esté activado, puedes iniciar el servidor MkDocs con la siguiente sintaxis:

mkdocs serve -a IP:PUERTO

Por ejemplo, para iniciar el servidor en la dirección 127.0.0.1 y el puerto 8000:

mkdocs serve -a 127.0.0.1:8000

También puedes ejecutar el servidor con la configuración predeterminada:

mkdocs serve

Esto iniciará el servidor en http://127.0.0.1:8000 por defecto.

4. Generación del Build

Para generar la versión estática de la documentación (build), ejecuta:

mkdocs build

Este comando creará una carpeta site/ con todos los archivos HTML y recursos necesarios para publicar la documentación. Los archivos generados se pueden desplegar en cualquier servidor web estático.

5. Generación de PDFs

Para generar versiones en PDF de la documentación, utiliza la variable de entorno ENABLE_EXPORT_PDF:

ENABLE_EXPORT_PDF=1 mkdocs build

Esto generará archivos PDF correspondientes a cada página de la documentación y los incluirá en la carpeta site/pdf/.

6. Gestión Multilingüe

La documentación se mantiene en dos idiomas: español (primario) e inglés (secundario).

Proceso de trabajo para la documentación multilingüe:

1. Primero se crean/editan los archivos en español dentro de la carpeta docs/es/
2. Luego estos archivos se traducen y se colocan en la carpeta docs/en/ manteniendo la misma estructura de carpetas y nombres de archivo

Por ejemplo:

• Si se edita docs/es/developer/api.md
• La versión en inglés debe crearse en docs/en/developer/api.md

[!TIP] Mantener sincronizadas ambas versiones cada vez que se realicen cambios en los documentos. No obstante, se recomienda realizar la traducción una vez se tenga una versión definitiva del documento en español.