Internationalization

Ongoing Maintanance

When you add new user-facing features or any new wording in the UI, you'll need to translate these messages to all of the locales available in FromThePage (currently English, Spanish, French, and Portuguese). To do this,

1. Add your new message(s) in the base locale (English)

After this, you should be able to see these key(s) are missing in the non-base locales by running i18n-tasks missing.

2. Translate your new message into the non-base locales

i18n-tasks translate-missing -p "controller.view.key"

The -p option specifies a pattern, so that if there are more missing keys than the one(s) you just added, only the one(s) you just added are translated. For a group of keys, you could use a pattern like "controller.view.*" to translate all of that view's missing keys instead of specifying one key directly.

If you want to translate only one locale or translate one locale at a time, use the -l option.

Pricing

Because i18n-tasks uses Google Translate v2, not v3, the pricing is $20 per 1 million characters. This means that locale maintenance is really cheap. Adding a short one-or-two word message to three (Spanish, Portuguese, French) languages would be around 0.03-0.1 cents. A longer message, such as a description, would be around 1-2 cents.

Adding a new language

Here's how you can add a new language to FromThePage, or another similar Rails app, using i18n-tasks and the Google Translate API.

Pricing

Because i18n-tasks uses Google Translate v2, not v3, the pricing is $20 per 1 million characters. For FTP, this means adding one new language is around $1-$2 as the base locale has around 60,000 characters.

1. Have healthy locales

The first step to adding a new language is making sure that your locales are totally healthy & happy. If you have unused keys in your locales when translating, you'll spend extra $$ for no reason. If you have keys missing in your base locale when translating, you'll have to go back and translate all of those keys once you add them. Same goes for string literals in your views.

i18n-tasks health gives an overview of your locale's health, including: missing keys/messages, unused keys, inconsistent interpolations, and unnormalized data.

See #3169 for my log of improving FTP locales before adding French.

2. Add the language

First, you'll have to add the language to the config, which is easier than you would expect. You need to add it in three places:

1. i18n's available locales in config/application.rb

Add the symbol for the new language (i.e. :fr, :it, :ru) to the list. This adds the language to FTP's language pickers as well. To keep the language pickers alphabetized, put the new language in this list in alphabetical order.

2. i18n-tasks's available locales in config/i18n-tasks.yml

Add the symbol for the new language (i.e. :fr, :it, :ru) to the list. This allows you to use i18n-tasks with the new language.

3. en.yml

Add the name of the new language here to be displayed in the FTP language pickers.

3. Set up to translate

Add your Google Translate API key in the i18n-tasks config (get one at Google API Console).

Add easy_translate to your Gemfile, i18n-tasks uses this to use Google Translate.

4. Add the messages

i18n-tasks translate-missing -l it will add all of the missing messages for Italian (use whichever language you're adding), which should be all of the messages you have in your base locale (English). However, you probably shouldn't just run that outright. Here are some suggestions:

Check what's going to be translated before translating

i18n-tasks missing -l it shows what translate-missing -l it will translate. You can make this look prettier using -f yaml or -f keys and redirect the output to a yaml or txt file to look at the list more closely.

Translate a small group first

Before translating everything, test on a small group, such as the article_version controller. To do this, run translate-missing with the -p "controller.*" option. You can even do just one message at once, like with -p "article_version.show.revision_changes".

Translate in sections

This is optional, but if you want to be extra careful when you're translating, you can translate just one controller at a time using the -p "controller.*" option.

If you're doing this, make sure you also get messages in helpers and in en.yml. Run i18n-tasks missing -l it to make sure you translated everything.

Redirect output to a log file when translating

To make sure you don't lose any translations, always redirect the output of a call to translate-missing to append to a log file. If you accidentally overwrite a translated file or somehow else lose translations, you won't have to re-translate anything ($$) as you have the translations in this file.

To make this data usable, make sure to add -f yaml. So, i18n-tasks translate-missing -l it -f yaml >> ~/dev/log.txt

5. Review

After you add all of the translations for the new language, i18n-tasks missing -l it should be empty. You should be able to start rails, change your language, and see all of the new messages.

There'll probably be places where the new translations don't fit the UI or the wording is weird. Make sure to look over all of the translations before deploying.