Internationalizing Node.js

Node.js Collection
Published in
7 min readJan 17, 2018


“It is our job to ensure that a global and multilingual community is maintained, and that no one is left out of work they’d like to do because of linguistic barriers.”

Richard Littauer, Node.js Contributor

Node.js is about people, first and foremost

Anyone I’ve met who’s committed to the growth of this project seems to hold to the above sentiment as a core principal. I see it in the fabric of our Community Committee each time we meet. It keeps me going, and gets me more involved–all the time. Enablement through community-engagement is our mission, and we care deeply about empowering people–no matter which language they speak, or what background they come from.

The effort to Internationalize Node.js was recently entrusted to its Community Committee, and we’re excited to pick up where the previous work left off. We’re not about to let language differences keep anybody from experiencing all that our community and runtime have to offer. In 2016, we saw that 49% of the participants in the Node.js user survey identified English as their second language. Our users shouldn’t have to speak native English in order to leverage the power of Node.js for their own endeavors–or more ideally, have to speak it at all.

Accordingly, members of the Community Committee and I are happy to present a new proposal to push this effort forward.

I’ll be bringing you up to speed on:

  • The current international-language needs of Node.js
  • A Node.js Internationalization (i18n) & Localization (l10n) status report
  • Our proposal for moving Node’s i18n forward as a function of the Community Committee

Node’s Current International-Language Needs

The language-landscape of the Node.js ecosystem is incredibly vast.

npm recently gave us a look into the current language preferences of the global Node.js community–based on the default browser settings for all visitors to* This clearly lets us see where our greatest translation needs are at the moment.

The Top 10 languages of Node.js users

What we can gather from this:

  • More than 30% of Node’s userbase natively speaks a different language than English.
  • Translating our site, docs, tutorials, and necessary text-vectors of Node-core (eg. error messagesª) into the languages above is extremely important as not to alienate current users, and stifle potential growth of the project.
  • Moving forward, the priority of l10n project targets will be defined by the order of the languages represented above.

Current Status & the Ongoing Struggle for i18n

io.js i18n set the tone for Node

Along with the excitement of the io.js fork came a serious push to establish l10n groups for the project–and it was quite successful! language options

When the Node.js Foundation was born, the io.js i18n methodology was carried over and became the template for Node’s current working model:

Current Node.js i18n Process
  • l10n groups translate Node’s textual content into their own languages as needed for the community of a given locale.
  • Translation commits land in l10n repos (eg. nodejs/nodejs-fr).
  • i18n projects are determined by the Technical Steering Committee, and then driven by the Intl Working Group–who then works directly with l10n groups to land changes in Node’s site, docs, modules, and core.

This has worked to Node’s advantage for some time, but significant issues with this model are now holding the project back.

What’s broken now?

Issue 1: Distributed Pace

“We’ve tried several times–but translating all of the API docs while trying to catch up with the upstream was too hard, so it’d be out of scope for now even though it’s super important.”

Daijiro Wachi, Node.js Collaborator

With testimonies like this, it’s easy to see that the current translation system is becoming increasingly ineffective–given the pace of updates that are landing upstream. It’s not able to streamline & integrate in a way that effectively scales.

Issue 2: Bottlenecking anti-patterns in the Github process

  • Translators have to understand the Github workflow, and how to navigate its UI. This may be fine for some people who have previous experience with GH, but causes an unnecessary barrier to entry otherwise.
  • The time it takes for each contributor to generate l10n group PRs & updates, as well as Node.js i18n project PRs & updates is a significantly congestive. With additional time then needed to prioritize and review them, productivity has the potential to slow down to stagnancy.

Issue 3: Ongoing Willpower for l10n Groups

“It seems that the French repo has been pretty dead for 2 years.”

Benjamin Zaslavsky, Node.js Developer

This is most likely a side-effect of the first two issues.

If a l10n project just can’t keep up with the frequency of core’s changes, and the number of available translators is limited to individuals who understand or are willing to learn the Github workflow–the group’s excitement about their project is bound to fade (most likely after experiencing some burnout).

If the Node.js core integration cadence becomes irregular while l10n groups work on i18n projects–the drive empowering them will probably dry up. People get excited when they see their changes utilized.

Node.js i18n v2

With the burden of Node’s i18n weighing us down the more it globalizes, we need to rethink our process a bit. Thankfully, there are a lot of amazing people around us to learn from.

Learning from Electron’s example

The Electron community has been doing outstanding work in their internationalization efforts and we can learn a lot from their recent case study & implementation decisions.† They’ve come up with a pattern that is solid and sensible for the current i18n needs of Node.js using the Crowdin localization management platform & one awesome Node.js module.

The Crowdin advantage:

  • Asking translators to jump into the Github environment is confusing enough. Crowdin beautifully abstracts away the cruft into a simple & useful interface.
  • Each localization project contains a directory tree of of the core project’s documents–giving the translator continuous visibility on what has and hasn’t been translated, streamlining the process entirely.
  • A simple work environment presents untranslated documents in one row, and the localized version being updated in another.
  • A Crowdin project seamlessly integrates with an existing Github repo, automating PRs & updates from its internationalization projects.
  • It’s FREE for open source projects!

A hand-rolled i18n module

I think the Electron community’s brilliance shines brightest in their electron-i18n module. It empowers the parent project by providing one JSON object containing the current state of every translation, with anything untranslated gracefully falling back to English.

A new i18n process for Node.js

Seeing that other i18n projects are now flourishing utilizing the Crowdin service & custom modules, I’d like to propose a new internationalization process for Node.js.

New Node.js i18n Process Proposal
  • The Node.js Community Commitee’s new i18n Working Group gathers and supports Node’s translation base. This consists of our current l10n groups, independent translators, and hired translators (if a strategic initiative’s priority ever necessitates that).
  • Our translation base utilizes Crowdin localization projects for their work. The projects are born by statistical need and community desire.
  • The work in Crowdin l10n projects generate automated PRs & updates to our own Node.js i18n repo.
  • Our Node.js i18n repo exports one large JSON object, containing all site, docs, tutorial content, and helpful text in Node.js core–translated into every language.
  • The i18n module is imported and used wherever it’s needed by Node.js to implement strategic initiatives.

As it turns out, maybe the missing glue between our l10n groups & core integration is a Node.js module! 😎

Supporting Strategic Initiatives

The most imminent endeavor for the i18n Working Group to support is our new site.

Since the site is the face of Node.js and a Community Committee initiative, i18n is going to be a first-class citizen of the project. We will be tracking along with its development timeline.

We’re excited for our work to complement the site redesign nicely, and level up Node’s internationalization offerings.

Help Wanted

“Any fool can make something complicated. It takes a genius to make it simple.”

Woody Guthrie

Creating simplicity takes a lot of work. We’re going to need help from anyone who’d like to offer it.

What we have ahead of us right now

  • Seek the approval of Node’s current i18n groups concerning this proposal.
  • If successful, get the word out and ask our groups for translation help–and request they might invite anyone who would like to join us in this.
  • Begin building our new i18n module, conversing with Node.js core contributors and the TSC along the way.
  • Track the progress of our site redesign and integrate.

Ways to help

Please track our progress in the Community Committee, and feel free to jump in anywhere as we grow. Our i18n Working Group repo will be available shortly.

We’ve got some great work to do, and we’d love to have you be a part of it.

Many thanks to Adam Miller, Ben Tiriel, Rachel White, Daijiro Wachi, Tierney Cyren, Zeke Sikelianos, Tracy Hinds, DShaw, James Snell, Michael Dawson, and everyone who’s contributed to this endeavor!

*Thanks to npm & Adam Miller for providing us with language preference stats.

ªThanks to Michael Dawson for the seeding this idea.

†Thanks to Zeke Sikelianos for your “drive-by comment” in our community committee issue.



Node.js Collection

I build hacker communities and ♡ the Internet of Music. Developer Advocate at @invisionapp. @nodejs CommunityCommittee & TSC. Leading meetups. Dabbling in ECMA.