Flyout: better language switcher

[strophy]

Read the Docs could benefit from a more user-friendly language switcher. I suspect the current language switcher is included in the code that generates the flyout, since its appearance is the same in both the RTD and Alabaster themes. Instead of listing lang_slug codes in the flyout, it would be preferable to offer a native language human readable language switcher according to best practices described here, and in a more visible (and configurable?) location.

• Read the Docs project URL: https://docs.dash.org
• Read the Docs username (if applicable): strophy

[stsewd]

We have this in the readthedocs.org footer

Also, the space in the *.readthedocs.io floating footer is very small, maybe that's why it doesn't show the large form?

[strophy]

Oops, I have opened this issue on the wrong repo? I agree that the readthedocs.org language switcher is great, I am looking for something similar in the Sphinx docs hosted by RTD. On my project, you need to click once to open the flyout (with no indication the language switcher is in there), then again on a language code (rather than a human-readable language name).

I would like to get this in a more visible and user-friendly format.

[stsewd]

Oops, I have opened this issue on the wrong repo?

No, at all. I agree the language chooser needs to improve

[strophy]

I would be interested in making a one-time donation or bounty to support this work :)

[RichardLitt]

Might be worth weighing in on this issue: readthedocs/readthedocs.org#3129. At the moment, I don't think we have a recommended bounty program in place.

[EdOverflow]

@RichardLitt, readthedocs/readthedocs.org#3129 is concerning a security bug bounty program. I believe @strophy is after something along the lines of https://www.bountysource.com/.

[RichardLitt]

@EdOverflow Good catch. You're right.

[strophy]

Correct @EdOverflow - I'm looking to either directly fund or post a bounty for development of an improved language switcher in line with the RTD coding and style guidelines. I'm happy to post this on Bountysource, unless someone here can give an estimate and offer? Feel free to PM or email [email protected]

[stsewd]

@ICJR thanks for the interest in collaborating here! Beware that the issue is tagged as Needed: design decision, so we need to wait for a core maintainer to approve this before you start something. This is the template that rtd use to inject the footer https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/restapi/templates/restapi/footer.html

[agjohnson]

This is part of our theme, sphinx_rtd_theme. Feel free to suggest/mock up any design changes you're thinking of first. After we make a decision we can move on to a development phase.

[strophy]

Thanks @agjohnson I suspected I might have the wrong repo here. Let me know if you want me to open another issue on the sphinx_rtd_theme repo instead.

Regarding design:

• I love the language switcher in the footer of readthedocs.org because it follows best practices of writing the native language name, followed by either a language code or the English name for the language. Language switchers should NOT use flags!
• Ideally it should be possible for the user to select either the upper breadcrumbs or lower footer area as a location for the switcher
• A globe icon (same size as the GitHub icon) and a styled dropdown list would fit the theme nicely
• The theme should fetch the list of available translations that is specified under Parent project > Admin > Translations, I think this is already the behaviour for the current language switcher
• Like the visibility of the "Edit on GitHub" link, It should be possible to specify visibility of the language switcher using a variable named e.g. "display_language_switcher" in the "html_context" section of conf.py

Mockup (imagine this with better CSS styling):

[stsewd]

I think something should be done with the floating footer too since not all projects use the rtd theme, so we inject the floating footer for them. Or maybe just make this change for the rtd theme?

[strophy]

Sorry, I don't entirely understand - do you mean put the language changer in the footer only? Or have an option to inject it either there or in the header? I would strongly prefer an option to have it in the header, we have a lot of non-English speaking users and the option to read documentation in the native language (if available) needs to be easily visible.

[stsewd]

There are two ways of using rtd.

1. Using the rtd theme, here we can put the language switcher at the top
2. Using a different theme, here we can't put that at the top in an easy way, we only can inject the floating footer. See http://docs.python-requests.org/en/master/

So, or we only modify the rtd theme, or we do it in both, the rtd theme and the floating footer. Or maybe another place.

[strophy]

Understood, thanks! Waiting for design decision from RTD side.

[agjohnson]

The top-right placement is a feature specific to documentation built with the latest version of our theme, so I'm -1 on that placement. It's also deviating from current pattern of implementing feature as flyout menu options. We have the flyout menu for this case -- dynamic content dropped into static documentation.

I'd say that if you want this dropdown placement on your docs, you should override our theme layout with local theme overrides and apply the dropdown to your docs. If we implement a better language selector, it's most likely going to be in our flyout menu.

I'm not certain what that looks like yet though, a dropdown selector is a deviation of style there, and doesn't fit with the current elements.

[agjohnson]

Accepting for now, but not in it's current state. We need to find a pattern that works for our flyout menu instead of in-doc.

[strophy]

Great to see this accepted, thank you! I think the flyout is an acceptable location, particularly if it makes sense from a design and logic point of view (dynamic vs. static content). But I would suggest some user-facing indication (e.g. globe icon) that settings such as this are actually available in the flyout menu. The current flyout is labelled Read The Docs v: latest which does not provide sufficient indication to a layperson that language settings can be found here. In the absence of Accept-Language header detection (also accepted in readthedocs/readthedocs.org#4600 - thanks!), it is not yet easy enough for non-English speakings users to access the translated documentation we offer by navigating to the canonical URL (e.g. docs.dash.org).

[agjohnson]

Agreed, I like the idea of at least some indication of language. Even just including the language code would be a start:

Ultimately, with a re-implemented flyout menu, I think we will add more visual guides, and likely remove usage of things like language locale codes in place of descriptive locale names. There are probably a few stages to upgrading the menu

[OriolAbril]

Hi, also interested in this improvement.

As it looks like there hasn't been any activity for a while, I have two questions. Would it be possible for me to make this change to show en / latest in the version switcher instead of only latest? If so, would it be ok if I try to update that for now* until a better alternative can be implemented?

*now is being very optimistic, at some point soonish but dependent on available time

[humitos]

This would eventually be supported by #64