Localization Guide

Making Scratch accessible to communities beyond those who speak English is very important to us. We make a lot of effort to make sure as many parts of our site are localized into as many different languages as we can. Part of our localization efforts involve making sure we properly tag all text on our website so that it can be translated by our localization community*.

In order to make Scratch translatable, we use a React plugin called react-intl. React-intl provides components in which you can wrap text on the website, which it then uses to look up translations for that text (we currently use the beta for v2 version of this plugin). For static text inside of components, react-intl provides us the FormatMessage component to use. For instance, say we have the following text on Scratch:

var React = require('react');

var HitchhikersGalaxyGuide = React.createClass({
    .
    .
    .
    render: function () {
        return (
            <p className=”box-content”>
                In the beginning the Universe was created. This has made a lot of people very angry and been widely regarded as a bad move.
            </p>
        );
    }
});

If we wanted to make this translatable, we would turn it into the following:

var React = require('react');
var FormattedMessage = require('react-intl').FormattedMessage;

var HitchhikersGalaxyGuide = React.createClass({
    .
    .
    .
    render: function () {
        return (
            <p className=”box-content”>
                <FormattedMessage
	            id: ’info.DouglasAdamsQuote’ />
            </p>
        );
    }
});

And we'd then add the string that is to be displayed into our template localization file, called l10n.json:

{
    .
    .
    .
    "info.DouglasAdamsQuote": "In the beginning the Universe was created. This has made a lot of people very angry and been widely regarded as a bad move.",
    .
    .
    .
}

Adding it to the template file ensures that when messages are loaded into the react component, this one will be found by the id check for info.DouglasAdamsQuote.

You may notice that there are multiple files called l10n.json in this src directory. This is done to ensure that only the relevant strings for a view are loaded onto that page for localization at request time. The basic structure of our l10n files is as follows:

• /src/l10n.json – contains general strings that are re-used in multiple parts of the site.
• /src/views/:<viewName>/l10n.json – contains strings specific to the view of viewName (such as splash, or about).

Only views should have l10n.json files in them – components should not.

We occasionally use some of the other react-intl components/methods – formatMessage(), FormattedHTMLMessage, or FormattedRelative – but they are not as likely to be used (more information on them is available at react-intl).

When assigning a string an ID, it’s important to give it a descriptive one. Generally, the pattern for id generation should follow the following guidelines:

• id: ‘<name of component or view>.<brief description of what the string says>’

The brief description should not be longer than 4 words total, and if it is more than one word, it should be in camelCase. The exception to this convention is when a string is used in multiple components and/or views – for example, translating the word “About”. In these cases, the guidelines are as follows:

• id: ‘general.<brief description of what the string says>’

So, for the word “About” it might look like: id: ‘general.about’

---

*If you are interested in becoming a translator for Scratch, you can find out more at http://wiki.scratch.mit.edu/wiki/How_to_Translate_Scratch.