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.
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
2 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.
3 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:
nl: refinery: admin: pages_dialogs: link_to: insert: Voeg in
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.
If you’re starting a translation for a new language, copy en.yml to “your_locale”.yml
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:)
4 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
5 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
6 Pull request
- 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.