Translating Blockly for more new coders

4 min readFeb 10, 2019

Last year I did a workshop at PyCon Zimbabwe, and this inspired me to look into further-reaching ways to assist tech communities across Africa. Recently I decided to kickstart translating Code.org lessons for Nigeria. Though English is commonly spoken in Nigeria, there is a strong identity for other languages including Hausa, Igbo, and Yoruba.

1. Request a translation project

If you visit code.org/translate you will see that many language projects originate in Europe — even Corsican (with an estimated 325,000 speakers) is in there. African languages have some overlap with Europe, then you can find Arabic and Zulu, but there are many more with large populations.

If you don’t see a language that you’re interested in supporting, you can email international@code.org

2. Go to the source

The first part of the Code.org translation set is Blockly, the visual coding blocks open sourced by Google engineers. Fortunately, translating Blockly and Blockly-Games will give you some interactive examples which can be used by multiple projects and perhaps inspire future translations.

I’ve copied the translation strings from Blockly, added comments for context, and pasted them all in this Google Doc. I also included the Blockly guide to translations with all of my messages.

3. Find a translator on UpWork

I have found several translators on UpWork, and their work is great for this ‘kickstart’ approach to translating. I advise to create a project and upload your files first. Then when you are working the search tool, make sure to include translators outside of the U.S. in your search (sometimes US-only is turned on by default).

You also want to explain concepts such as “I bought %s eggs”… this string needs to be designed to support zero, one, two, three… and plurals work in different ways in each language.

4. Entering translations into TranslateWiki

Blockly uses TranslateWiki, which means you may need to create an account, answer some existing wiki translations in good faith, then wait ~24 hours to have full access. If you end up using English-US-UK or Spanish to get through the account-creation process, no worries - you’ll still be able to add translations in any language.
Complete your translations, and Blockly will within days download their JSON file into the develop branch. In the next release, the JS file will be generated.

5. Adding your language to Blockly-Games

You need to add your language and its ISO code (preferably two letters) to two files on the Blockly-Games repo, as seen in my pull request for Hausa.

5b. Making your own demo

A new language won’t show up on the official site right away, because Blockly needs to have a release before that JS file is created and available in Blockly-Games’s third-party dependencies. If you want results now, you should fork Blockly-Games and create your own repo on GitHub Pages.

Here’s my process, using their build instructions as a guide:

Make sure that you still have the two file changes which you made to the blockly-games repo.
Also edit the JavaScript so that your language is the default option.
Download Google’s Closure compiler and have closure-library directory in the same directory as blockly and blockly-games.
Download your translation PO file from TranslateWiki and use this script to generate a JSON file from it
In Blockly’s msg directory, run ../i18n/create_messages.py json/ig.json to add a msg/js/ig.js file.
In blockly-games, run make deps to download and build dependencies.
Copy your custom JSON and JS translations into the appropriate locations on the file system inside blockly-games/appengine/third-party/blockly
Also copy the JSON file from your Blockly repo into blockly-games/json/ Remove all-caps keys from the file (these are for Blockly and will throw an error on Blockly Games).
Either set your master branch to be your forked repo’s GitHub Pages branch, or run git checkout -b gh-pages to use the default page-hosting branch.
make languages would build all Blockly Games for all languages, but this process takes multiple hours, so I removed any other languages from blockly-games/json/.

Go around .gitignore — this should capture your translations.

git add -f appengine/third-party/blockly appengine/third-party/JS-Interpreter
git add -f appengine/generated appengine/*/generated appengine/*/*/generated

Push to gh-pages branch:

git push yourfork gh-pages