Translated and Other Version Docs

[ChrisRackauckas]

While having two badges works, the ideal case would be to have the ability to switch between versions of documentation via a menu. By allowing a full menu, this would allow choices beyond Stable and Latest. This can be good for keeping older versions of docs for backwards compatibility, or having documentation translated in other languages. Since Julia is already very widely used in places where English is not the main language, it is and will continue to be very important that we support translated documentation.

Maybe @Ismael-VC might have some good ideas for how to implement this. My idea would just be to let the package developer use different Markdown files for the translated files, and have a way of specifying the different kinds of docs. One way to implement this would be to allow one higher level in "pages" where we can specify the Markdown files for building the different versions/translations.

Here are screenshots of examples from the Julia website (how they show translations) and the Julia documentation (how they show different versions). Something like this could be used for both translations and versions, and it would set Julia documentation apart from other languages.

[ChrisRackauckas]

I talked this over with @Ismael-VC. It seems it wouldn't be too difficult to integrate a translation site into Documenter.jl. You can see that this was done for the Julia site via placing the Javascript:

https://github.com/JuliaLang/julialang.github.com/pull/252/files

This can be implemented in Documenter by simply adding the API key to the makedocs function, and adding the Javascript to the page headers.

Another place to look would be integrating Crowdin instead of Transifex Live.

As for adding to the dropbox a button for other versions, that would take a Javascript expert. Look at the discussion here: julialang.github.com#428. Maybe a Juno dev could help out? @pfitzseb?

[MichaelHatherly]

Adding an optional API key sounds reasonable to me. Probably best to stick with Transifex Live so that translators don't need to learn a different system.

[mortenpi]

Having a widget to swap between versions is something we definitely need (also mentioned in #212).

It would be nice to integrate the language and version widgets into a single one I think -- could that be easily done with Transifex's widget?

[ChrisRackauckas]

Now that you have the widget for versions, could translations be put in there?

[MichaelHatherly]

Doesn't Transiflex provide it's own widgets though, or can it be customised? Not sure whether combining version and language selection in a single dropdown might get a bit confusing/busy for users to handle.

Just out of interest though: has there been much in the way of requests for translation of technical docs, rather than just tutorials/community pages? Not that I'm against getting more thorough translations, just curious whether anyone's already started translating anything like that. Note that we also need a solution for swapping out docstrings for a different set of translations at runtime, I've got some ideas in mind, but since I don't personally have any need of it it's been at the back of the queue.

[Ismael-VC]

I've got some ideas in mind, but since I don't personally have any need of it it's been at the back of the queue.

@MichaelHatherly sorry for the late response, it would be awesome if you could share your ideas at the julia-i18n chat room:

• https://gitter.im/Julia-i18n/julia-i18n

Doesn't Transiflex provide it's own widgets though, or can it be customised?

Basically one can do anything with JS to the DOM, but we have been short of JS experts able to contribute. @waldyrious has made progress in this:

• https://github.com/JuliaLang/julialang.github.com/pull/551

Note that we also need a solution for swapping out docstrings for a different set of translations at runtime

Currently there is the PyCall based Gettext.jl thanks to @garrison, I've been wanting to port gettext.py to julia, for which I needed a tokenizer, now available thanks to @KristofferC.

• https://github.com/KristofferC/Tokenize.jl
• https://github.com/Julia-i18n/Gettext.jl
• https://github.com/python/cpython/blob/3.6/Lib/gettext.py

I'll focus on porting Gettext.jl, sadly it has also been in the back of my queue because of work.

[joaquimg]

Are there any workarounds for this? I have two complete versions of the markdown files in two languages (no auto translate needed). Can I have a language toggle similar to the version toggle?

[odow]

There is some other discussion in https://github.com/JuliaDocs/Documenter.jl/issues/658

[odow]

Translated docs should also account for some of the hard-coded English words inside Documenter, like Next: https://github.com/JuliaDocs/Documenter.jl/issues/977

[Paalon]

Even if it's not perfect, I want something that works, because translating is hard work.