This add-on is operated by Tigrish LTD

Easy localization for Rails apps


Last Updated: 14 January 2014

Table of Contents

Localeapp is an add-on that removes the pain of dealing with YAML files when using the Ruby i18n gem.

If you’ve ever dealt with sending YAML files to translators or having to make endless template changes because non technical people need content changed then Localeapp is here to help.

Adding Localeapp to your heroku project means you don’t have to manage the i18n yaml files yourself and non technical translators or business people can change content without having to talk to you.

Localeapp is accessible via an API and works with any Ruby framework that uses the i18n gem.

Provisioning the add-on

Localeapp can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add localeapp
-----> Adding localeapp to sharp-mountain-4005... done, v18 (free)

Once Localeapp has been added a LOCALEAPP_API_KEY setting will be available in the app configuration and will contain the API key required to access the newly created project. This can be confirmed using the heroku config:get command.

$ heroku config:get LOCALEAPP_API_KEY

After installing Localeapp the application should be configured to fully integrate with the add-on.

Local setup

Ruby Version

We recommend you use the latest version of ruby 1.9.3 as the default version on the Cedar stack has a very old version of Psych, the ruby YAML parser and defaults to using Syck which can produce invalid YAML. The easiest way to do this is to specify the ruby version in your Gemfile by adding:

ruby '1.9.3'

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export LOCALEAPP_API_KEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the LOCALEAPP_API_KEY values retrieved from heroku config to .env.

$ heroku config -s | grep LOCALEAPP_API_KEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Service setup

Localeapp is best used in the development and staging environments. It is possible to configure it to fetch new translations in production but this isn’t recommended.

Using with Rails 3.x

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Localeapp client library.

gem 'localeapp', :github => 'Locale/localeapp'

Update application dependencies with bundler.

$ bundle install

Create the template heroku initializer by running

$ bundle exec localeapp install --heroku

This will generate an initializer file setup for best practises as described below. Your API key isn’t in this file so it can be safely added to source control.

Development environment

When developing locally it’s recommended that you run the localeapp daemon as another service in your Procfile by adding.

localeapp: bundle exec localeapp daemon

This will check for new content every five seconds and add anything it finds to your yaml files.

Staging environment

The generated configuration also sets up reloading in every request or “live reloading” for a staging environment.

We can set up this environment by overriding the rails environment name with LOCALEAPP_ENV

$ heroku config:set LOCALEAPP_ENV=staging

Translations are updated upon every request and also fully pulled every time the dyno restarts.

Production environment

We recommend that you commit your YAML and push to production when your happy with it rather than have it pulled down automatically. You don’t want production to get content for features still in development. For this reason the default configuration does nothing in production. See the Staging section just before this for how to override if you need to.

Deploy changes

Deploy the Localeapp configuration to Heroku:

$ git add config/initializers/localeapp.rb
$ git commit -a -m "Adding localeapp config"
$ git push heroku master
-----> Heroku receiving push
-----> Launching... done, v3
       http://warm-frost-1289.herokuapp.com deployed to Heroku

To git@heroku.com:warm-frost-1289.git
 * [new branch]      master -> master

For more information on the features available within the Localeapp dashboard please see the docs on the Localeapp Wiki.

Adding existing content

If you have existing content in config/locales you can import this to Locale with

$ bundle exec localeapp push config/locales/*.yml


The Localeapp dashboard allows you to:

  • Invite developers and translators to edit the content
  • Add translations for existing ruby libraries (these don’t count towards your plan limits)
  • See how complete each locale is
  • Add and remove locales
  • Import existing yaml translation
  • Export the content at any time

The dashboard can be accessed via the CLI:

$ heroku addons:open localeapp
Opening localeapp for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question followed by “Localeapp” from the Add-ons menu.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade localeapp:newplan
-----> Upgrading localeapp:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: localeapp:newplan

Removing the add-on

Localeapp can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove localeapp
-----> Removing localeapp from sharp-mountain-4005... done, v20 (free)

Before removing Localeapp a data export can be performed by choosing export from the dashboard.


All Localeapp support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome by using the feedback link in the help menu.