[Feature] Option to insert/inject content for fallback lang pages.

Andre601 commented 8 months ago

I'm in the process of implementing multiple languages into my docs using this plugin.

For various reasons can I not translate all pages tho (i.e. auto-generated ones from code or other source files). I still want to display them, so I use the fallback option for this.

With all that said, do I still want to display text, informing the user about the page not being translated. But I also don't want them to copy over the page only to add that notice.

So I now want to suggest an option/way to allow inserting text into a fallback page.

One way I could think of is to add a jinja2 variable to use like is_fallback. This would allow to create template overrides to display text if the page is a fallback.

Tho, then again the issue appears on how this text could be translated... 😅 Maybe someone here has an idea?

kamilkrzyskow commented 8 months ago

The plugin already provides two context variables that would allow you to find out whether or not is_fallback is True: https://ultrabug.github.io/mkdocs-static-i18n/setup/using-i18n-context/

In our docs we do exactly that, and insert a text to the announce bar with overrides. The text prompt is input manually into the Jinja2 syntax: https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/main.html#L35

Currently untranslated page: https://gothic-modding-community.github.io/gmc/pl/zengin/worlds/

You could also place the call to action translation prompts in extra of mkdocs.yml and overwrite it for each language and refer to those in the Jinja2 syntax.

Andre601 commented 8 months ago

Okay, thanks for the info. Tho, I'm a bit confused on your last sentence... What do you mean exactly with overwriting it?

I would like to use that extra aproach, as it avoid translators having to edit template files, but I'm not sure how I would implement this within jinja templating...

I know I can use a {% set something = config.extra.path.to.something %}, but how could I alter it to use a language option or smth?

Andre601 commented 8 months ago

Also, another issue I face is the fact that some pages are not translatable, while others just aren't translated yet...

So I would need to find some way to display a different text based on if the page in question is not translated yet, or cannot be translated... But the only way I could think of is making a page with frontmatter to check, which would cause the file check thing to fail...

Andre601 commented 8 months ago

Also, as a final note am I facing an issue I had in the past with another site, which is that the announce block is always visible in my docks, even when they are not used (Don't have a content).

And since blocks are apparently handled before if checks can I not wrap it into an if to not include while the page is not the default and non-existant...

kamilkrzyskow commented 8 months ago

What do you mean exactly with overwriting it?

The overwrite method can be seen here: https://ultrabug.github.io/mkdocs-static-i18n/setup/setting-up-languages/#additional-per-language-overrides-options it was also bugged a while back with extra, but should be working now: https://github.com/ultrabug/mkdocs-static-i18n/issues/267

Basically a short example of mkdocs.yml similar to our current override:

extra:
  announcement: 'This page has not yet been translated into LANGUAGE, therefore it is displayed in English.'
  # Announcement for the default English language

plugins:
  - i18n:
    languages:
      - locale: en
        default: true
        name: English
        build: true
      - locale: pl
        name: Polish
        build: true
        extra:
           announcement: 'Ta strona nie została jeszcze przetłumaczona na język polski, dlatego wyświetla się po angielsku.'
           # Overwrite the value on language switch

and then you use {{ config.extra.announcement }} in the Jinja2 template to access the value.

another issue I face is the fact that some pages are not translatable,

Like you said, I agree you'd need to add a front-matter value for the pages that are not translatable. You can then combine the conditional, modifying the example of our overrides: if i18n_page_locale != "en" and i18n_file_locale != i18n_page_locale and not page.meta.not_translatable ~~There might be an issue with page.meta not being defined for the 404 template page, I'm not sure if that was fixed in MkDocs 1.5.0, if that happens you can add yet another condition: if page.meta and i18n_page_locale != "en" and i18n_file_locale != i18n_page_locale and not page.meta.not_translatable~~ Checking for page.meta is an incorrect approach in this context, as seen in a further comment.

Also, as a final note am I facing an issue I had in the past with another site, which is that the announce block is always visible in my docks, even when they are not used (Don't have a content).

Yes, and it was me that argued at some point that you did something incorrectly, but the time has come for me to apologize for that time.

Material for MkDocs has a somewhat nasty condition in the base.html https://github.com/squidfunk/mkdocs-material/blob/dfa5f0313893ff7fc254a8d74421735d5f1d3eb1/material/templates/base.html#L114 if self.announce()

In other words, if your main.html contains a block announce override it triggers that conditional and it adds the announcement bar wrapper <aside class="md-banner">, no matter if there is any content in your announce override.

It turned out I had the same issue, but I simply didn't want to fight for a nice, perhaps best solution, and I just added extra CSS to remove additional margin and keep the announce bar "hidden". https://github.com/Gothic-Modding-Community/gmc/blob/287e4bfe2daec82b237983252903a2d020bbf620/overrides/assets/stylesheets/extra.css#L205

In the override you can also notice that we have our own <div class="gmc-announce"> to style it however we see fit.

Andre601 commented 8 months ago

The overwrite method can be seen here: https://ultrabug.github.io/mkdocs-static-i18n/setup/setting-up-languages/#additional-per-language-overrides-options it was also bugged a while back with extra, but should be working now:

267

From my testing it doesn't.

The announce block:

{% block announce %}
  {% if page.meta and i18n_page_locale != "en" and i18n_file_locale != i18n_page_locale %}
    <div class="announcement__translation">
      {% if page.meta.not_translatable %}
        {{ config.extra.not_translatable | d('This page cannot be translated and is therefore only available in English.') }}
      {% else %}
        {{ config.extra.missing_translation | d('This page has not yet been translated.') }}
      {% endif%}
    </div>
  {% endif %}
{% endblock %}

The mkdocs.yml content:

extra:
  social:
    - icon: 'simple/patreon'
      link: 'https://patreon.com/andre_601'
    - icon: 'simple/github'
      link: 'https://github.com/purrbot-site'
    - icon: 'simple/twitter'
      link: 'https://twitter.com/TruePurrBot'
    - icon: 'simple/mastodon'
      link: 'https://botsin.space/@purrbot'
  missing_translation: 'This page has not yet been translated.'
  not_translatable: 'This page cannot be translated and is therefore only available in English.'

plugins:
  - search
  - neoteroi.mkdocsoad:
      use_pymdownx: true
  - i18n:
      docs_structure: folder
      languages:
        - locale: en
          default: true
          name: English
          build: true
        - locale: de
          name: Deutsch
          build: true
          extra:
            missing_translation: 'Diese Seite wurde noch nicht übersetzt.'
            not_translatable: 'Diese Seite kann nicht übersetzt werden und ist darum nur auf Englisch verfügbar.'
          nav_translations:
            # Welcome system
            Welcome-System: Willkommenssystem
            # Contributing
            Contributing: Mitmachen
            Translations: Übersetzungen
            # Legal
            Legal: Rechtliches

kamilkrzyskow commented 8 months ago

Tested the code myself, and it doesn't work at all. So through trial and error I found that if page.meta does if fact break it 😓 I feel like this was a valid way to test for meta at some point, must have changed in MkDocs 1.5.0 I removed that part (together with some other stuff) and created this minimal reproduction: i18n-extra.zip I only verified that the German language displays the translation notice. Didn't check the rest.

Andre601 commented 8 months ago

Tested the code myself, and it doesn't work at all. So through trial and error I found that if page.meta does if fact break it 😓 I feel like this was a valid way to test for meta at some point, must have changed in MkDocs 1.5.0 I removed that part (together with some other stuff) and created this minimal reproduction: i18n-extra.zip I only verified that the German language displays the translation notice. Didn't check the rest.

It wasn't page.meta, but my own mistake. I used 1.1.0 of this plugin which probs didn't had these extra fixes in it... Updated now to 1.2.0 and it seems to work, even with the page.meta

Andre601 commented 8 months ago

Either way, this is what I was looking for so I'm closing this now. Thanks.

Andre601 commented 8 months ago

@kamilkrzyskow Unrelated to this issue, but I saw your docs using country flags as display in the language selector...

Was looking into your sources on GitHub, but cannot reproduce that stuff you made... From what I get are you using hooks to change and inject stuff? In my case do I get the error that a header.html is missing.

Maybe you have a simplified/dumbed down version and/or explanation for me? Because I feel like that would be quite a nice thing to add for my docs too...

(Maybe this could be a feature for this plugin too? I feel like it could be really neat to have... Tho it probs would require the same level of file altering as your solution seems to use.)

ultrabug commented 8 months ago

(I'm just passing by to say thank you for this great exchange. I'll reflect on this to create a proper documentation section in the plugin's doc as it seems a cool pattern to share to a wider audience)

kamilkrzyskow commented 8 months ago

@Andre601 At the moment both the main and dev branches are locked at MkDocs Material 9.1.21

I believe in 9.2 the file structure has changed so it stopped working.

I'm slowly working on the upgrade to 9.4 and did update the hooks in the process.

https://github.com/kamilkrzyskow/gmc/tree/upgrade-material-9.4/overrides/.hooks

Copy the theme overrides manager and language flags to your repo and you should be good to go, just remember to add both of them in the mkdocs.yml, edit: oh and add extra CSS, which can be found in the linked guide below

The hooks temporarily modify the template files and then restore them afterwards. I guess, this could be simplified by just permanently modifying the template until next Material reinstall/update.

I made a guide for the initial version, it's outdated like said above but the idea is mostly the same:

https://github.com/squidfunk/mkdocs-material/discussions/5060

If @ultrabug wants I could make a PR here with this functionality, but at the same time I think it's sort of out of scope.

When I made the switch from one to two hooks I sort of realised I should make a plugin out of it because hooks hooking into hooks is just weird 😅

So I will port it over into a plugin at some point

Andre601 commented 8 months ago

@Andre601 At the moment both the main and dev branches are locked at MkDocs Material 9.1.21

I believe in 9.2 the file structure has changed so it stopped working.

I'm slowly working on the upgrade to 9.4 and did update the hooks in the process.

https://github.com/kamilkrzyskow/gmc/tree/upgrade-material-9.4/overrides/.hooks

Copy the theme overrides manager and language flags to your repo and you should be good to go, just remember to add both of them in the mkdocs.yml, edit: oh and add extra CSS, which can be found in the linked guide below

The hooks temporarily modify the template files and then restore them afterwards. I guess, this could be simplified by just permanently modifying the template until next Material reinstall/update.

I made a guide for the initial version, it's outdated like said above but the idea is mostly the same:

squidfunk/mkdocs-material#5060

If @ultrabug wants I could make a PR here with this functionality, but at the same time I think it's sort of out of scope.

When I made the switch from one to two hooks I sort of realised I should make a plugin out of it because hooks hooking into hooks is just weird 😅

So I will port it over into a plugin at some point

Edit: Just now saw your edit about the CSS.

Well, it works... kinda 😅 grafik

Andre601 commented 8 months ago

Also, a plugin would indeed be cool to consider... Tho then you should be able to add/override the flags defined by default in the options, so that it can have its own lang_code -> flag mapping...

Andre601 commented 8 months ago

I just had a moment to think about it and I think I found a basic solution that only requires a small amount of effort by the user.

Basically, there would be a hook which does the following:

Check the plugins option for i18n and check the languages option for entries.
For each entry that is set to build, get the language code used.
Use the lang code with flag_ to pull from the Twemoji CDN.
Store the SVG in a specific directory (i.e. .icons/languages/{lang_code}.svg)

All that would be left to do by the user is to override the partial with the language selector to now include the SVG under that directory...

This would eliminate two things:

The need to dynamically alter the template file via hook
The reliance on the CDN since the icons would be included now in the docs themself...

Tho, that's just my thinking, using my old discussion about this with your system using the CDN to make a mix...

kamilkrzyskow commented 8 months ago

The whole point of dynamic overrides is so that people don't have to change the partials themselves.

Partial override is the last resort for me, because later you'd need to look out for any changes in future updates of the theme. And the hook will immediately report if there is something broken or incompatible.

Saving files and including them as rendered SVG instead of using the CDN might be a valid improvement, I will think about implementing it.

ultrabug / mkdocs-static-i18n

[Feature] Option to insert/inject content for fallback lang pages. #276

267