Ruby on Rails

Localizing with RoR's built-in i18n support

Ilya Krukowski avatar
Written by Ilya Krukowski
Updated over a week ago

You might be also interested in our library for plain Ruby.

A sample app built with Rails can be found on Developer Hub.

Lokalise can be used with Ruby on Rails apps.


Once your app is prepared for localization, it should contain a locales directory with translation files, for example myapp/config/locales/en.yml.

Using the lokalise_rails gem

Before proceeding, add the lokalise_rails gem into your Gemfile:

gem 'lokalise_rails'

Then run:

bundle install
rails g lokalise_rails:install

Next, open the config file config/lokalise_rails.rb. Provide API token and project ID inside:

require 'lokalise_rails'

LokaliseRails::GlobalConfig.config do |c|
c.api_token = ENV['LOKALISE_API_TOKEN']
c.project_id = ENV['LOKALISE_PROJECT_ID']
# ...other options

Import and export options have sensible defaults but you may adjust them further as needed.

Uploading to Lokalise

Run the following Rake task:

rails lokalise_rails:export

Your translation files will be uploaded to the specified Lokalise project.

Use the following code to perform export programmatically:

require "#{Rails.root}/config/lokalise_rails.rb"

processes = LokaliseRails::TaskDefinition::Exporter.export!

processes contains a list of queued background processes.

Downloading from Lokalise

Run the following Rake task:

rails lokalise_rails:import

Translations will be downloaded to your Rails project. Filenames information will be preserved as well.

To perform import programmatically:

require "#{Rails.root}/config/lokalise_rails.rb"

result = LokaliseRails::TaskDefinition::Importer.import!

result contains a boolean value.

Using the CLI tool

Install Lokalise CLI tool before proceeding.

Uploading to Lokalise

Upload your translation file to Lokalise:

$ lokalise2 \
 --token <token> \
 --project-id <project_id> \
 file upload \
 --file "myapp/config/locales/en.yml" \
 --lang-iso en

Downloading from Lokalise

Once the translations are completed you'll need to download the language files from Lokalise:

$ lokalise2 \
 --token <token> \
 --project-id <project_id> \
 file download \
 --format yaml \
 --original-filenames=false \
 --bundle-structure "%LANG_ISO%.yml" \
 --unzip-to "myapp/config/locales/"
Did this answer your question?