Add multi-lang support for docs

[JohnONolan]

We've got a ton of translation offers, docs is probably the best possible place we can start to make use of them.

Let's have a look at making out gh-pages jekyll branch support multiple languages.

http://developmentseed.org/blog/multilingual-jekyll-sites/

[ErisDS]

How do you want to proceed with this? There's a PR but it's not mergable because it has fake translations. Should we rip those out but leave the changes which make translating possible in?

Can we get a first example translation?

[JohnONolan]

Matt and I are still working on this - it is not ready for merging or next steps just yet

[DuncanMacWeb]

I wonder whether it would be good to systematise the structure and process of docs translations. At present the structure of the docs and incoming translations is still in flux. (Previous discussions: #1233, #1370)

@JohnONolan, you’ve said you’d like to use two-character country-coded subdirectories as the main means of accessing translated docs (e.g. Canada: docs.ghost.org/ca, Belgium: …/be, China: …/cn, Brazil: …/br).

• Advantages: This would allow geotargeting in Google’s Webmaster Tools, and possibly localising content (special content for Canada, etc.; could be used for Node hosting of special interest to local markets).
• Disadvantages: having to make the country–language links work; some countries have multiple major languages; there is likely to be much duplicate content because lots of major languages are spoken in many countries.

Is this decided as the way to go?

If so, it would be good to find a sensible way of linking country-coded URLs (using ISO/BCP 47 codes) with translations in such a way that it’s easy for people to edit the docs/translations and keep the languages in sync, while not requiring multiple copies of each language. If editors & translators could use Prose.io that would be marvellous. ;)

I see these challenges:

• Automating mapping country codes to languages
• Providing graceful fallbacks (pt ↔ pt-BR, zh-TW/zh-Hant ↔ zh-Hans, fr-CA ↔ fr)
• Ensuring there’s no need to maintain more than one copy of a docs language just because there’s more than one country that uses the language.
• Maintaining translations as the source content changes (something like GetLocalization or Transifex could come in handy)

Notes:

• The Unicode CLDR includes a ‘likely subtags’ chart (html | json*) that gives sensible default languages for each country and vice versa. (*We’d need the und_* keys.)
• It might be possible to put together something that plays nicely with Jekyll and GitHub Pages, without plugins, to link country-coded top URLs with appropriate languages using the CLDR data, maybe using Jekyll’s Data Files feature combined with site & page variables.
• Markdown partials can be included using this technique; could be used to include content designated by its language code in country-coded pages
• Development Seed have outlined their technique for multilingual Jekyll sites, but it’s based on using language codes, not country codes.

[ErisDS]

Seems you missed this: http://docs.ghost.org/translations/, we settled on using IETF :)

[DuncanMacWeb]

Ah, yes! I suppose all things considered, that is the simpler approach :D
I was keeping an eye out for updates to the conversations in #​1233 and #​1370.
There’s still versioning to think of, so if syncing becomes a headache, those localisation platforms could be an option; after translations are established, updates are likely to be small edits that could easily get out of sync. Can think about that later though.

[ErisDS]

Aye sorry, meant to put a comment on your PR when I closed it.

[DuncanMacWeb]

No worries!