<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 auto-translated using po files or the like. and #774 proposes a system in which pages are manually translated.

It is likely that any native solution would come from a third party plugin or wrapper 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) any such third-party solutions.

</edit>

There was a long conversation today on IRC about this, so I thought I'd raise an issue to document some thoughts - and, hopefully, collect better ones :)

Problem Statement

• How to support more than one language within mkdocs without over-complicating things
• How to make these user-selectable
• How to co-exist with multiple document versions (is it actually the same thing?)

Considerations

• Default language/landing page

• Language selector (vs version selector?)

• Whether translations are stored alongside the default docs or pulled in from somewhere else, e.g.

  Site
  Language (default)
  Content
  Language (alt)
  Content

vs

Site (default)
    Language (default)
       Content
Site (alt)
    Language (alt)
       Content

• How much of this is a mkdocs issue versus a publishing/hosting issue?
• Ease of use - it can't get in the way of single-language simplicity
• Theme support vs content

Constraints

• mkdocs renders a single, static site
• We don't necessarily want tags in the markdown, translation/.po files, or similar
• We want to keep the source .md files clean

Initial Ramblings

From what I can see on a quick quint around, most multi-lingual sites are using dynamic content, or have multiple sites under different CNAMEs (even if they then link to a central host). So they're no use as inspiration...

The issue is thus one of jumping from one hierarchy of docs to another. Given how mkdocs renders (e.g. how ToCs are handled), you'd probably want to build each language site independently and then glue them together - otherwise, your ToC would have all language headings, and you coudl prev/next between languages.

So, does this actually turn into a debate about 'wrapping' independent sites in some way?

• You could do it with a language selection page (pretty ugly, but useful if you think your users couldn't find the language selector otherwise), and then shift to the relevant mkdocs sub-site as necessary; each sub-site would need a path back up to the top if you wanted to change.
• Or you could simply have a selection mechanism on your default page that allows you to switch into a different documentation path on the hosted site.
• Cookies to store language preference? Direct URLs to each language?
• Interplay with version? (my.project.docs/vv/en or my.project.docs/en/vv - probably the latter - which makes sense in building, as /en is a standalone mkdocs output with multiple versions and its own default).
• You could do a lot with relative paths. Indeed, if each sub-site is standalone, they don't even have to have the same theme or content. Inefficient use of storage, though, because of repetition.
• If mkdocs handled the ability to switch 'branches' cleanly, then it becomes a hosting issue: different language maintainers pushing different sub-sites in line with their design guidelines/headings/policies (is that in line with @d0ugal's initial approach to versions?).
• You could stick to replaceable strings in the main themes, as these would need to be localised as well (home/prev/next et al). That suggests theme-sharing, which would cut down on the duplication of storage; alternatively, each sub-site keeps its own theme and there's just some way to force the used theme into language XYZ.