Refinery supports internationalization (I18n for short), which includes translation. This guide will show you how to:
- Improve upon or add a new translation to Refinery
Before you start translating, you should clone a fresh copy of Refinery from GitHub. See the contributing guide for information regarding how to do that.
It's not required, but we strongly advise you to create a separate branch when adding a translation or a new feature. You can do so by typing the following shell command.
TIP: Throughout this guide, we refer to the Dutch locale (nl). In most circumstances, you will not want to refer to this locale; be sure to substitute nl for the locale you're working with.
$ git checkout -b i18n_nl
Finding missing keys
First, you must create a 'dummy' application to enable additional useful rake tasks. Do so with the following command:
$ bin/rake refinery:testing:dummy_app
Then execute the following to get a list of missing translations for all locales:
$ bin/rake app:translate:lost_in_translation_all
Or execute the following rake task to get a list of missing translations for a given locale:
$ bin/rake app:translate:lost_in_translation LOCALE=nl
The output of this will look like this:
Searching for missing translations for the locale: nl refinery.admin.pages.form_advanced_options.page_options in pages/app/views/refinery/admin/pages/_form_advanced_options.html.erb is not in any nl locale file refinery.admin.pages_dialogs.link_to.insert in pages/app/views/refinery/admin/pages_dialogs/link_to.html.erb is not in any nl locale file Number of missing translations for nl: 2
As you can see, there are two missing keys: refinery.admin.pages.form_advanced_options.page_options and refinery.admin.pages_dialogs.link_to.insert.
Adding the keys
Each plugin has its own locale YAML files. The one we'll have to fix is pages/config/locales/nl.yml. Note that it is important to put the right key in the right file.
The key refinery.admin.pages_dialogs.link_to.insert is represented in YAML like so:
Order the keys exactly like the en.yml version. This way, you can use a diff-enabled-editor to open both the en.yml and nl.yml file to quickly update the locale. If you are making changes to the en.yml file, alphabetically list keys you add.
TIP: If you're starting a translation for a new language, copy en.yml to "your_locale".yml
WARNING: Make sure you change en: to your locale's key at the top of "your_locale".yml to avoid overriding the English translation (e.g. nl:)
Run the Refinery tests
Run the Refinery tests to be sure you didn't break something, and that your YAML is valid.
$ bin/rake spec
Commit & Push
Add the modified files to the git repository
$ git add pages/config/locales/nl.yml
Commit your changes
$ git commit
and push them back to GitHub
$ git push origin i18n_nl
- Go to GitHub, and select your i18n_nl branch;
- Click on the button "Pull request";
- Add a message about I18n, like "Hi, I've translated the missing Dutch keys";
- Press "Send pull request".
And now you're done! If your changes are accepted, you will end up on the contributor list.