localisation: current state and outstanding challenges

[pwalsh]

Current state of play

Much of the site is translatable:

• Guide
• Glossary
• Value Stories

Some sections are not:

• Resources
• Credits

There are some challenges with managing translations in our use case. We've covered most of the territory, but some areas are left in need some work.

How it works

• We have a list of all languages, used for lookups that resolve a language key to a name: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L46
• Each section also has a language list, which represents that sections coverage. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L141
• Each section also has a helper key for activating language-specific logic. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L122
• Each content type has a default language of English. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L227
• Each content file also declares a language in front matter. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/guide/ja/how-to-open-up-data/index.md
• And then, of course, any given section that has translations is divided up by directories for each language: https://github.com/okfn/opendatahandbook-v2/tree/gh-pages/guide

All these elements are used in various places in the code, usually while looping over pages:

• All lists of content are language aware. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_layouts/glossary.html#L8
• The TOC on the index page of the actual guides is built in a for loop (so additions to the guide, or changes to a chapter title, for example, are always picked up for a given language): https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/toc.html#L1
• Likewise, the main navigation is built via a similar (but simpler) loop: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/header.html#L57

What's working

• Any page that has one or many translated versions will display links to them
• Links in the main navigation are language aware (if I'm in the german guide, the links will be to other pages in the german guide)
• The "internal TOC" of all guides is language aware

What's not

• While the main navigation has language aware links, the title text is not language aware. As noted about, this is because it uses a rather naive loop, based on this data structure: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L186
  • Fixing this is totally possible, and will be something like this loop already working for internal guide TOC: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/toc.html#L1
  • The above TOC loop pushed my local build times from 7 seconds to around 30. Expect similar render time degradation when we deal with the main nav TOC in a similar fashion
• The website has no concept of state, so if a user is navigating, say, the german guide, and navigates to a language unaware page like credits - the user has moved back into english (all links from there will be "en" namespaced, and not "de"

[jayvdb]

Also there are {term:xyz} on translated pages (e.g. http://opendatahandbook.org/guide/id/why-open-data/ ) instead of links to the terms/ pages.