Load user overrides from PO file

[rose-a]

Hi, this is a proposal for adding the functionality to load user overrides from a gettext po file rather than specifying them explicitly in the config file.

In the current draft, this adds the following options to the plugin config:

plugins: 
  - i18n:
      po_overrides:
        po_dir: locale
        override: [site_name]

where po_dir is the directory path relative to the directory containing the config file where the po files are located, and override is an array of config keys to override.

For each configured language it looks for a file <locale>.po (i.e. en.po) in po_dir, reads the original value of the elements specified in override and tries to find a translation for them in the po file (msgid = original config value). If found, the translation is used as override value.

Corresponding directory structure:

.
├── locale
│   ├── en.po
│   └── fr.po
└── mkdocs.yml

If an explicit override is configured for the language, the explicit one takes precedence.

Rationale

I'm using mkdocs to construct a system for building "operating manuals" for special-purpose machinery, which has to be handed out in the manufacturers language ("original"), but as well in the national language of the country where it is deployed ("translation") and which has to be clearly marked as translation.

The idea is to have a "template" repository which is forked for each new project so that the people doing documentation have as few contact with the inner works of the project structure and build system as possible.

Translation is to be done half-automatically, using a similar approach like mkdocs-mdpo-plugin but purpose built (currently not a mkdocs plugin), which then generates the translated sources from po-files previously extracted from the default language files.

Loading the overrides from the po files allows me to

• Move stuff like site_name, which is content in my opinion, out of the configuration
• Lets me automatically generate a translation for it when a user adds a new language (which potentially happens for each new project)
• Lets me change the default languages title to "operating manual - original" despite the automatic translation (by hardcoding that one in the config)

ToDo

This is still in a draft state which currently works for my special purpose, but propably needs some edge case testing and polishing for general useability. If you're interested in merging, I'll try to invest some more time to add tests, proper docs, etc.

[ultrabug]

Hello @rose-a , that sounds like an amazing proposal, I'm impressed!

Please bear with me while I find the time to get my head into it properly and answer. Thanks!

[rose-a]

Hi there, it's been a while now...

I've rebased this PR on the current main branch and added support for the to-pdf fork of with-pdf (since the latter one seems to be abandoned).

I guess this has propably slipped through, I'm still interested in getting this functionality merged, though.