Translate Refinery

3 minutes and 44 seconds read.

Translate Refinery

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:

          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.

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 (

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

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.