-
Notifications
You must be signed in to change notification settings - Fork 53
Internationalization
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,
This is the most important step! Make sure that you're adding a key to the locales, not just writing plaintext into the view/controller.
i18n-tasks rm "controller.view.key"
If you're editing a message (but not its key), you'll need to re-translate it to all of the non-base locales. To do this automatically, first remove the translations of this message, then add the edited message back in the base locale.
After adding and/or editing these messages, you should be able to see the new/edited key(s) are missing in the non-base locales by running i18n-tasks missing.
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.
i18n-tasks health
Make sure the locales are still healthy after you added these messages. This means that everything is normalized, there's no unused messages (did you remove some messages but forget to remove them in the locales?), and all of your locale variables are consistent. If i18n-tasks health doesn't return clean, you won't pass tests!
There are some consistent ways in which Google Translate messes up translations for FromThePage. If any of these words are included in your new messages, please edit the French translations as so:
- "Work" incorrectly translates as "travaille", it should be "œuvre"
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.
Here's how you can add a new language to FromThePage, or another similar Rails app, using i18n-tasks and the Google Translate API.
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.
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.
Since we've added tests for locale health, this step is much easier! These tests include everything in i18n-tasks health, so the only thing left to check for this step is string literals, as i18n-tasks can't check for that. Slimkeyfy can help with this, but it won't get everything.
See #3169 for my log of improving FTP locales before adding French.
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:
-
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.
-
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.
You'll also want to add the new language to ignore_missing and ignore_unused in that file.
Add the name of the new language here to be displayed in the FTP language pickers.
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.
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:
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.
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".
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.
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 --format yaml. So, i18n-tasks translate-missing -l it --format yaml >> ~/dev/log.txt
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.
See #3232 for how we did this with French.