The language of programming.
I live in a bubble of English speakers who write English code in English-based programming languages using English tools with English documentation. I do not speak any other language aside from some amateurish American Sign Language, and being able to count to 10 in a couple different languages.
Because of this it is difficult for an native English speaker to relate to the experience others have learning how to be a programmer and how to work in this ecosystem when English is not your first language.
Discovery
This may sound dumb to many, but I had never really grasped how big of a problem this is before. I always knew it probably sucked, however it wasn’t until a few weeks ago that I internalized it.
About a month ago now I read a GitHub thread with a person who struggled to communicate the problem that they were having because they were not a native english speaker. They went back and forth for a while before the maintainer finally understood their problem. They wrote a frustrated “RTFM” response linking to their README, and then they angrily closed the issue.
However, that README was written in English, a language that this person could barely speak. So who could blame them? This hostility from the maintainer was totally unwarranted.
I started to think about all the other experiences I’ve had on GitHub with non-native english speakers. There has been so many issues and comments that would never have existed if there was not this massive language barrier in the documentation. I began to feel responsible for this problem, I had never once made an attempt at actually lowering this language barrier.
I looked at the Google Analytics for the Babel website and discovered something that I supposed I should have expected but hadn’t really considered– A third of our users spoke a different language.
I asked around to other people who maintain popular tools, I found that non-english speakers made up 20–40% of the total users. It’s not hard to imagine that this number would rise significantly if documentation was available in other languages.
Getting Started
Something needed to be done about this problem, at the very least in the documentation that I’ve written. I took my most popular repo, a handbook on how to write Babel plugins, and I created a translations directory with markdown files for every translation. Then I opened an issue and asked people for their help translating.
That issue quickly became the most popular issue in the entire repo with people offering their help. Chinese, Spanish, Russian, Dutch, Korean, French, Hebrew, Italian, Romanian– people from all around the world wanting to contribute, in a repo that had almost no contributors aside from minor typo fixes.
The tooling problem
Then it was pointed out to me that maintaining translations in markdown files is a nightmare. No one would ever know if things were up to date and there’d be no way of managing it.
I evaluated a number of translation tools and eventually came across Crowdin.
Note: This is when it’s going to start sounding like an advertisement, but I promise I’m not being paid for this.
It appealed to me for a number of reasons:
- Support for Markdown files
- Free for open source projects*
- Unlimited target languages (for open source projects)
- Unlimited participants (for open source projects)
- CLI tooling and webhooks for keeping things in sync
* It has to be manually approved and has a couple arbitrary qualifications for getting approved, which kinda sucks but it didn’t take long. See here.
I took some time and set up a server that has endpoints for both GitHub and Crowdin webhooks that synced between the two using a GitHub bot (I wrote a guide on how you can do it yourself here).
Translation
Once I had setup everything, I updated the thread and asked everyone in it to sign up for Crowdin and start helping out.
Within 24 hours I had translations for Simplified Chinese and Romanian, with Russian, German, Italian, and others on their way. I watched as they worked together to translate the documentation.
In my mind, this is open source at its finest. The translators already spoke English well enough to translate it, so this is an inherently selfless form of contribution, and I really can’t thank all of the translators enough.
The Future
The question now is how to bring translations to the entire Babel ecosystem. The plugin handbook is a good start, but there’s a lot more that could use this treatment.
As a community we need to get better at this problem. As maintainers we need to do more to support what is a massive number of our users. Translations should be on the checklist for every popular tool and framework. I think we’ll all be surprised at how many people are willing to step up and contribute.
Follow me on twitter
