Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Load user overrides from PO file #296

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

rose-a
Copy link
Contributor

@rose-a rose-a commented Mar 7, 2024

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
Copy link
Owner

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants