Saltar a contenido

mkdocs-mdpo-plugin

Traducciones para Mkdocs usando archivos PO, totalmente personalizable. Compatible con mkdocs-material, basado en mdpo.

Instalación

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.

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 serve no funciona.
  • Actualmente, los mensajes editados no son marcados como fuzzy como hace xgtettext.

Mejora el selector de idioma de mkdocs-material

Si estás usando el tema de mkdocs-material, puedes instalar el plugin mkdocs-material-relative-language-selector para hacer relativos los links entre idiomas dentro de la misma página y eliminar el idioma actualmente desplegado del selector de idiomas:

pip install mkdocs-material-relative-language-selector
plugins:
  - search
  - material-relative-language-selector
  - mdpo
plugins:
  - search
  - material-relative-language-selector:
      root_domain: true
  - mdpo

Proyectos usando mkdocs-mdpo-plugin