mkdocs-mdpo-plugin¶
Traducciones para Mkdocs usando archivos PO, totalmente personalizable. Compatible con mkdocs-material, basado en mdpo.
Instalar¶
pip install mkdocs-mdpo-plugin
Uso¶
Habilita el plugin en tu mkdocs.yml:
plugins:
- mdpo
Configuración mínima¶
Con mkdocs-material¶
theme:
name: material
language: en
extra:
alternate:
- name: English
lang: en
- name: Español
link: es
lang: es
plugins:
- mdpo
Por separado¶
plugins:
- mdpo:
languages:
- en # el primer idioma es el original
- es
Ambas configuraciones previas crearán la misma estructura de archivos construyendo la documentación. Dada la siguiente estructura en un directorio docs/:
📁 docs
└── 📄 index.md
Después de la construcción, obtendrás:
📁 docs
├── 📁 es
│ └── 📄 index.md.po
└── 📄 index.md
Simplemente traduce las cadenas en docs/es/index.md.po al español, construye de nuevo con mkdocs build y el directorio site/ se verá tal que:
📁 site
├── 📄 404.html
├── 📁 assets
│ ├── 📁 images
│ ├── 📁 javascripts
│ └── 📁 stylesheets
├── 📁 es
│ └── 📄 index.html
├── 📄 index.html
├── 📄 sitemap.xml
└── 📄 sitemap.xml.gz
Cómo funciona¶
mkdocs-mdpo-plugin está basado en mdpo el cual es un programa para traducir contenido Markdown complaciente con CommonMark usando archivos PO.
Consejo
Ver también la aproximación tradicional para traducciones Markdown (inglés) y la aproximación mdpo (inglés).
Ya que con mkdocs escribes la implementación Markdown de Python-Markdown, mkdocs-mdpo-plugin usa el xml.etree.ElementTree para traducir el resto de mensajes del HTML personalizado creado por las extensiones. Esta es la razón por la que activando algunas de ellas el proceso de traducción debe ser ajustado algo para poder ser soportadas correctamente (ver Soporte de extensiones).
Limitaciones conocidas¶
- El comando
mkdocs serveno funciona si almacenas los archivos PO dentro del directorio de documentación. Usa otro layout como el explicado en la configurationlocale_dir. - Actualmente, los mensajes editados no son marcados como fuzzy como hace xgtettext.