ultrabug / mkdocs-static-i18n Goto Github PK
View Code? Open in Web Editor NEWMkDocs i18n plugin using static translation markdown files
Home Page: https://ultrabug.github.io/mkdocs-static-i18n/
License: MIT License
MkDocs i18n plugin using static translation markdown files
Home Page: https://ultrabug.github.io/mkdocs-static-i18n/
License: MIT License
Example page: https://docs.coregames.com/
Steps:
lang
tag value. It should be en
.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.
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.
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/
How would I style or relocate where the translation link is rendered?
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.
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.
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.
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
- FrenchTo 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.
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.
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.
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.
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.
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.
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:
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.
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.
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:
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.
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.
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
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
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:
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!
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?
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
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.
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 ❤️
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:
Why would this be helpfully? See the progress of translation and the next steps to do.
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:
https://user.github.io/repo/other-page/de/
https://user.github.io/de/other-page/
.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 :)
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)
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.
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/
Hi there 👋
I've been looking at different translation methods where I can achieve:
../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
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
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!
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.
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
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')
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
)?
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!
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.
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 ?
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!
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
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
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.
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.
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?
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:
("default_language_name", Locale(str, required=False)),
"name": self.config["languages"].get(
self.config["default_language_name"],
self.config["default_language"]
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 %}
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 ?
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.
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```
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.