Have a localization story

[ceejbot]

Inspired by the closing keynote of JSConf EU. We have some gestures toward localizability in error codes, but we need to be rigorous about it. Also, we need to have a plan for getting there with the client.

[chrisdickinson]

I suggest using something like y18n (I saw it used in cacache and liked it!)

[jkrems]

At first glance y18n may run into issues when trying to have proper plurals (e.g. it only supports English plural rules afaict). Not sure how much of a concern that is for entropic specifically. :)

[nschonni]

Might be good to pick a translation file format EX: http://docs.translatehouse.org/projects/translate-toolkit/en/latest/formats/index.html Having a translation file format will help using translation platforms as the number of strings grows

[NerveClasp]

I'm upvoting this with both hands! Please do make a way to localize cli messages and I will devote all my free time to localizing this marvelous tool into Ukrainian =)

[jimmywarting]

Intl.PluralRules would be good for plural stuff. y18n should have used it 😞

[zeke]

I'd love to help out on this effort.

For the last couple years I've been working on internationalizing Electron, Node.js and soon GitHub. For all of these projects, we've used Crowdin, a localization platform that allows anyone to jump in and easily start translating strings into myriad languages. On Electron we've had translations submitted by over 1700 people!

Some of the features that make Crowdin a compelling choice for a project like this include:

• It has a GitHub integration that automatically ingests source (English) content from your repo and opens pull requests when translations are made.
• It keeps the content of your translated files congruous with your source files. So even if the contents of the translated files are not fully translated into their target language yet, they will always have the same content and structure. This is a key differentiator from translation setups that exist entirely in GitHub repos, where the content in translated files quickly falls out of date, never to catch up with the English source.
• It has support for GitHub Flavored Markdown (most localization platforms don't)
• It supports JSON and YAML files with arbitrary structure (not sure about Toml)
• Translators can auth into the Crowdin project using their existing GitHub accounts
• It's free for open source projects
• They have great support

For the curious, here are some existing projects:

• https://crowdin.com/project/electron
• https://crowdin.com/project/nodejs

I think a good first step toward internationalizing entropic would be to externalize all the English strings: that is, extract them from the JS source code and into a structured file like JSON or YAML. Once that work is done, it's pretty straightforward to set up a localization pipeline with Crowdin that can ingest the Markdown docs and structured CLI strings.

[zeke]

the closing keynote of JSConf EU

Is this online yet?

[huijing]

@zeke here it is: https://youtu.be/SeV_Pqw5egU

[gribnoysup]

@zeke crowdin looks cool! Do they have some sort of free tier for OSS?

[fetis]

we don't not fully meet Crowdin open source requirements yet https://crowdin.com/page/open-source-project-setup-request

You have been working on your open-source project for at least three months.

first commit was in Aprial

You keep the "News" section of your website up to date.

website? :)

You release updated builds on a regular basis.

I'm not sure about this too.

But I'm very pro to use proper translation platform for docs at the first place.

[zeke]

I'm sure we'll have no problem getting a free Crowdin plan for this project. cc @andrulko

[fetis]

Since people start to do some implementation. I would like to share my experience on how i18n of software should be done.

• you never should manually control your i18n strings. use extraction tools for that
• you shouldn't use formats not suited for that like JSON. Use .po or XLIFF instead.
• you should mark your string for translation in the source code. your i18n will replace in target language.
  • you should have the ability to specify plurals
  • you should have ability to specify replacements, like box type X and packages size Y
  • you should have ability to specify locale format for dates or use unified format.
• you should use online translation platform (like Crodwin mentinoned above and many others) for translation itself.
• the integration process should be automated as much as possible: after addition a new string, you extract it automatically, translate on the platform (mostly manually) and automatically bring it back for build or runtime. This leads to requirement: translation platform should have a CLI tool.

I think we need aggree on the process before any development.

@zeke can share what tools Node.js currently use for translation so we can re-use it if it's ok with us.

[zeke]

@fetis the projects I've worked on are mostly reference documentation in the form of Markdown, YAML, and JSON files. I do not have much experience with internationalizing user interfaces, especially those with dynamic content where there's a need for custom plurals, currency, etc. I haven't used any of the JavaScript localization libraries, like y18n which was mentioned above.

That said, all the modern browsers now have support for a bunch of really useful localization stuff:

• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleTimeString()
• Number.prototype.toLocaleString()
• Intl.getCanonicalLocales()

As far as tooling goes, Crowdin does most of the work of moving content in and out of the repo, but our community has authored a handful of tools to close the gaps where Crowdin doesn't fit our needs. You can find those here: https://github.com/crowdin-modules

[jkrems]

The downside of the built-in localization logic is that it requires node runtime flags to be useful since node ships with the English CLDR data only by default. But once that's figured out, it makes a lot of sense to use the standard Intl APIs where applicable!

A huge 👍 to everything @fetis wrote above. I would also add that choosing a good string format (e.g. MessageFormat) may pay off long term. Those formats have some chance that translators may be familiar with them and they have a decent amount of organizational wisdom baked in. Alternatively there is fluent which is backed by Mozilla IIRC: https://github.com/projectfluent/fluent.js.