<edit>

Note from project maintainers:

There are multiple aspects to supporting multiple languages in MkDocs, each of which is linked to from #211, which is the primary issue and ties all of the various aspects together. However, it is best to discuss each aspect in its related issue.

This issue is one (of two) proposals for adding support for pages in multiple languages. This issue proposes a system in which pages are manually translated, and #617 proposes a system in which pages are auto-translated using po files or the like.

Some third party plugins exist to address this issue (see comments below). It is likely that any native solution would come from a third party plugin if/when one establishes itself as well developed and is a clear favorite among users. Whether that means the plugin would be moved in-house or it would become the "recommended" solution and remain a third-party plugin will depend upon the circumstances at the time that such a decision is made. In any event, the best way to move this forward is to volunteer your time to develop and/or test (and provide feedback to) the plugins.

</edit>

This is related to #617 and, therefore, also to #211. However, I didn't want to add my comments to either of the two issues as to not hijack ideas discussed there. Feel free to close it if you disagree.

I'd like to share my requirements for multi-language support and ask for your input as to how to work around current limitations.

• All the docs (or doc content) must reside within the same repository/branch as the code itself. The rational is that we want to verify that each PR is complete and self-contained i.e. changes to code are properly reflected in the docs. That's the reason the Read the Docs localization support isn't really helpful, apart from the fact that it's currently only available for Sphinx-based projects.
• Derived from the above...the localized docs must be stored along side the default language docs.
• A solution that is based on externalized strings i.e. .pot/.po isn't desirable as each localization may slightly vary in how the content is represented. So, the localized version must depend on individually localized .md files.
• Ideally, localized versions of the docs should be free to define their own TOC. It's IMO not always useful to enforce that each localization has page X available because X might only make sense in certain languages.

So, for us a perfect solution would allow to define mkdocs.yml#pages for each language and to have a structure either like this

docs/
docs/ES
docs/FR

or this

docs/index.md
docs/index.ES.md
docs/index.FR.md

I'm thinking about going with the latter and writing some custom JavaScript that re-writes the links of the TOC to point to the files of the selected language. The default index page would offer a language selector and to store it in a cookie. How feasible do you think this is (still pretty new to MkDocs)?