Make TelescopeJS speaks your language with GitHub

In this tutorial, you will learn how to contribute to Telescope: an open-source social news app, built with Meteor.

You will add a new language file, and fix some words in an existing one.

The interesting thing is that you will use only the GitHub website: you don't have to be necessarily a Git ninja to contribute to open source. ;)

You will learn how to

  • fork a repository
  • create a new branch
  • create a new language file
  • edit a language file
  • commit the changes
  • create and send a pull request

A little introduction with some useful information.

Internationalization in Telescope

Telescope supports internationalization through the tap-i18n meteor package. Give it a look, it's very well done.

In tap-i18n a language file is defined in JSON format

// i18n/en.i18n.json
{ 'hello': 'Hello' }
// i18n/it.i18n.json
{ 'hello': 'Ciao' }
i18nscope.meteor.com to motivate you

I made this application i18nscope.meteor.com to show you the current status of all the translations files in the official Telescope master branch, compared to the english master file.

The app also, shows you all the missing keys in each file: isn't it a good reason to start a contribution? Sure it is! :)

Ready, go!

If you don't have a GitHub account, go to the sign up page, otherwise sign in.

Go to the official Telescope respository: https://github.com/TelescopeJS/Telescope

Fork the TelescopeJS project clicking on the Fork button

GitHub, fork the repository into your GitHub account. In my case, my Telescope repository fork is at https://github.com/massimilianomarini/Telescope

Now, to create a new branch, click on the dropdown button, and give it an appropriate name, better if it is short and descriptive.

Cool, The new branch was created and you're in.

Open the i18n folder clicking on it.

This folder contains - and shows you - all the language files actually present.

If your language file doesn't exist, create a new one.

New language file

In this page, GitHub is asking you to insert a file name and a content.

As you can see in the image below, I've named the file zz.i18n.js, it's a fake name for tutorial purpose. ;)

Each language filename must respect this pattern: language_tag.i18n.json

Open a new tab, go to the i18n/en.i18n.json master file and copy its content into your new file.

Translate all the values <key>: <value>, for example: in english is "settings": "Settings", in italian becomes "settings": "Impostazioni".

Never edit the key, only the value must be edited.

When finished, you have to commit your changes; scroll down the page and write what you have done, like in the image below.

Very good!

Are you a bilingual or polyglot? Why not give your contribution to the other translations? :)

Edit language file

Enter into the /i18n folder, choose the file to edit and click on it. In the new page, GitHub shows you the content of the file.

To edit the file, click on the pen icon (on the left of the trash icon).

Now you are in Edit Mode, translate all the values <key>: <value>, for example: "settings": "Settings", in italian becomes "settings": "Impostazioni".

Repetita iuvant: never edit the key, only the value must be edited.

When finished, you have to commit your changes; scroll down the page and write what you have done, like in the image below.

Now GitHub knows you have done some changes and shows you the Compare & pull request button

Create a pull request to the Telescope devel branch. The core team needs to evaluate your work, and if all is ok, it will be merged in the official master branch and released in the next Telescope release.

As in the commit step, write some descriptive information to help the Telescope core team to evaluate your work.

So far so good but in Telescope not only the /i18n folder contains the language file, they are also in each package folder.

i18n in Telescope packages

Click on the /packages folder and you can see a lot of sub-folders, each sub-folder is named telescope-<package_name> is a Telescope package, except obviously the npm-container.

Check each package sub-folder and when you find a i18n folder, open it and when a language file exists or not do the same work you have learned and done before.

An example with the telescope-email package

As you can see in the image below, if you compare the /packages/telescope-email/i18n/ folder with the /i18n folder in the root, bulgarian, russian, turkish and chinese language files are missing.

That's all folks, enjoy coding.