SmallCountry/infra-core

Fork 0

🌍 Traducción al inglés de la documentación #1

New issue

Open

opened 2026-05-14 22:30:09 +00:00 by tonatiuh · 2 comments

tonatiuh commented

2026-05-14 22:30:09 +00:00

Owner

Propuesta

Traducir toda la documentación de SmallCountry al inglés, sumándola a los idiomas ya existentes (español y portugués brasileño).

Motivación

El proyecto ya es bilingüe ES + pt_BR con ~200 archivos traducidos vía el plugin mkdocs-static-i18n
Añadir inglés daría visibilidad internacional al proyecto, abriéndolo a colaboradores, investigadores y apicultores de habla inglesa
La infraestructura de i18n ya está montada (plugin, docs_structure: folder, nav_translations). Añadir un tercer idioma es cuestión de:
- Crear docs/en/ con los mismos 188 archivos que docs/pt_BR/
- Añadir locale: en en mkdocs.yml
- Añadir las traducciones de navegación (nav_translations para en)
- Traducir el contenido progresivamente

Alcance

Misma estructura de carpetas que docs/pt_BR/
Banner de construcción ya soportado en overrides/main.html con i18n_page_locale
El trabajo de traducción puede hacerse progresivamente, empezando por index.md, proyectos/ y legal/

Abierto vía opencode

## Propuesta Traducir toda la documentación de SmallCountry al inglés, sumándola a los idiomas ya existentes (español y portugués brasileño). ## Motivación - El proyecto ya es bilingüe **ES + pt_BR** con ~200 archivos traducidos vía el plugin `mkdocs-static-i18n` - Añadir **inglés** daría visibilidad internacional al proyecto, abriéndolo a colaboradores, investigadores y apicultores de habla inglesa - La infraestructura de i18n ya está montada (plugin, `docs_structure: folder`, `nav_translations`). Añadir un tercer idioma es cuestión de: - Crear `docs/en/` con los mismos 188 archivos que `docs/pt_BR/` - Añadir `locale: en` en `mkdocs.yml` - Añadir las traducciones de navegación (`nav_translations` para `en`) - Traducir el contenido progresivamente ## Alcance - Misma estructura de carpetas que `docs/pt_BR/` - Banner de construcción ya soportado en `overrides/main.html` con `i18n_page_locale` - El trabajo de traducción puede hacerse progresivamente, empezando por `index.md`, `proyectos/` y `legal/` --- _Abierto vía opencode_

tonatiuh commented

2026-05-14 22:33:24 +00:00

Author

Owner

Investigación: cómo maneja `mkdocs-static-i18n` las páginas sin traducir

El plugin que usamos (mkdocs-static-i18n v1.3.1) tiene una opción clave:

fallback_to_default: true   # valor por defecto

¿Qué hace?

Cuando un usuario navega en un idioma (ej. inglés) y la página no existe en ese idioma, el plugin silenciosamente sirve la versión del idioma por defecto (español). Sin warning, sin error, sin enlace roto.

¿Por qué es importante para esta propuesta?

Significa que no necesitamos traducir todos los archivos de golpe. Podemos:

Añadir locale: en al mkdocs.yml con solo docs/en/index.md traducido
El resto de páginas (188 archivos sin traducir) mostrarán automáticamente la versión en español
Ir traduciendo progresivamente: cada vez que se traduce una página, el plugin la sirve en inglés en vez del fallback
Sin warnings, sin builds rotos, sin prisas

Configuración actual

Nuestro mkdocs.yml no declara fallback_to_default explícitamente, así que usa el valor por defecto true. El comportamiento de fallback ya está activo — solo hay que añadir el idioma.

Próximo paso técnico

Añadir al mkdocs.yml:

plugins:
  - i18n:
      languages:
        - locale: en
          default: false
          name: English
          build: true
      nav_translations:
        en:
          Inicio: Home
          ...

Crear docs/en/index.md con la landing page traducida. El build generará site/en/ con index en inglés y todo lo demás en español (fallback).

Investigado y comentado vía opencode

## Investigación: cómo maneja `mkdocs-static-i18n` las páginas sin traducir El plugin que usamos (`mkdocs-static-i18n` v1.3.1) tiene una opción clave: ```yaml fallback_to_default: true # valor por defecto ``` ### ¿Qué hace? Cuando un usuario navega en un idioma (ej. inglés) y la página **no existe** en ese idioma, el plugin **silenciosamente sirve la versión del idioma por defecto** (español). Sin warning, sin error, sin enlace roto. ### ¿Por qué es importante para esta propuesta? Significa que **no necesitamos traducir todos los archivos de golpe**. Podemos: 1. Añadir `locale: en` al `mkdocs.yml` con solo `docs/en/index.md` traducido 2. El resto de páginas (188 archivos sin traducir) mostrarán automáticamente la versión en español 3. Ir traduciendo progresivamente: cada vez que se traduce una página, el plugin la sirve en inglés en vez del fallback 4. Sin warnings, sin builds rotos, sin prisas ### Configuración actual Nuestro `mkdocs.yml` **no** declara `fallback_to_default` explícitamente, así que usa el valor por defecto `true`. El comportamiento de fallback ya está activo — solo hay que añadir el idioma. ### Próximo paso técnico Añadir al `mkdocs.yml`: ```yaml plugins: - i18n: languages: - locale: en default: false name: English build: true nav_translations: en: Inicio: Home ... ``` Crear `docs/en/index.md` con la landing page traducida. El build generará `site/en/` con index en inglés y todo lo demás en español (fallback). --- *Investigado y comentado vía opencode*

tonatiuh commented

2026-05-14 22:39:26 +00:00

Author

Owner

✅ Implementado — commit `7829641`

Cambios realizados

mkdocs.yml: añadido locale: en con nav_translations completas (70+ entradas de navegación traducidas al inglés)
docs/en/index.md: landing page completa traducida al inglés (manifiesto, compromisos, proyectos, manual, aviso legal)
overrides/main.html: banner de construcción ahora es trilingüe (ES / EN / PT)
Copyright: añadido enlace a /en/legal/ en el footer

Cómo funciona

El sitio ahora construye en 3 idiomas:

Building es  documentation → /site/
Building en  documentation → /site/en/
Building pt_BR documentation → /site/pt_BR/

El 99% de las páginas en inglés muestran la versión en español como fallback. Solo index.md está traducido de momento. El plugin mkdocs-static-i18n con fallback_to_default: true (valor por defecto) hace que cualquier página sin traducción sirva silenciosamente la versión en español. Sin warnings, sin errores.

Próximos pasos

Traducir progresivamente el resto de archivos (empezando por proyectos/ y legal/). Cada archivo que se traduce y se coloca en docs/en/ reemplaza automáticamente al fallback en español para los visitantes de habla inglesa.

Build

INFO - Documentation built in 20.85 seconds

Commit y comentario vía opencode

## ✅ Implementado — commit `7829641` ### Cambios realizados - **`mkdocs.yml`**: añadido `locale: en` con `nav_translations` completas (70+ entradas de navegación traducidas al inglés) - **`docs/en/index.md`**: landing page completa traducida al inglés (manifiesto, compromisos, proyectos, manual, aviso legal) - **`overrides/main.html`**: banner de construcción ahora es trilingüe (ES / EN / PT) - **Copyright**: añadido enlace a `/en/legal/` en el footer ### Cómo funciona El sitio ahora construye en **3 idiomas**: ``` Building es documentation → /site/ Building en documentation → /site/en/ Building pt_BR documentation → /site/pt_BR/ ``` **El 99% de las páginas en inglés muestran la versión en español como fallback.** Solo `index.md` está traducido de momento. El plugin `mkdocs-static-i18n` con `fallback_to_default: true` (valor por defecto) hace que cualquier página sin traducción sirva silenciosamente la versión en español. Sin warnings, sin errores. ### Próximos pasos Traducir progresivamente el resto de archivos (empezando por `proyectos/` y `legal/`). Cada archivo que se traduce y se coloca en `docs/en/` reemplaza automáticamente al fallback en español para los visitantes de habla inglesa. ### Build ``` INFO - Documentation built in 20.85 seconds ``` --- *Commit y comentario vía opencode*

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

SmallCountry/infra-core#1

No description provided.

Rows
Columns

🌍 Traducción al inglés de la documentación #1

Propuesta

Motivación

Alcance

Investigación: cómo maneja mkdocs-static-i18n las páginas sin traducir

¿Qué hace?

¿Por qué es importante para esta propuesta?

Configuración actual

Próximo paso técnico

✅ Implementado — commit 7829641

Cambios realizados

Cómo funciona

Próximos pasos

Build

Investigación: cómo maneja `mkdocs-static-i18n` las páginas sin traducir

✅ Implementado — commit `7829641`