Merge 3178cd9 into fed23a7

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.17
+current_version = 0.0.18
 
 [bumpversion:file:mkdocs_mdpo_plugin/__init__.py]
 

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
           - 3.9
         mkdocs-version:
           - 1.1.2
-          - 1.2.1
+          - 1.2.3
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python v${{ matrix.python-version }}

.gitignore

@@ -1,4 +1,4 @@
-# Developmenr
+# Development
 /__main__.py
 /__dev__.*
 /cases/
@@ -10,6 +10,7 @@ prueba.md
 /*.po
 /*.txt
 /src/
+examples/**/**/site/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/es/config.md.po → docs/locale/es/config.md.po

@@ -9,24 +9,6 @@ msgstr ""
 "Siempre coloca el plugin `mdpo` en el archivo `mkdocs.yml` después de otros "
 "plugins que pudieran editar el contenido de tus archivos:"
 
-msgid ""
-"Directory inside your documentation where the PO translation files will be "
-"placed. If not defined, the root of `docs` (`docs_dir` setting) will be "
-"used, so the default layout would be something like:"
-msgstr ""
-"Directorio dentro de tu documentación donde los archivos PO de traducción "
-"serán colocados. Si no se define, se usará la raíz de `docs` (configuración "
-"`docs_dir`), por lo que la estructura por defecto sería algo como:"
-
-msgid ""
-"The default value is `{{language}}/{{page.file.dest_path}}`, being `page` "
-"the original documentation page and `language` the language of the "
-"translation."
-msgstr ""
-"El valor por defecto es `{{language}}/{{page.file.dest_path}}`, siendo "
-"`page` la página de documentación original y `language` el idioma de la "
-"traducción."
-
 msgid "The context for the template includes:"
 msgstr "El contexto para la plantilla incluye:"
 
@@ -51,15 +33,6 @@ msgstr ""
 "Idioma original de tus archivos. Si no se define se usará el primer idioma "
 "encontrado en [`languages`](#languages-list)."
 
-msgid ""
-"Defining it to `locale`, the layout will change a bit, but this doesn't mean"
-" that this new `locale/` folder will be included in the `site/` directory "
-"(see [`dest_filename_template`](#dest_filename_template-str))."
-msgstr ""
-"Definiéndolo a `locale`, la estructura cambiará un poco, pero esto no "
-"significa que esta nueva carpeta `locale/` será incluida en el directorio "
-"`site/` (ver [`dest_filename_template`](#dest_filename_template-str))."
-
 msgid ""
 "In the world of program translation is common the creation of a "
 "`LC_MESSAGES/` folder inside the language directory. If you need it you can "
@@ -82,20 +55,6 @@ msgstr "Árbol de directorios de documentación"
 msgid "true"
 msgstr "true"
 
-msgid "`language`: Translation language for the page."
-msgstr "`language`: Idioma de traducción para la página."
-
-msgid ""
-"`page`: The original Markdown page object inside your documentation "
-"directory."
-msgstr ""
-"`page`: El objeto de la página Markdown original dentro de tu directorio de "
-"documentación."
-
-msgid "`po_filepath`: The path of the PO file wich contains the translations."
-msgstr ""
-"`po_filepath`: La ruta del archivo PO el cual contiene las traducciones."
-
 msgid ""
 "File extensions that are ignored from being added to site directory, "
 "defaults to `['.po', '.pot', '.mo']`."
@@ -124,12 +83,6 @@ msgstr ""
 "válida que será usada para definir donde debe ser colocado el archivo "
 "traducido generado dentro del directorio `site/`."
 
-msgid ""
-"`po`: A [`polib.POFile`][polib.POFile] object with the translations loaded."
-msgstr ""
-"`po`: Un objeto [`polib.POFile`][polib.POFile] con las traducciones "
-"cargadas."
-
 msgid "[mkdocs-material]: https://squidfunk.github.io/mkdocs-material"
 msgstr "[mkdocs-material]: https://squidfunk.github.io/mkdocs-material"
 
@@ -188,3 +141,47 @@ msgid ""
 msgstr ""
 "Puedes ignorar ciertos mensajes de ser volcados a los archivos PO "
 "añadiéndolos a esta lista."
+
+msgid ""
+"The default value is `{{language}}/{{file.dest_path}}`, being `file` the "
+"original documentation file and `language` the language of the translation."
+msgstr ""
+"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."
+
+msgid "`language`: Translation language for the file."
+msgstr "`language`: Idioma de traducción para el archivo."
+
+msgid ""
+"`file`: The original Markdown file object inside your documentation "
+"directory."
+msgstr ""
+"`file`: El archivo Markdown original dentro de tu directorio de "
+"documentación."
+
+msgid ""
+"The problem with this layout is that doesn't allow you to use the command "
+"`mkdocs serve`."
+msgstr ""
+"El problema con esta estructura es que no te permite usar el comando `mkdocs"
+" serve`."
+
+msgid ""
+"Directory where the PO translation files will be placed. If not defined, the"
+" root of your documentation (`docs_dir` setting) will be used, which will "
+"not allow you to use the command `mkdocs serve`. The default layout would be"
+" something like:"
+msgstr ""
+"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:"
+
+msgid ""
+"The recommended practice is to organize your tipical `docs/` directory with "
+"multiple subdirectories, one for documentation files, other for translation "
+"files, other for theme overrides..."
+msgstr ""
+"La práctica recomendada es organizar tu directorio típico `docs/` con "
+"múltiples subdirectorios, uno para archivos de documentación, otro para "
+"archivos de traducción, otro para sobreescritura de temas..."

docs/es/extensions-support/official.md.po → docs/locale/es/extensions-support/official.md.po

@@ -2,9 +2,6 @@
 msgid ""
 msgstr ""
 
-msgid "Official extensions"
-msgstr "Extensiones oficiales"
-
 msgid "*[HTML]: Hyper Text Markup Language"
 msgstr "*[HTML]: Lenguaje de Marcado de Hipertexto"
 
@@ -92,3 +89,6 @@ msgstr "[^1]: Esto es el contenido de una nota al pie."
 
 msgid "[^2]: This is another footnote content."
 msgstr "[^2]: Esto es el contenido de otra nota al pie."
+
+msgid "Official extensions"
+msgstr "Extensiones oficiales"

docs/es/extensions-support/pymdownx.md.po → docs/locale/es/extensions-support/pymdownx.md.po

@@ -2,9 +2,6 @@
 msgid ""
 msgstr ""
 
-msgid "PyMdown extensions"
-msgstr "Extensiones PyMdown"
-
 msgid ""
 "There is no way of skip inline codespan blocks from being included in "
 "translations:"
@@ -87,9 +84,6 @@ msgstr "Contenido de pestaña"
 msgid "~~Delete me~~"
 msgstr "~~Elimíname~~"
 
-msgid "Some inserted content from another file."
-msgstr "Algo de contenido insertado desde otro archivo."
-
 msgid "++ctrl+alt+delete++"
 msgstr "++ctrl+alt+f10++"
 
@@ -105,3 +99,6 @@ msgid ""
 msgstr ""
 "[pymdown-extensions]: https://facelessuser.github.io/pymdown-"
 "extensions/extensions"
+
+msgid "PyMdown extensions"
+msgstr "Extensiones PyMdown"

docs/es/index.md.po → docs/locale/es/index.md.po

@@ -149,9 +149,6 @@ msgstr ""
 "[xgettext-docs]: "
 "https://www.gnu.org/software/gettext/manual/gettext.html#xgettext-Invocation"
 
-msgid "The command `mkdocs serve` doesn't work."
-msgstr "El comando `mkdocs serve` no funciona."
-
 msgid ""
 "As with [mkdocs][mkdocs-docs] you write [Python-Markdown][python-markdown-"
 "docs]'s implementation of Markdown, **mkdocs-mdpo-plugin** uses the "
@@ -170,9 +167,6 @@ msgstr ""
 "soportadas correctamente (ver [Soporte de extensiones][extensions-support-"
 "official])."
 
-msgid "Immprove the mkdocs-material's language selector"
-msgstr "Mejora el selector de idioma de mkdocs-material"
-
 msgid "[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/"
 msgstr "[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/"
 
@@ -212,3 +206,15 @@ msgstr "Proyectos usando mkdocs-mdpo-plugin"
 
 msgid "[hrcgen-docs]: https://hrcgen.ml"
 msgstr "[hrcgen-docs]: https://hrcgen.ml/es/"
+
+msgid "Improve the mkdocs-material's language selector"
+msgstr "Mejora el selector de idioma de mkdocs-material"
+
+msgid ""
+"The command `mkdocs serve` doesn't work if you store the PO files inside the"
+" documentation folder. Use another layout like the explained in "
+"[`locale_dir` configuration](config/#locale_dir-str)."
+msgstr ""
+"El comando `mkdocs serve` no funciona si almacenas los archivos PO dentro "
+"del directorio de documentación. Usa otro layout como el explicado en [la "
+"configuration `locale_dir`](config/#locale_dir-str)."

docs/es/tested-plugins/api-documentation-building.md.po → docs/locale/es/tested-plugins/api-documentation-building.md.po

@@ -2,9 +2,6 @@
 msgid ""
 msgstr ""
 
-msgid "API documentation building"
-msgstr "Construcción de documentación de API"
-
 msgid "[API documentation building][api-documentation-building]"
 msgstr "[Construcción de documentación de API][api-documentation-building]"
 
@@ -15,23 +12,23 @@ msgstr ""
 "[api-documentation-building]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-"
 "Plugins#api-documentation-building"
 
-msgid "Remove empty directories walking through all nested subdirectories."
-msgstr ""
-"Elimina los directorios vacíos iterando por todos los subdirectorios "
-"anidados."
-
 msgid ""
 "You can translate your docstrings using this plugin with mkdocs-mdpo-plugin."
 msgstr ""
 "Puedes traducir tus cadenas de documentación usando este plugin con mkdocs-"
 "mdpo-plugin."
 
-msgid "**`mkdocs_mdpo_plugin.io.remove_empty_directories_from_dirtree`**"
-msgstr "**`mkdocs_mdpo_plugin.io.remove_empty_directories_from_dirtree`**"
-
-msgid "Top directory tree path."
-msgstr "Ruta al directorio padre de todos."
-
-#, fuzzy
 msgid "[mkdocstrings-github-link]: https://github.com/pawamoy/mkdocstrings"
 msgstr "[mkdocstrings-github-link]: https://github.com/pawamoy/mkdocstrings"
+
+msgid "Value to check."
+msgstr "Valor a comprobar."
+
+msgid "Function documentation."
+msgstr "Documentación de función."
+
+msgid "**`mkdocs_mdpo_plugin.docs_helper.function`**"
+msgstr "**`mkdocs_mdpo_plugin.docs_helper.function`**"
+
+msgid "API documentation building"
+msgstr "Construcción de documentación de API"

docs/es/tested-plugins/navigation-and-page-building.md.po → docs/locale/es/tested-plugins/navigation-and-page-building.md.po

@@ -2,9 +2,6 @@
 msgid ""
 msgstr ""
 
-msgid "Navigation and page building"
-msgstr "Navegación y construcción de páginas"
-
 msgid ""
 "[navigation-and-page-building]: "
 "https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#navigation--page-"
@@ -16,3 +13,6 @@ msgstr ""
 
 msgid "[Navigation and page building][navigation-and-page-building]"
 msgstr "[Navegación y construcción de páginas][navigation-and-page-building]"
+
+msgid "Navigation and page building"
+msgstr "Navegación y construcción de páginas"

docs/config.md → docs/src/config.md

@@ -41,9 +41,10 @@ Original language of your files. If not defined, the first language found in
 <!-- mdpo-disable-next-line -->
 ### **`locale_dir`** (*str*)
 
-Directory inside your documentation where the PO translation files will be
-placed. If not defined, the root of `docs` (`docs_dir` setting) will be used,
-so the default layout would be something like:
+Directory where the PO translation files will be placed. If not defined,
+the root of your documentation (`docs_dir` setting) will be used,
+which will not allow you to use the command `mkdocs serve`. The default
+layout would be something like:
 
 === "Configuration"
 
@@ -67,20 +68,25 @@ so the default layout would be something like:
     └── index.md
     ```
 
-Defining it to `locale`, the layout will change a bit, but this doesn't mean
-that this new `locale/` folder will be included in the `site/` directory
-(see [`dest_filename_template`](#dest_filename_template-str)).
+The problem with this layout is that doesn't allow you to use the
+command `mkdocs serve`.
+
+The recommended practice is to organize your tipical `docs/` directory
+with multiple subdirectories, one for documentation files, other for
+translation files, other for theme overrides...
 
 === "Configuration"
 
     ```yaml
+    docs_dir: docs/src
+
     plugins:
       - mdpo:
           languages:
             - en
             - es
             - fr
-          locale_dir: locale
+          locale_dir: ../locale
     ```
 
 === "Documentation directories tree"
@@ -89,13 +95,13 @@ that this new `locale/` folder will be included in the `site/` directory
     docs
     ├── locale
     │   ├── es
-    │   │   └── index.md.po
-    |   └── fr
-    |       └── index.md.po
-    └── index.md
+    │   │   └── index.md.po
+    │   └── fr
+    │       └── index.md.po
+    └── src
+        └── index.md
     ```
 
-
 <!-- mdpo-disable-next-line -->
 ### **`lc_messages`** (*bool* or *str*)
 
@@ -172,15 +178,13 @@ Template for destination file name inside `site/` directory. This is a valid
 [Jinja2 template][jinja2-template] string that will be used to define where
 should be placed the generated translated file inside the `site/` directory.
 
-The default value is `{{language}}/{{page.file.dest_path}}`, being `page` the
-original documentation page and `language` the language of the translation.
+The default value is `{{language}}/{{file.dest_path}}`, being `file` the
+original documentation file and `language` the language of the translation.
 
 The context for the template includes:
 
-- `language`: Translation language for the page.
-- `page`: The original Markdown page object inside your documentation directory.
-- `po_filepath`: The path of the PO file wich contains the translations.
-- `po`: A [`polib.POFile`][polib.POFile] object with the translations loaded.
+- `language`: Translation language for the file.
+- `file`: The original Markdown file object inside your documentation directory.
 - All the configuration settings of the plugin such as `languages`,
   `default_language`, `lc_messages`, `locale_dir`, `dest_filename_template`
   itself...