Configuración

Siempre coloca el plugin mdpo en el archivo mkdocs.yml después de otros plugins que pudieran editar el contenido de tus archivos:

- plugins
  - search
  - include-markdown
  - mdpo
  - minify

Idiomas

languages (list)*

Idiomas a los que traducir tus archivos. Comúnmente definidos como códigos ISO 639.

Nota

Si estás usando el tema mkdocs-material, también puede ser definido en el ajuste de configuración extra.alternate (ver Selector de idioma).

default_language (str)

Idioma original de tus archivos. Si no se define se usará el primer idioma encontrado en languages.

Nota

Si estás usando el tema mkdocs-material, también puede ser definido en el ajuste de configuración theme.language (ver Selector de idioma).

Estructura

locale_dir (str)

Directorio donde los archivos de traducción PO serán ubicados. Si no se define, se usará la raíz de tu documentación (configuración docs_dir), lo cual no te permitirá usar el comando mkdocs serve. La estructura por defecto sería algo como:

Configuración

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr

Árbol de directorios de documentación

📁 docs
├── 📁 es
│   └── 📄 index.md.po
├── 📁 fr
│   └── 📄 index.md.po
└── 📄 index.md

El problema con esta estructura es que no te permite usar el comando mkdocs serve.

La práctica recomendada es organizar tu directorio docs/ con múltiples subdirectorios, uno para archivos de documentación, otro para archivos de traducción, otro para sobreescritura de temas...

Configuración

docs_dir: docs/src

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: ../locale

Árbol de directorios de documentación

📁 docs
├── 📁 locale
│   ├── 📁 es
│   │   └── 📄 index.md.po
│   └── 📁 fr
│       └── 📄 index.md.po
└── 📁 src
    └── 📄 index.md

lc_messages (bool or str)

En el mundo de la traducción de programas es común la creación de una carpeta LC_MESSAGES dentro del directorio de idioma. Si la necesitas, puedes definir este ajuste como true, pero si quieres otro nombre de carpeta, puedes pasar una cadena, o incluso una ruta relativa para crear más de una carpeta entre el directorio de idioma y su contenido:

true

Configuración

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: locale
      lc_messages: true

Árbol de directorios de documentación

📁 docs
├── 📁 locale
│   ├── 📁 es
│   │   └── 📁 LC_MESSAGES
|   │       └── 📄 index.md.po
|   └── 📁 fr
|       └── 📁 LC_MESSAGES
│           └── 📄 index.md.po
└── 📄 index.md

Valor personalizado

Configuración

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: locales
      lc_messages: my-own/subdir

Árbol de directorios de documentación

📁 docs
├── 📁 locales
│   ├── 📁 es
│   │   └── 📁 my-own
|   │       └── 📁 subdir
|   |           └── 📄 index.md.po
|   └── 📁 fr
|       └── 📁 my-own
│           └── 📁 subdir
|               └── 📄 index.md.po
└── 📄 index.md

dest_filename_template (str)

Plantilla para el nombre del archivo destino dentro del directorio site/. Esto es una cadena para una plantilla Jinja2 template válida que será usada para definir donde debe ser colocado el archivo traducido generado dentro del directorio site/.

El valor por defecto es {{language}}/{{file.dest_path}}, siendo file el archivo de documentación original y language el idioma de la traducción.

El contexto para la plantilla incluye:

• language: Idioma de traducción para el archivo.
• file: El archivo Markdown original dentro de tu directorio de documentación.
• Todos los ajustes de configuración del plugin, como languages, default_language, lc_messages, locale_dir, dest_filename_template...

Contenido

translate (list[str])

Parámetros de configuración a traducir. Actualmente sólo están soportados los siguientes parámetros:

• site_name
• site_description

cross_language_search (bool)

Configura si el plugin de búsqueda del tema buscará a través de todos los idiomas. Por defecto está habilitado. Puedes deshabilitarlo para restringir la búsqueda al idioma activo.

El soporte de esta característica actualmente incluye el tema mkdocs-material, el tema por defecto de Mkdocs, el tema de Readthedocs y todos los temas que usen el plugin de búsqueda incluido en Mkdocs.

min_translated_messages (str or int)

Número o porcentaje de mensajes mínimo en todos los archivos para incluir las páginas traducidas para un idioma. Un mensaje de información será mostrado si un idioma no alcanza los requisitos de traducción mínimos.

Especifica como cadena terminada con % como 55% para porcentaje de mensajes totales o como entero como 76 para determinar el número mínimo de mensajes traducidos requeridos para incluir un idioma.

Filtrar por porcentaje

plugins:
  - mdpo:
      languages:
        - en
        - es
      min_translated_messages: 95%

Filtrar por número de mensajes

plugins:
  - mdpo:
      languages:
        - en
        - es
      min_translated_messages: 50

exclude (list[str])

Excluye ciertos archivos de ser traducidos, aunque sigue creando copias de los archivos originales en los idiomas objetivo. Acepta rutas relativas a los archivos desde el directorio docs_dir (directorio de documentación).

Esta configuración es útil si quieres, por ejemplo, excluir un archivo de historial de cambios (changelog) de ser traducido:

Configuración

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: locale
      exclude:
        - changelog.md

Árbol de directorios

📁 docs
├── 📁 locale
│   ├── 📁 es
│   │   └── 📄 index.md.po
|   └── 📁 fr
|       └── 📄 index.md.po
├── 📄 changelog.md
└── 📄 index.md

ignore_extensions (list[str])

Extensiones de archivos que son ignorados de ser añadidos al directorio del sitio, por defecto ['.po', '.pot', '.mo'].

ignore_msgids (list[str])

Puedes ignorar ciertos mensajes de ser volcados a los archivos PO añadiéndolos a esta lista.