Localisation (i18n) in Rails with localeUI

Multilingual support is no longer a niche feature — it is standard in many projects. Whether you are building a SaaS product, an internal platform, or a public website, internationalisation becomes essential as soon as you address different audiences. 

The good news: Ruby on Rails already provides everything we need with its built-in I18n system. And when your project grows or multiple people work on translations, localeUI makes management much easier.

In this article, we’ll build a new Rails app step by step, configure English and German (with English as the default), create a translated “Hello World” page with URL-based language switching, and then connect localeUI.

Create a new Rails app

We start by creating a new Rails app with the console command:

Command line
rails new rails_localeui_demo
cd rails_localeui_demo

With the rails new command, Ruby on Rails automatically generates a complete project structure for a new application. This includes the typical MVC folders such as app/models, app/controllers, and app/views. Rails also creates important configuration files in the config folder, prepares database configuration, and generates a Gemfile where project dependencies are defined. In addition, a default test setup is created so testing is integrated from the start.

After starting it with: 

Command line
rails server

the application is available in your browser at http://localhost:3000.

Configure I18n in Rails

Rails already includes the I18n system. By default, however, only English is enabled. We also want to add German and set English as the default language.

To do this, open config/application.rb. Inside the application class, add the following configuration:

Rubyconfig/application.rb
... 

module RailsLocaleuiDemo
  class Application < Rails::Application
    ... 

    config.i18n.available_locales = [:en, :de]
    config.i18n.default_locale = :en
    config.i18n.fallbacks = true

    ...
  end
end

These settings define the basic language configuration of your application. available_locales specifies which languages are officially supported. default_locale defines the language used when no locale is provided. The option fallbacks = true tells Rails to use the default language whenever a translation is missing. This completes the basic multilingual setup.

Create translation files

All translations in Rails are stored in YAML files. YAML is easy to read and supports hierarchical structures. Each language gets one or more dedicated files. In the config/locales folder, create two files.

YAMLconfig/locales/en.yml
en:
  hello_world: "Hello World"
  language:
    english: "English"
    german: "German"

YAMLconfig/locales/de.yml
de:
  hello_world: "Hallo Welt"
  language:
    english: "Englisch"
    german: "Deutsch"

The top level (en: or de:) defines the language. Below that are the translation keys themselves. These keys are the references we use later in code. It is important to keep the same structure in both files so all texts are available in every language.

Create a Hello World page

To view the translations on a page in the app, we now create a simple home page.

Command line
rails generate controller Home index

This generator creates several core parts of the application: the controller app/controllers/home_controller.rb, where application logic is implemented, and the view app/views/home/index.html.erb, which contains the page markup. It also adds a route entry so the page is reachable by URL. Rails additionally generates test and helper files to support development and maintenance.

Then open app/views/home/index.html.erb and add:

ERBapp/views/home/index.html.erb
<h1><%= t('hello_world') %></h1>

<p>
  <%= link_to t('language.english'), locale: :en %>
  <%= link_to t('language.german'), locale: :de %>
</p>

The t helper returns the translation for the currently active language. Internally, Rails uses I18n.t.

Set up language selection via URL

Now we want to implement language selection via URL. We have already created links for English and German in the view. However, these do not yet have the final URL.

To enable this, we want routes like /en and /de. In config/routes.rb, update the routes as follows:

Rubyconfig/routes.rb
Rails.application.routes.draw do
  scope "(:locale)", locale: /en/de/ do
    root "home#index"
  end
end

The scope allows an optional locale parameter in the URL. The regular expression ensures that only en or de are valid values.

Next, we need to tell Rails how to handle this parameter. Open app/controllers/application_controller.rb and add:

Rubyapp/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_locale

  private

  def set_locale
    I18n.locale = params[:locale] || I18n.default_locale
  end

  def default_url_options
    { locale: I18n.locale}
  end
end

set_locale runs before each request and sets the current language from the URL parameter. default_url_options ensures generated links automatically include the current locale.

Now restart the server with rails server and open http://127.0.0.1:3000/en. You should see “Hello World”. Open http://127.0.0.1:3000/de and you should see “Hallo Welt”.

Set up localeUI

Up to this point we have managed our translations directly in YAML files within the Rails application. This is completely sufficient for small projects. However, as the application grows, this procedure quickly becomes confusing. At the latest when several developers, product managers or translators have to work on the texts, a problem arises: changes have to be maintained manually in YAML files, Git merges become more complicated and non-technical people do not have easy access to the content.

This is exactly where localeUI helps. The platform provides centralised translation management. Instead of editing text directly in code, content is maintained in a web interface and then synchronised automatically with your application.

The first step is to create an account with localeUI. After registering and logging in, a new project can be created. A project usually corresponds to an application or a service. Instructions on how to do this can be found in the localeUI documentation under: Get Started.

When creating a project, the first step is to define the default language. In our example, we choose English because it is also the default language of our Rails app. You can then add additional languages, such as German.

Once the project is created, localeUI provides the required API credentials: usually an API key for authentication and a project ID to uniquely identify the project. You will store both values in your Rails app so it can connect to localeUI and synchronise translations. The API key restricts access to authorised applications, while the project ID defines where translation data is stored and managed.

Translations can then be managed, changed, or extended through the localeUI web interface. The big advantage is that people without source-code access can edit texts, while developers continue syncing through local files.

Detailed information about the steps can be found in the linked pages to this article.

Integrate localeUI into the Rails app

After the project is set up on localeUI, we need to connect our Rails application to this platform. For this purpose, localeUI provides its own Ruby gem that can be integrated directly into Rails.

First, open the Gemfile in your project and add the gem:

RubyGemfile
gem "localeui"

In Rails, the Gemfile is where additional libraries are declared. After adding the gem, install it with Bundler so it becomes available to the application.

The installation is done with:

Command line
bundle install

This command downloads the gem from the RubyGems repository and installs all the required dependencies. At the same time, new Rails tasks from the gem will also become available, which will later be used to synchronise the translations.

The next step is to run the gem's installation generator:

Command line
rails generate localeui:install

Generators are a typical Rails concept. They automatically generate files or configurations that are required for a specific feature. In this case, the generator creates a configuration file for localeUI.

After running the command, you will find a new file, config/initializers/localeui.yml, in the config folder. This file contains the gem configuration. Add your authentication and project identification credentials there.

Rubyconfig/initializers/localeui.rb
Localeui.config do |config|
  ...

  # Authentication Token
  config.api_token = 'YOUR API KEY'

  # Project API ID
  config.project_id = 'YOUR PROJECT ID'

  ...
end

The API key is used for authentication. The project ID tells localeUI which project should be synchronised with your application.

This sets up the technical connection between Rails and localeUI. This can be tested with the following command.

Command line
rails localeui:project_info

Once the connection has been successfully established, information about the project will be displayed in the console. This completes the integration, and the synchronisation of the translations can begin.

First synchronisation

After the integration is complete, the existing translations from your Rails application need to be uploaded to localeUI for the first time. Your current YAML files already contain keys such as hello_world and language.english. These should now be imported into your localeUI project.

To transfer the translations we use the command provided by the gem: 

Command line
rails localeui:upload

This command uploads the YAML files from the config/locales folder to your localeUI project. localeUI then processes the files automatically and reads all included translation keys. Detected keys are created in the project and become available immediately in the web interface. From that point on, translations can be maintained or extended in localeUI without manually editing YAML files.

After making changes in the localeUI web interface—for example, adding new translations or updating existing ones—you can pull them back into your Rails application with:

Command line
rails localeui:download

This command fetches the current translation files via the localeUI API and writes the YAML files back to the config/locales folder. This keeps your application files in sync with the localeUI project without manually copying or maintaining translations in multiple places.

Conclusion

Clean internationalisation can be implemented in Rails with just a few configuration steps. The integrated I18n system is flexible, clearly structured and easily expandable. URL-based language switching ensures transparent and SEO-friendly routes.

The additional integration of localeUI creates a professional solution for larger projects in which translations are managed centrally and maintained by multiple participants.

The combination of Rails-I18n and a specialised localisation platform provides a solid foundation for multilingual applications of any size.