Consider alerting visitors to unofficial docs translation

[juthilo]

I planned on implementing this but my JS knowledge failed me.

If anybody else wants to jump in and give it a try, be my guest.

I'll open a Pull Request in a moment to convert the translations section in the docs to be generated from YAML data, which might help with the implementation of this feature.

/cc @twbs/team

[hnrch02]

What do you have in mind to alert to visitor with? A standard browser alert or something different?

[juthilo]

Oh please no popup JS alert! :D Sorry, elaborating: Right now, translations are hidden way down on the Getting started page. The idea is to detect a visitor's preferred language, check if we have a suiting unofficial translation available and display a short message and link somewhere on the page. Most recently, I remember www.teslamotors.com having such functionality.

The message and link might go between the purple masthead and the normal content on any page.

The option of saving in a cookie if a user has dismissed the message is also worth considering.

[XhmikosR]

Yeah no alert :/ But something like we do when the user is using an unsupported browser using the showCallout stuff.

[hnrch02]

I'd be happy to look into this, if @XhmikosR isn't doing so already.

[XhmikosR]

Feel free to take care of this @hnrch02. Thanks!

[juthilo]

Cool, thanks @hnrch02 !

[hnrch02]

Will work on this first thing tomorrow.

[hnrch02]

So, here's what I've found out so far: The browser sets a language property on the navigator object, which—as it turns out—is not actually affected by the user's language choice. It is rather the language the browser uses for various strings in the UI. This SO answer provides a workaround for this, which involves a XHR to a server returning the value of the Accept-Language header sent with the request. The question I now have is whether I should use the AJAX approach for this, or simply use the navigator.language property for determining which translation reference to display.

[XhmikosR]

@hnrch02: maybe we should just check for navigator.language. We can always extend this later if needed.

[juthilo]

Yeah, let's go with that for now. Also, sorry I didn't reply earlier.

[hnrch02]

The next question is how we'd expose the list of available translations from that YAML data file to the user facing JavaScript.

[juthilo]

I'm no expert here but maybe we could let Jekyll generate a JSON file from the YAML data?

[XhmikosR]

Unfortunately we can't use any custom plugins with GitHub Pages...

[XhmikosR]

Maybe https://github.com/nodeca/js-yaml with http://stackoverflow.com/a/22671960 ?

[cvrebert]

JSON is basically a subset of YAML you know. So you could just rewrite the YAML to be JSON and then use the JSON in both places.

[juthilo]

@cvrebert As far as I can tell from a quick test, Jekyll can't parse JSON in _data though, or can it?

[cvrebert]

Haven't tried it, but it theoretically ought to work unless Jekyll is pulling some shenanigans. Did you check your JSON with a validator?

[juthilo]

Yup, valid JSON, but no generated list of translations in getting-started...

My original idea was keeping the YAML and adding a file translations.json to, e.g., docs/assets/js/ with the following content:

---
layout: nil
---
[
{% for language in site.data.translations %}
  {
    "name": "{{ language.name }}",
    "code": "{{ language.code }}",
    "description": "{{ language.description }}",
    "url": "{{ language.url }}"
  }{% unless forloop.last %},{% endunless %}
{% endfor %}
]

[juthilo]

Output:

[

  {
    "name": "Chinese",
    "code": "zh",
    "description": "Bootstrap 中文文档",
    "url": "http://v3.bootcss.com/"
  },

  {
    "name": "French",
    "code": "fr",
    "description": "Bootstrap en Français",
    "url": "http://www.oneskyapp.com/docs/bootstrap/fr"
  },

  {
    "name": "German",
    "code": "de",
    "description": "Bootstrap auf Deutsch",
    "url": "http://holdirbootstrap.de/"
  },

  {
    "name": "Korean",
    "code": "ko",
    "description": "Bootstrap 한국어",
    "url": "http://bootstrapk.com/BS3/"
  },

  {
    "name": "Russian",
    "code": "ru",
    "description": "Bootstrap по-русски",
    "url": "http://www.oneskyapp.com/docs/bootstrap/ru"
  },

  {
    "name": "Spanish",
    "code": "es",
    "description": "Bootstrap en Español",
    "url": "http://www.oneskyapp.com/docs/bootstrap/es"
  },

  {
    "name": "Ukrainian",
    "code": "uk",
    "description": "Bootstrap ua Українською",
    "url": "http://twbs.site-konstruktor.com.ua"
  }

]

[hnrch02]

@juthilo That's essentially what I did, I just put it in a <script> tag in the footer for now. I did use a different structure though, something like the following so it allows for iteration with Object.keys.

{
  de: {
    name: 'German',
    description: 'Bootstrap auf Deutsch',
    url: 'http://holdirbootstrap.de/'
  }
}

[cvrebert]

Closing per #13595.