LokaliseRails

This gem provides Lokalise integration for Ruby on Rails and allows to exchange translation files easily. It relies on ruby-lokalise-api to send APIv2 requests.

If you would like to know how this gem was built, check out the {“How to create a Ruby gem” series at Lokalise blog}[https://lokalise.com/blog/create-a-ruby-gem-basics/].

Getting started

Requirements

This gem requires Ruby 2.5+ and Rails 5.1+. It might work with older versions of Rails though. You will also need to setup a Lokalise account and create a translation project. Finally, you will need to generate a read/write API token at your Lokalise profile.

Installation

Add the gem to your Gemfile:

gem 'lokalise_rails'

and run:

bundle install
rails g lokalise_rails:install

The latter command will generate a new config file config/lokalise_rails.rb looking like this:

require 'lokalise_rails'

LokaliseRails.config do |c|
  c.api_token = ENV['LOKALISE_API_TOKEN']
  c.project_id = ENV['LOKALISE_PROJECT_ID']

  # ...other options
end

You have to provide api_token and project_id to proceed. project_id can be found in your Lokalise project settings.

Other options can be customized as well (see below) but they have sensible defaults.

Importing translations from Lokalise

To import translations from the specified Lokalise project to your Rails app, run the following command:

rails lokalise_rails:import

Please note that any duplicating files inside the locales directory (or any other directory that you've specified in the options) will be overwritten! You may enable safe mode to check whether the folder is empty or not.

Exporting translations to Lokalise

To export translations from your Rails app to the specified Lokalise project, run the following command:

rails lokalise_rails:export

Running tasks programmatically

You can also run the import and export tasks from the Rails app:

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

# Import the files:
result = LokaliseRails::TaskDefinition::Importer.import!

result contains a boolean value with the result of the operation

# Export the files:
processes = LokaliseRails::TaskDefinition::Exporter.export!

processes contains a list of queued background processes.

Configuration

Options are specified in the config/lokalise_rails.rb file.

Global settings

Import settings

{
  format: 'yaml',
  placeholder_format: :icu,
  yaml_include_root: true,
  original_filenames: true,
  directory_prefix: '',
  indentation: '2sp'
}

Full list of available import options can be found in the official API documentation. * import_safe_mode (boolean) - default to false. When this option is enabled, the import task will check whether the directory set with locales_path is empty or not. If it is not empty, you will be prompted to continue. * max_retries_import (integer) - this option is introduced to properly handle Lokalise API rate limiting. If the HTTP status code 429 (too many requests) has been received, LokaliseRails will apply an exponential backoff mechanism with a very simple formula: 2 ** retries. If the maximum number of retries has been reached, a Lokalise::Error::TooManyRequests exception will be raised and the export operation will be halted.

Export settings

en_US:
  my_key: "my value"

Please note that if your Lokalise project does not have a language with the specified lang_iso code, the export will fail.

c.skip_file_export = ->(file) { f.split[1].to_s.include?('fr') }

Settings to work with formats other than YAML

If your translation files are not in YAML format, you will need to adjust the following options:

Running tests

  1. Copypaste .env.example file as .env. Put your Lokalise API token and project ID inside. The .env file is excluded from version control so your data is safe. All in all, we use pre-recorded VCR cassettes, so the actual API requests won’t be sent. However, providing at least some values is required.

  2. Run rspec .. Observe test results and code coverage.

License

Copyright © Lokalise team, Ilya Bodrov. License type is MIT.