Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Send and retrieve your ruby i18n localizations to the Locale translation service
Ruby Cucumber
Failed to load latest commit information.
bin Add a warning in the CLI help message about being overwritt…
features Tweak Aruba config for jRuby.
lib Bump version to 0.9.3
spec Allow configuration of SSL version to use in HTTP requests
.autotest Add tmp to .autotest and .gitignore
.gitignore Tweak Aruba config for jRuby.
.rspec Tweak Aruba config for jRuby.
.rvmrc Less problematic approach with rvm use --create
.travis.yml Add Ruby 2.2 to Travis matrix Add 0.9.3 to changelog [ci skip] Correct contribution steps for this gem.
Gemfile Remove the deprecated :rubyforge source in Gemfiles
Gemfile.github_project.rb Remove the dependency on a specific bundler version for github projects
Gemfile.i18n_037 Update activesupport gem version for travis with i18n 0.3.7
Gemfile.i18n_050 Remove the deprecated :rubyforge source in Gemfiles
Gemfile.i18n_060 Remove the deprecated :rubyforge source in Gemfiles Update README and CHANGELOG
Rakefile Add aruba gem and basic localeapp binary
cucumber.yml First part of install command, lots of spec setup
init.rb * Replaced all instances of 'locale_app' with 'localeapp' * Replaced …
localeapp.gemspec Add a version dependency on cucumber since newly released version 2.0…


Build status Code Climate Gem Version

The localeapp gem connects your rails app to the Locale service on Locale makes hand editing translation files something you don't have to do.

The gem hooks into the i18n exception mechanism to send missing translations to the app. When translated content has been added it's automatically pulled down so you can see it straight away.


Though the i18n gem uses YAML as it's default file format it doesn't require serialization of ruby objects. To prevent the kind of security problems detailed in CVE-2013-0156 the localeapp gem will not load any YAML containing the string !ruby/ as of version 0.6.9.


Rails 3

Add the localeapp gem to your Gemfile and install it:

echo "gem 'localeapp'" >> Gemfile
bundle install

Create a project on and get the api key. Then run:

bundle exec localeapp install <YOUR_API_KEY>

This will check everything looks good and create config/initializers/localeapp.rb for you.

Rails 2.3

Define localeapp in config/environment.rb:

config.gem 'localeapp'

Install the gem:

rake gems:install

Create a project on and get the api key. Then run:

localeapp install <YOUR_API_KEY>

Non rails projects

Install the gem and run:

localeapp install --standalone <YOUR_API_KEY>

This will create a .localeapp directory for your configuration files.

Public projects

Install the gem and run:

localeapp install --github <YOUR_API_KEY>

This will create a skeleton project you can push to <your_gem>-i18n on github. You get a .localeapp directory for your configuration files, a locales directory for the yaml, a .gitignore file that ignores .localeapp and a explaining to translators how to find the project on

Importing existing content

You can import via or with the command line tool. To import existing translations do:

localeapp push config/locales/en.yml

This will queue importing the file. The projects pages on will automatically refresh so you can see the import progress.

If you've more than one locale to import you can import all files in a directory:

localeapp push config/locales/

Default Rails Translations

Locale will automatically add the standard rails translations when a project is created. If for some reason you don't want these, you can remove them using in the project libraries area on

Automatically sending missing translations

Missing translations are automatically sent only in the development environment by default. When a page is refreshed any missing translations will be sent to

If you want to disable sending missing translations in the development environment then edit config/initializers/localeapp.rb to include:

config.sending_environments = []

This is just an array, so you can configure it to match send in any environment you wish.

Manually create translations

You can create translations on the command line by running:

localeapp add en:"test content" es:"spanish content"

You must provide at least one translation and the locale code must already exist in the project.

Automatically pulling translations

There are two ways to do this, one that suits a single developer working the code locally and one where the translations are being pulled down to a staging (or live) server.

Single developer

In this mode the gem pulls any updated translations from at the beginning of each request. This is the default setting so you don't need to do anything special.

Staging server

In this mode you configure the individual listeners to not poll every request and instead run localeapp in daemon mode to fetch updated translations. This is useful when you have more than one listener and don't want them to race to update the translations.

Disabling polling

Edit config/initializers/localeapp.rb to include:

config.polling_environments = []

Run the daemon with:

localeapp daemon

The listeners will automatically reload translations when they see there are new ones. The daemon has two options:

-b will run in the background and put a pid file in tmp/pids/ -i X will change the polling interval to X from it's default five seconds.

Disabling Reloading

Automatic reloading is only enabled in the development environment by default and can be disabled in a similar way to polling and sending:

config.reloading_environments = []

Blacklisting keys and namespaces (Rails only)

To prevent certain missing translations from being sent to the Locale servers - in case of automatically generated keys from a gem for example - you can configure the blacklisted_keys_pattern option with a regular expression.

For example, to prevent all keys containing the word "simple_form" :

config.blacklisted_keys_pattern = /simple_form/


To prevent localeapp from sending translations every time they are missing, add this config setting:

config.cache_missing_translations = true

Inviting other developers and translators

You can invite other developers and translators via Developers have access to all the content and all the locales. Translators are restricted to editing only the locales you give them access too.

Adding a locale

If we find an unknown locale during an import we'll add it to your project. You can also add a new locale to a project via This will create missing translations for every translation key. You will need to restart any listeners completely to pick up the new locale.

Syck, Psych, and creating YAML

Since ruby 1.9.3-p0 Psych has been the default YAML engine in Ruby. Psych is based on libyaml and fixes a number of issues with the previous YAML library, Syck. uses 1.9.3 and Psych for all its YAML processing. The localeapp gem will use Psych if it is available but falls back to the ya2yaml library if not. ya2yaml supports UTF-8 (which Syck doesn't handle very well) but it does write YAML differently to Psych so you will notice differences between exporting directly from and doing localeapp pull on the command line unless you're using 1.9.3+ or have installed Psych as a gem.


If you need to go through a proxy server, you can configure it with:

config.proxy = ""

SSL Certificate verification uses https everywhere but certificate validation is turned off by default. This is because ruby doesn't know how to read the certs from the OSX keychain. You can turn verification on and tell the gem where the latest CA certificates are by adding:

config.ssl_verify = true
config.ssl_ca_file = /path/to/

See this article on Ruby Inside for some more details.

Support and feedback

You can contact us via the support link at the bottom of the page or emailing


See corresponding contributing guidelines.


Copyright (c) 2014 Locale and other contributors, released under the MIT License.

Something went wrong with that request. Please try again.