Hi there 👋

I've been looking at different translation methods where I can achieve:

• (i) navigation title translations
• (ii) custom ordering of pages in nav, and
• (iii) preserve URL schemes to match my file directory (i.e., ../folder-name/ and not ../Folder%20Name/ if configured otherwise).

As awesome-pages is non-compatible for nav_translations, here's an approach using the native nav configuration in mkdocs.yml that almost gets me to what I'm looking for, but I run into an issue.

I have the nav_translations for my folders within the i18n configuration in mkdocs.yml:

nav_translations:
    fr:
        Folder 1: "Dossier 1"
        Folder 2: "Dossier 2"

Note that I'm not concerned about translating page titles as these can be inherited from the markdown heading of the page.

Then I order the nav for my entire site, with my translated files:

nav:
- Folder 1:
  - folder1/page1.md
  - folder1/page1.fr.md
  - folder1/page2.md
  - folder1/page2.fr.md
- Folder 2:
  - folder2/page1.md
  - folder2/page1.fr.md
- page1.md
- page1.fr.md

The intended outcome is to have the following in my main nav for whatever language that is selected:

| Folder 1 | Folder 2 | Page 1 |

And in the nav for a given folder in a given language I want the following:

Folder 1

• page 1
• page 2

With the configuration above, (i) my titles get translated, (ii) my custom order defined in nav is preserved, and (iii) the URL scheme reflecting my file directory is preserved (with a nice /fr/ prefix when translated to my non-default language). And of course my content is correctly translated following the .fr.md scheme.

Here is the problem: when I'm in a given language, all non-translated files defined in my mkdocs.yml nav configuration are shown on screen, marked as "None", and lead to a 404.

The effect is the following:

Main nav in English
| Folder 1 | Folder 2 | Page 1, english | None |

Main nav in French
| Dossier 1 | Dossier 2 | None | page 1, français |

Similarly in my page nav:
Folder 1

• Page 1 in Folder 1, english
• None
• Page 2 in Folder 1, english
• None

And the inverse for French, where the page titles and "None" are flipped.

Here is an example I put together showing the problem: https://scmcca.github.io/nav-issues/

And the repo so you can see the files: https://github.com/scmcca/nav-issues/

Am I perhaps missing something basic here? Would love any help or alternatives to achieve what I outlined here.

Thanks!

Is there a way to translate the site_name parameter ?

A plugin parameter could be great :

site_name: Mon super site
plugins:
  - i18n:
      default_language: fr
      languages:
        fr: Français
        en: English
      site_name_translations:
        en: My awesome website

Hey there! Ever since I updated to the latest version (I might have skipped one), I've been getting a lot of relative path warnings again for a lot of files that are actually there.

I can repro this on two systems, mac and Linux, with this repo https://github.com/ManticoreGamesInc/platform-documentation

I don't know how much of this will be actionable, but I'm in the middle of converting a largish site over to mkdocs right now and trying to come up with a workable i18n/l10n story. I gave mkdocs-static-i18n a good try but in the end it's not a fit for us.

Background

I'm attempting to migrate https://docs.qmk.fm/ from docsify to a static site generator. The current docsify structure looks something like this:

• /docs/page.md - English
• /docs/fr-fr/page.md - French

To start working with mkdocs-static-i18n I put together a site structure that looks like this: https://github.com/qmk/qmk_mkdocs/tree/mkdocs-static-i18n

(Apologies for the rough repo, I accidentally deleted my branch that had all the tweaks and fixes to make that work well.)

That repo contains roughly 145 English markdown documents and nearly 350 documents across 8 languages overall.

Pain Points

Speed

The first pain point is speed- on my relatively beefy desktop with an NVME SSD it takes roughly 5 seconds to build the English language docs. It takes nearly 2 minutes to build every language. We can alleviate that pain for people working on English documentation, but anyone working on a translation is looking at 2+ minutes of waiting every time they press save.

Navigation Translation

Tying the navigation translation to the current English text means that changes to navigation titles have to be done in multiple places. That's one more thing we need to catch in PR reviews.

It also prevents changing the structure of the navigation in a way that makes sense for native speakers. For example, our French translation specifically calls out the pages that have and have not been translated.

Can't have pages that don't exist in the primary language

I spent a lot of time cleaning up errors like this:

Exception: mkdocs-static-i18n is expecting one of the following files: [PosixPath('getting_started_build_tools.md'), PosixPath('getting_started_build_tools.en.md')]

We have some files that are translation specific. Requiring a corresponding English language document is in some cases nonsensical and in other cases just redundant.

Everything is in one directory

With everything in one directory it's harder on everyone. People working on the English language site have to sort through all the non-English files. Since our translations are incomplete you can't be sure if the next English doc is 2 lines down or 5 lines down when you're scanning through the list.

If you want to see what has and hasn't been translated for your particular language you end up writing a bunch of shell to filter through the list of files.

What are we using instead?

I'm still in the experimental phase of this project, but right now the clear winner is what I have on the main branch here. This basically builds a structure where every language is a separate site, and I use some custom github actions to assemble them into a whole structure.

I don't have a good story for language or version switching yet, but I think I can solve those with some mkdocs-material theme customization work.

Language options do not render in the same order defined in configuration. The default language always appears first, followed by the rest of my languages unordered. For example, my configuration looks like this:

languages:
  en: ... 
  fr: ...
  da: ...
  es: ...
  pt: ...
  ja: ...

And the render is unordered on every serve (results of 2 different serves below):

I suspect this is because yaml does not consider order. Is there a fix that exists so that my languages appear in the same order I configure them? Thanks!

I have a problem to deploy site with this plugin into github pages.

You can find trace here: https://github.com/Kanaduchi/vwcoding/runs/3442091472?check_suite_focus=true

I use latest version of mkdocs-material and your plugin:

mkdocs-pdf-export-plugin==0.5.8
mkdocs-print-site-plugin==1.2.3
mkdocs-static-i18n==0.19```

Error:
```Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.6/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/click/core.py", line 1137, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/click/core.py", line 1062, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/click/core.py", line 1668, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/click/core.py", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/mkdocs/__main__.py", line 204, in gh_deploy_command
    build.build(cfg, dirty=not clean)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/mkdocs/commands/build.py", line 274, in build
    files = config['plugins'].run_event('files', files, config=config)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/site-packages/mkdocs_static_i18n/plugin.py", line 388, in on_files
    self.i18n_configs[language] = deepcopy(config)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 172, in deepcopy
    y = _reconstruct(x, memo, *rv)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 270, in _reconstruct
    state = deepcopy(state, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 230, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 230, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 172, in deepcopy
    y = _reconstruct(x, memo, *rv)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 270, in _reconstruct
    state = deepcopy(state, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 230, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 230, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 205, in _deepcopy_list
    append(deepcopy(a, memo))
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 237, in _deepcopy_method
    return type(x)(x.__func__, deepcopy(x.__self__, memo))
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 172, in deepcopy
    y = _reconstruct(x, memo, *rv)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 270, in _reconstruct
    state = deepcopy(state, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 230, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 172, in deepcopy
    y = _reconstruct(x, memo, *rv)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 270, in _reconstruct
    state = deepcopy(state, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 146, in deepcopy
    y = copier(x, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 230, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "/opt/hostedtoolcache/Python/3.9.6/x64/lib/python3.9/copy.py", line 161, in deepcopy
    rv = reductor(4)
TypeError: cannot pickle 'module' object```

Hi,

I am writing a macro using mkdocs-macros-plugin that is to include content depending on the language chosen but I could not find a way to identify the language outside your plugin. Is there a chance you could export it? Would be a two-liner to add an instance variable or just a couple more to add a getter.

Thanks for a all the great work on the plugin, it works a treat!

Cheers,

Alex

Sorry If I fail explaining this.

I'm working whith the last version of mkdocs material and also mkdocs static i18n. They work like a charm.

However, with the following configuration:

plugins:
  - i18n: # https://github.com/ultrabug/mkdocs-static-i18n
      default_language: es
      languages:
        en: English
        es: Español
      nav_translations:
        en:
          Hola: Hi
          Docencia: Teaching
          Cosas: Stuff

I've found that the bottom links are not translated:

While the navbar is:

Thanks a lot ❤️

Hello, it's me again! 👋

So on this example page: https://docs.coregames.com/fr/api/key_bindings/

If you look at the link "Core Academy" you can see that is missing a slash after the https

<a href="https:/learn.coregames.com" class="md-tabs__link"> Core Academy </a> same with other external links.

They are specified in the yaml as follows:

  - Core Academy:
      - Academy: https://learn.coregames.com
  - Forums:
      - Forums: https://forums.coregames.com
  - News:
      - News: https://forums.coregames.com/c/community/5

The links are fine on the non-/fr/ version

Hello.
This applies to MkDocs-material.
I don't really know if it's a bug or a plugin use that is out of specs.
Commit: 9694c6a
Release 0.20 introduced a much anticipated feature: page context locale switching without going back to the home.
However, if MkDocs is hosted inside a subfolder AND your default locale point to the root of that folder, if you omit the "extra.alternate.url" parameter for the default language (en ) as documented in the mkdocs-material documentation (although it is marked as 'required' it is optional and defaults to ./), mkdocs build will fail.

Consider the following config:

• The base folder has a variable name depending on deployment, it is set once with the "site_url" parameter.
• the default language folder is the root of mkdocs folder.
• We can't set an extra.alternate.link because we don't know yet the deployment folder url.
• The default lang url isn't set, and gracefully defaults to site_url ... which is handy for this (particular) case

extra:
  alternate:
    - name: English
      lang: en
      title: English version
      default: true
    - name: Français
      link: fr
      lang: fr
      title: Version française

Building mkdocs with mkdocs-static-i18n 0.20 generates an error because alternate["link"] is undefined.

Error:

INFO     -  Building documentation...
INFO     -  Adding 'fr' to the 'plugins.search.lang' option
INFO     -  Cleaning site directory
ERROR    -  Error building page 'index.md': 'link'
Traceback (most recent call last):
  File "/home/XXX/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/home/XXX/lib/python3.8/site-packages/click/core.py", line 1137, in __call__
    return self.main(*args, **kwargs)
  File "/home/XXX/lib/python3.8/site-packages/click/core.py", line 1062, in main
    rv = self.invoke(ctx)
  File "/home/XXX/lib/python3.8/site-packages/click/core.py", line 1668, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/XXX/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/XXX/lib/python3.8/site-packages/click/core.py", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/home/XXX/lib/python3.8/site-packages/mkdocs/__main__.py", line 173, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, **kwargs)
  File "/home/XXX/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 54, in serve
    config = builder()
  File "/home/XXX/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 49, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/XXX/lib/python3.8/site-packages/mkdocs/commands/build.py", line 306, in build
    _build_page(file.page, config, doc_files, nav, env, dirty)
  File "/home/XXX/lib/python3.8/site-packages/mkdocs/commands/build.py", line 212, in _build_page
    context = config['plugins'].run_event(
  File "/home/XXX/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/home/XXX/lib/python3.8/site-packages/mkdocs_static_i18n/plugin.py", line 560, in on_page_context
    if alternate["link"].endswith("/"):
KeyError: 'link'

A quick workaround is to add a single dot (.) to the default locale link parameter.

extra:
  alternate:
    - name: English
      link: .
      lang: en
      title: English version
      default: true
    - name: Français
      link: fr
      lang: fr
      title: Version française

Maybe a conditional should be added in case no value is given?

Thanks for your attention.

Spanish version has index.html inside README/ but english version doesn't (english version works and spanish version doesn't). Rendered doc shows a 404 error when changing to spanish.

nav:
  - Home: README.md

This is the docs folder, README.md and README.es.md at the same level.

And this is the built docs, with differences between english and spanish versions. (spanish index.html is inside README/ when it shouldn't be).

Any ideas why? Thanks!

EDIT: It's a 404 error when changing to spanish so obviously adding a /README makes it work but this is a workaround that i want to avoid (or changing spanish README.md references to include /README).

EDIT 2: If i rename README.md and README.es.md to index.md and index.es.md it works. I'd rather not do this but maybe makes the bug/problem more discoverable.

Example page: https://docs.coregames.com/

Steps:

• Go to above website, inspect and check HTML's lang tag value. It should be en.
• Use the language switcher and switch to Francais (Beta). lang stays at en.

Config:

  - i18n:
      default_language: en
      languages:
        fr: Français (Beta)

It works on https://ultrabug.github.io/mkdocs-static-i18n/ so I'm suspecting some config.

Hello again. Sorry for the inconvenience, but we found another problem in the plugin, now is the integration with the search plugin. The thing is that the search function only works with the default language, so when we are in a different language it searches only in the default language, ignoring the other languages. I think the problem is with the plugin itself, which is maybe disabling something that the search plugin needs, as long as for example this other one works.

Do you know what the problem could be and if it is easy to solve?

Thank you very much.

index.md file is the first file that is served from any website (as index.html) and usually references multiple media files (images etc).

<html>
<body>
<img src=img/visual.png>
<p>content</p>
<img src=img/chart.png>
</body>
</html>

in the example above, when using mkdocs-static-i18n module, is one expected to make copy of visual.png and chart.png on a per locale basis so that the 'index.html' page is rendered correctly ?

While I do like the <filename>.<language>.md syntax is it rather annoying if you want to keep the different translations separated from each other.
Because of this would I like to ask, if there is a way to actually define a folder to utilize for the language, instead of relying on the file name pattern.

As an example, I want this docs/ structure:

docs/
├── image.en.png
├── image.fr.png
├── index.fr.md
├── index.md
├── topic1/
│   ├── index.en.md
│   └── index.fr.md
└── topic2/
    ├── index.en.md
    └── index.md

to be like this instead:

docs
├── en/
│   ├── image.png
│   ├── index.md
│   ├── topic1/
│   │   └── index.md
│   └── topic1/
│       └── index.md
└── fr/
    ├── image.png
    ├── index.md
    ├── topic1/
    │   └── index.md
    └── topic1/
        └── index.md

While this would double the folders used would it also improve readability and searchability and keep a consistent structure across the page...

I hope this can be considered.

is mkdocs-static-i18n compatible with mkdocs-theme-bootsrap4 ?

i'm trying to adapt the custom language switcher example that you describe and i can't get it to work. Any pointers ?

Hi! I copied all of files and then executed mkdocs build && mkdocs serve... everything OK. (I did it on Windows)
Then when I go to some pages the browser can't find them. There are some screenshots.

How can I help to fix the issue?
Thanks!

How would I style or relocate where the translation link is rendered?

Currently, languages like traditional Chinese (zh) are working fine.
But other languages, like simplified Chinese (zh_CN) and simplified Chinese for Taiwan (zh_TW), etc. just break the system.

➜  rldocs git:(main) ✗ python3 -m mkdocs serve
INFO     -  Building documentation...
ERROR    -  Config value: 'plugins'. Error: Plugin 'i18n' value: 'languages'. Error: Language values must respect the ISO-639-1 (2-letter)
            format, received 'zh-cn' of length '5'.
Aborted with 1 Configuration Errors!

Hello. @mic4ael and I found a problem using nginx for serving the static files. The navigation items are created without the leading slash, which creates a redirect that in some cases might be problematic. For example, we end up on http://localhost/topic1/ instead of http://localhost:8080/topic1/.

We think that a / is missing, so nginx redirects to /topic1 instead of /topic1/ and it breaks.

As you can see, for these sections that have an index.md they have the / and there is no problem with the redirections.

To sum up, the thing is that we think that it's necessary to have /site/ instead of /site for all the files, so we can expect the same behavior both for default and non-default languages and also for those files which are not index.md.

Thank you in advance :)

Given the config:

# ...

site_url: https://user.github.io/repo
repo_url: https://github.com/user/repo

# ...

nav:
  - Section:
      - index.en.md
      - other-page.en.md

# ...


extra:
  alternate:
    - name: English
      link: ./en/
      lang: en
    - name: Deutsch
      link: ./de/
      lang: de

# ...

plugins:
  # ...
  - i18n:
      default_language: en
      default_language_only: false
      languages:
        en: English
        de: Deutsch
      nav_translations:
        Section: Abschnitt
  # ...

and the structure:

docs
├── index.de.md
├── index.en.md
├── other-page.de.md
└── other-page.en.md

when switching from English (en) to German (de) while on other-page, this plugin messes up the target destination.

Most of the time it correctly takes me to the target destionation: https://user.github.io/repo/de/other-page/, but quite regularly it takes me to:

• either https://user.github.io/repo/other-page/de/
• or https://user.github.io/de/other-page/.

For this given docs structure and this config

docs
├── index.en.md
├── index.md
├── topic1
│   ├── 1.1.exemple.en.md
│   ├── 1.1.exemple.fr.md
│   ├── index.en.md
│   └── index.fr.md

plugins:
  - i18n:
      default_language: fr
      languages:
        fr: Français
        en: English

I always get the english version :

http://127.0.0.1:8000/Topic1/1.1.exemple.html => english (not ok)
http://127.0.0.1:8000/fr/Topic1/1.1.exemple.html => english (not ok)
http://127.0.0.1:8000/en/Topic1/1.1.exemple.html => english (ok)

Currently when you configure the language switcher it always takes you back to the root of the site. It would be a lot nicer if it took you to the same page in that language.

For a concrete example, say you are on this page:

https://ultrabug.github.io/mkdocs-static-i18n/topic1/named_file/

When you change the language to French you are taken to this page:

https://ultrabug.github.io/mkdocs-static-i18n/fr/

I would like the user to instead be taken to this page:

https://ultrabug.github.io/mkdocs-static-i18n/fr/topic1/named_file/

mkdocs 1.2 is out now and has support for ENV checks in configs, this would allow me to get rid of having to use two different mkdocs.yml but mkdocs-static-i18n does not have an easy way to disable it.

Would be nice if there was an enabled: true|false key I could set.

On https://ultrabug.github.io/mkdocs-static-i18n/ the language switching links at the bottom of the start page are broken.

"Get to the FR version" points to https://ultrabug.github.io/fr when it should point to https://ultrabug.github.io/mkdocs-static-i18n/fr/ instead. Same issue for EN and DEFAULT.

The mkdocs.yml

site_name: Test
nav:
  - Home: index.md
theme:
  name: material
plugins:
  - awesome-pages
  - i18n:
      default_language: en
      languages:
        en: English
        de: Deutsch        
      nav_translations:
        de:
          'Home': Startseite

with index.md

# Welcome!

and index.de.md

# Herzlich Willkommen!

gives the German website

When I remove awesome-pages I get the expected website

Is this an issue of awesome-pages or of i18n?

With upgrade to version 0.20 my "Select Language" switcher is broken: it links to "index.html/index.html" or "de/index.html/index.html". Works fine with version 0.19.

<div class="md-header__option">
    <div class="md-select">
        <button aria-label="Select language" class="md-header__button md-icon">
            <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
                <path d="m12.87 15.07-2.54-2.51.03-.03A17.52 17.52 0 0 0 14.07 6H17V4h-7V2H8v2H1v2h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04M18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12m-2.62 7 1.62-4.33L19.12 17h-3.24z"/>
            </svg>
        </button>
        <div class="md-select__inner">
            <ul class="md-select__list">
                <li class="md-select__item">
                    <a class="md-select__link" href="index.html/index.html" hreflang="en">EN
          </a>
                </li>
                <li class="md-select__item">
                    <a class="md-select__link" href="de/index.html/index.html" hreflang="de">DE
          </a>
                </li>
            </ul>
        </div>
    </div>
</div>

My mkdocs module versions:

Name: mkdocs
Version: 1.2.2
Name: mkdocs-static-i18n
Version: 0.20
Name: mkdocs-material
Version: 7.3.1
Name: mkdocs-localsearch
Version: 0.9.1

Thanks for your work!

So I used the following conf:

  - i18n:
      default_language: en
      languages:
        fr: français

and as expected my EN/default site works the same way as before but switching to French via the language picker dropdown switches the content to the french page.

Now here's the problem, as soon as I'm on the french version of my index, the menu no longer shows.

I'm assuming it is because of the autolinks plugin because I also get a lot of these:

WARNING -  A relative path to 'getting_started/installing_core.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/editor_intro.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/my_first_multiplayer_game.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/publishing.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/core_help.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/community_content.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/performance_panel.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/profiler.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  A relative path to 'getting_started/publishing_checklist.md' is included in the 'nav' configuration, which is not found in the documentation files 

When trying to access any other page, it also fails to load them, example:

On getting_started/installing_core/ manually changing the path in the address bar to fr/getting_started/installing_core/ should show a page, yet does not?

Here's my branch where I am testing this: https://github.com/ManticoreGamesInc/platform-documentation/tree/localization

set use_directory_urls: false in mkdocs.yml

use_directory_urls: false

create test.en.md, test.fr.md:

docs
├── test.fr.md
├── test.en.md

then

mkdocs serve

just test these urls:

So mkdocs does generate a sitemap.xml for all pages but currently the extra language pages generated by this plugin do not get added to it, it seems.

<url>
    <loc>http://www.example.com/docs/</loc>
    <xhtml:link rel="alternate" hreflang="de" href="http://www.example.com/de/"/>
  </url>

This example Is probably what it should do, not sure if plugins can even change the sitemap generation though.

Currently when using the mode to not build a dedicated version for the default language, the default language does not show up in the language switcher dropdown which makes it hard to return to it. So I'd suggest adding something to get the default language and then updating the example for it.

Material also now has a native language selector (https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) so my current code looks like this:

<!-- Site language selector -->
    {% if config.extra.alternate %}
      <div class="md-header__option"></form>
        <div class="md-select">
          {% set icon = config.theme.icon.alternate or "material/translate" %}
          <span class="md-header__button md-icon">
            {% include ".icons/" ~ icon ~ ".svg" %}
          </span>
          <div class="md-select__inner">
            <ul class="md-select__list">
              <li class="md-select__item">
                <a href="/" class="md-select__link">
                  English
                </a>
              </li>
              {% for lang, display in config.plugins.i18n.config.languages.items() -%}
                <li class="md-select__item">
                  <a href="/{{ lang }}/" class="md-select__link">
                    {{ display }}
                  </a>
                </li>
              {% endfor %}
            </ul>
          </div>
        </div>
      </div>
    {% endif %}

We use use_directory_urls true on our build, because our webserver doesn't use index files, so we need the full file path.

I think the links generated for the language selector should acknowledge that option to generate the links like this when use_directory_urls is set to true: /fr/index.html, /de/index.html etc.

Currently if we specify config like

  - i18n:
      default_language: fr
      languages:
        en: English

then nf the language selector we will see two items: fr and English

My suggestion is to add new variable default_language_label: Français for displayable label in the selector for default language

As I got it right the fix is quite simple:

1. Introduce new variable in the config scheme

("default_language_name", Locale(str, required=False)),

2. Read it in the creation of language list

"name": self.config["languages"].get(
self.config["default_language_name"],
self.config["default_language"]

I tried to use nginx to serve the static files, the parent index.html displayed correctly. However, when I navigated to sub-directory, the browser get the wrong assets path, and I got this error in console Uncaught SyntaxError: Unexpected token '<'.

For example: The site displayed correctly when I navigated to http://localhost:8081/guides/zh/, but not http://localhost:8081/guides/zh/sub/; I have to add index.html(http://localhost:8081/guides/zh/sub/index.html) at the end of path manually then it will display correctly.

nginx configuration:

`server {
gzip on;
gzip_min_length 1k;
gzip_comp_level 9;
gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/x-
httpd-php image/jpeg image/gif image/png;
gzip_vary on;
gzip_disable "MSIE [1-6].";

listen 80;
server_name localhost;
root /usr/share/nginx/my-site;
autoindex on;

#Another project
location /en-US/ {
    try_files $uri$args $uri$args/ /en-US/index.html;
}

location /zh/ {
    try_files $uri$args $uri$args/ /zh/index.html;
}

location / {
    add_header Cache-Control "no-store";
	try_files $uri$args /zh/index.html;
}
#mkdocs
location /guides/ {
    autoindex off;
	try_files $uri /guides/index.html;
    
    location /guides/zh/ {
        autoindex off;
        try_files $uri /guides/zh/index.html;
    }
}


error_page   500 502 503 504  /50x.html;
location = /50x.html {
    root   /usr/share/nginx/my-site/zh;
}

}
`
Is there any documentations that can help? Thanks.

for now, it switch to http://127.0.0.1:8000

in my opinion, it should switch to http://127.0.0.1:8000/en/ or http://127.0.0.1:8000/fr/

I have a case when in custom_dir of mkdocs theme I have some overrides of template html files (main.html, home.html):

theme:
  name: material
  custom_dir: overrides
  favicon: assets/icon.png
...

Is it possible to add possibility of switching between template files inside this dir for different languages?

Content of custom_dir folder:

• overrides/
  |_ main.html
  |_ main.fr.html

When creating the following structure:

├─ api
│  ├─ index.de.md
│  └─ index.en.md
├─ index.de.md
└─ index.en.md

and I want to link from index.<lang>.md to api/index.<lang>.md could I just do [link](/api/index.md) and the plugin would adjust the link to point to the right file of the same language, or would I need to directly reference the file (api/index.en.md)?

Plugin: https://github.com/midnightprioriem/mkdocs-autolinks-plugin

I'm testing with version 0.3.0 because the latest release is buggy for me.

So during build it will throw a duplicate file warning for every file that contains a link to a file that now has a multi language version. In my repo for example

WARNING -  Documentation file 'getting_started/community_content.fr.md' contains a link to 'getting_started/publishing.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/editor_intro.fr.md' contains a link to 'getting_started/my_first_multiplayer_game.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/my_first_multiplayer_game.fr.md' contains a link to 'getting_started/installing_core.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/my_first_multiplayer_game.fr.md' contains a link to 'getting_started/publishing.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/my_first_multiplayer_game.fr.md' contains a link to 'getting_started/publishing.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/publishing.fr.md' contains a link to 'getting_started/publishing_checklist.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/publishing.fr.md' contains a link to 'getting_started/publishing_checklist.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/publishing_checklist.fr.md' contains a link to 'getting_started/publishing.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/publishing_checklist.fr.md' contains a link to 'getting_started/publishing.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/publishing_checklist.fr.md' contains a link to 'getting_started/publishing.md' which is not found in the documentation files. 
WARNING -  Documentation file 'getting_started/publishing_checklist.fr.md' contains a link to 'getting_started/community_content.md' which is not found in the documentation files. 

It would be interesting within the context of your plugin to process not only file.<language>.md files, but also others whose suffix would be identical in term of naming.

Example:
versions.fr.json => fr/versions.json

To authorize this functionality and therefore limit the choice of files according to their extension, a setting could be added:

alternate_files_extension: json, txt, jpeg

If empty, then no file other than file.<language>.md is processed.

pip install mkdocs-static-i18n
in Windows10，output follow errors:

Traceback (most recent call last):
  File "setup.py", line 20, in <module>
    long_description=read("README.md"),
  File "setup.py", line 11, in read
    return (Path(__file__).resolve().parent / fname).read_text()
  File "C:\Program Files\Python38\lib\pathlib.py", line 1233, in read_text
    return f.read()
UnicodeDecodeError: 'gbk' codec can't decode byte 0x80 in position 2335: illegal multibyte sequence

Just add encoding to read_text(), like this:

return (Path(__file__).resolve().parent / fname).read_text(encoding='utf-8')

It would be helpfully if a log (INFO) could be written for each time a link/image reference fallback to the default language version of the image/page.

Example:

• default language: en
• current language: fr
• page contain link to: page1.md
• page1.fr.md doesn't exists -> INFO log is written
• same for images which not exists in the current language

Why would this be helpfully? See the progress of translation and the next steps to do.

Hey there! I ran into a weird bug (again) and I think I got it pinned down to me using the same filename but different extension in the same folder. Without the plugin, the images and videos load fine, with the plugin, the images do not load and are actually 404.

Example code:

| View Alignment      | Ground Alignment | Up Alignment|
|:-------------------:|:----------------:|:-------------:|
|![View Alignment](../img/TerrainReference/ViewMode.png){: style="width:15em" }|![Ground Alignment](../img/TerrainReference/GroundMode.png){: style="width:15em" }|![Up Alignment](../img/TerrainReference/UpMode.png){: style="width:15em" }
|The drawing plane is aligned with the camera|The drawing plane is parallel to the ground|The drawing plane always points towards the camera and is upright|
|<div class="mt-video"><video autoplay loop muted playsinline poster="/img/EditorManual/Abilities/Gem.png" class = "center" style="width:15em"><source src="../img/TerrainReference/ViewMode.mp4" type="video/mp4" /></video></div>|<div class="mt-video"><video autoplay loop muted playsinline poster="/img/EditorManual/Abilities/Gem.png" class = "center" style="width:15em"><source src="../img/TerrainReference/GroundMode.mp4" type="video/mp4" /></video></div>|<div class="mt-video"><video autoplay loop muted playsinline poster="/img/EditorManual/Abilities/Gem.png" class = "center" style="width:15em"><source src="../img/TerrainReference/UpMode.mp4" type="video/mp4" /></video></div>|

Log:

WARNING  -  Documentation file 'references/terrain.md' contains a link to 'img/TerrainReference/ViewMode.png' which is not found in the documentation files.
WARNING  -  Documentation file 'references/terrain.md' contains a link to 'img/TerrainReference/GroundMode.png' which is not found in the documentation files.
WARNING  -  Documentation file 'references/terrain.md' contains a link to 'img/TerrainReference/UpMode.png' which is not found in the documentation files.

Maybe it's also the inline HTML at fault, as in #45 but then I'd expect it to work in the default language though.

Hello @ultrabug ! First of all, thanks for putting effort here :)

Is there a way to support multi-lang and still keep pages/folders at custom order? I cannot find a combination where this works. Note that i cannot list .md files directly as now i have multiple lang suffixed files (.en.md , .es.md), so standard nav: tag ordering wont work as it breaks the non default lang page access.

mkdocs: 1.1.2
mkdocs-material: 7.0.7
mkdocs-static-i18n: 0.5
OS: Windows

I just try to build a i18n site with your plugin and the result of the build from docs is quiet strange:

docs:

├─ index.fr.md
└─ index.md
mkdocs.yml

And the command 'mkdocs build' produces:

site:

├─fr
     ├─index.fr
          ├─index.html
└─ index.html

The index.html file for french language is not directly under fr folder, but inside a index.fr folder!?!

mkdocs.yml:

site_name: Test
plugins:
  - search
  - i18n:
      default_language: en
      languages:
        fr: français
theme:
  name: material
  features:
    - navigation.expand
extra:
  alternate:
    - name: English
      link: /
      lang: en
    - name: Français
      link: /fr/
      lang: fr
nav:
  - index.md

Thanks for the plugin, great job! I was wondering if it's possible to have somehow a translation of the section titles on the nav (your Topic 1, Topic 2) depending on the language, as you can see below:

English version

French version

Hello

How can I hide/remove the link to the other language on the page?

Also, despite the language selection, the folder with the "German-language" content is displayed. Although there is no file for French.

Thanks

Building mkdocs fails after adding Lithuanian files and I don't know why.

For debugging I copied the working English file docs/index.md to docs/index.lt.md to rule out formatting errors, but I still get the same error, so I assume its a bug specifically with lt files.

Error message:

INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/runner/work/skynet-guide.github.io/skynet-guide.github.io/site 
INFO    -  Building en documentation 
INFO    -  Building fr documentation 
INFO    -  Building de documentation 
INFO    -  Building ru documentation 
INFO    -  Building es documentation 
INFO    -  Building lt documentation 
ERROR   -  Error building page 'index.lt.md': partials/languages/lt.html 
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.7.10/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/click/core.py", line 1134, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/click/core.py", line 1059, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/click/core.py", line 1665, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/click/core.py", line 1401, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/click/core.py", line 767, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/mkdocs/__main__.py", line 152, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/mkdocs/commands/build.py", line 295, in build
    config['plugins'].run_event('post_build', config=config)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/mkdocs/plugins.py", line 96, in run_event
    result = method(**kwargs)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/mkdocs_static_i18n/plugin.py", line 349, in on_post_build
    _build_page(file.page, config, files, nav, env, dirty)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/mkdocs/commands/build.py", line 210, in _build_page
    output = template.render(context)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/jinja2/environment.py", line 1289, in render
    self.environment.handle_exception()
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/jinja2/environment.py", line 924, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/material/main.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/material/base.html", line 4, in top-level template code
    {% import "partials/language.html" as lang with context %}
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/jinja2/environment.py", line 1394, in make_module
    return TemplateModule(self, ctx)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/jinja2/environment.py", line 1524, in __init__
    body_stream = list(template.root_render_func(context))  # type: ignore
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/material/partials/language.html", line 4, in top-level template code
    {% import "partials/languages/" ~ config.theme.language ~ ".html" as lang %}
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/site-packages/jinja2/loaders.py", line 214, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/languages/lt.html
Error: Process completed with exit code 1.

After adding this plugin all requests to the fonts/ folder result in a 404.

I am using the readthedocs theme and mkdocs 1.2.1

After inspecting the generated style.css, I noticed that all font paths are relative and of the form: .../fonts/<fontfile>, maybe resolving this is a problem?

Given the config:

# unrelevant code ommited

theme:
  name: material
  features:
    - navigation.tabs

nav:
  - Section:
      - index.en.md
      - other-page.en.md

plugins:
  - i18n:
      nav_translations:
        Section: 'Whatever "section" is when translated to the other language'

labels in the navigation (bar) tabs at the top are not being translated.