Creating multi-language HTML builds

[shimizukawa]

With the translation machinery released in version 1.1 it is a natural idea to generate multiple builds using different languages and create a HTML tree including different languages with the outer pages allowing to switch between them.

It would also be interesting to investigate if this makes any sense with output formats other than HTML.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/788
• Originally reported by: Dinu Gherman
• Originally created at: 2011-10-11T18:57:14.846

[aruhier]

Hello, It would be a great idea to generate builds by language !

[SamB]

I ran into some documentatin that does this - it's not great that they've hardcoded the language list into layout.html, but this does demonstrate that people want to do this, and shows a UI they think works well.

Anyway, the relevant bits of doc source can be found from:

• https://github.com/search?q=repo%3Acryptpad%2Fdocumentation+language-selector-container+AND+NOT+path%3Awww%2F&type=code

The language switcher itself starts at:

• https://github.com/cryptpad/documentation/blob/d478435047a6402113568bdde043303e0ae1709e/_themes/theme/layout.html#L105

and the rendered docs are at: https://docs.cryptpad.org

[jayaddison]

From experience contributing one or two small fixes to Debian's documentation projects, I can share how they approach this problem:

1. By iterating over a set of supported languages (identified by language codes) and performing an HTML build for each language (and each into a separate output directory), a collection of internally-consistent standalone documentation results are produced.
2. The results of these individual per-language builds are combined into a single directory, after inserting a language code after the filename and before the file extension so that they do not clobber each other (for example, if we build using PT and EN language codes, then index.pt.html and index.en.html will co-exist in the combined output dir).
3. The hosting webserver is optionally configured to select a default index.{__}.html file based on the user's browser Accept-Language header; however a default index.html file (or symlink) is also included in the directory and may be navigated-to directly.
4. Some small adjustments are made to the default theme to provide a JavaScript-based language selection chooser that is aware of the available language codes, their corresponding language names, and can be used to adjust the current language manually.

There is two obstacles/limitations that I can think of initially:

• There is currently a static path to searchindex.js -- the search index file -- typically written into each per-language output in the search.html file from the basic theme base. Sphinx's search functionality does include localization support (it provides different stemming rules for various languages, for example) - so ideally in the example above we would also produce distinct searchindex.pt.js and searchindex.en.js files. This seems to overlap with feature request #11153 about specifying search index filename.
• Sphinx has support for both two-letter language codes and also four-letter locale codes (en-US for example). This would hopefully not be a significant problem to overcome in terms of deciding on filename suffixes, but it would be good to determine some preferred mechanisms (for example: is index.en_us.html the locale-specific filename output? and is index.en.html also produced, similar to the top-level default of index.html? I would probably argue that no, the project only has one default (determined by the authors) and that is the index.html version; the chooser menu and/or the Accept-Language heading (when a match is available) allow for a more-specific choice to be determined)

Edit: reword default-index selection sentence.

[jayaddison]

Note also: the use of Accept-Language header on the webserver in the approach above is entirely optional; a simple static webserver will still be able to host the combined multilingual HTML documentation absolutely fine, and users will be able to choose their preferred language. However, the initial/default language they see will be the project default instead of a dynamically-negotiated one determined from the browser settings.