Tech Blog

Localization is easy with Gettext and Ruby on Rails. In this tutorial I’m going to describe from top which steps are needed to install gettext in your Rails application. We shall start with an empty Rails application and add Gettext to it.

Step 1: Install gettext

sudo gem install gettext

Skip sudo if you are on Windows. The following dialog will popup.

Select which gem to install for your platform (i686-linux)
 1. gettext 1.10.0 (ruby)
 2. gettext 1.10.0 (mswin32)
 3. gettext 1.9.0 (mswin32)
 4. gettext 1.9.0 (ruby)
 5. Skip this gem
 6. Cancel installation

If you are on windows, choose the mswin32 version, else choose the latest ruby version. (note: you need to be able to compile stuff, on Ubuntu something like sudo apt-get install build-essential). Now the gettext Gem is installed.

Step 2: Create an empty Rails application

rails multilangual

This will create a new rails rails application called multilangual.

Step 3: Prepare your application for Gettext

3.1 Add the following task to Rails

Create a file called localization.rake in lib/tasks with the following code:

require 'gettext/utils'
desc "Create mo-files"
task :makemo do
 GetText.create_mofiles(true, "po", "locale")
end
 
desc "Update pot/po files to match new version."
task :updatepo do
 TEXT_DOMAIN = "myapp"
 APP_VERSION     = "myapp 1.1.0"
 GetText.update_pofiles(TEXT_DOMAIN,
                        Dir.glob("{app,lib}/**/*.{rb,rhtml}"),
                        APP_VERSION)
end

This code comes from the gettext tutorial on the Rails site.

3.2 Add the following code to your environments in multilangual/config/database.yml

encoding: UTF8

Add it to every environment you wish to use UTF8. Read more about it at:here.

3.3 The right directory structure

What we now need is a directory structure where we save our PO files. PO files are the language files that contain the strings that must be translated. For each language there will be a different PO file. After that PO files are converted to MO files(See Step 6), these files are the “compiled” translations.

So, we create a directory named po. In it we make a directory for each of your languages.

multilangual
-| po
—-| en_US
—-| nl
—-| de

Step 4: Prepare the application

4.1 Initialize gettext in the application

Open app/controllers/application.rb and make it to this

require 'gettext/rails'
class ApplicationController < ActionController::Base
 init_gettext "myapp"
end

4.2 Create a controller and a view

We create a DemoController with a corresponding index.

script/generate controller demo index

Edit this view to let it have a text that will be translated. So we edit app/views/demo/index.rhtml and give it following content:

< %=_("This text must be translated.") %>

Note that the _() syntax is a method that will automatically say to your application: "Hey im an translatable text, add me to your index of texts (the po files) that must be translated and after that: translate me(the mo files)!"

Step 5: Translate the application

Now we are ready to translate everything. Give the command:

rake updatepo

This will scrape your application and add every translatable texts to the po files in the po directory. At this moment we don't have a PO file, so only po/myapp.pot will be created. This is a template you can use for every language. Open it with a poeditor: I use POEdit. (for ubuntu: sudo apt-get install poedit). Then open po/myapp.pot in poedit:

poedit po/myapp.pot

Or just open poedit and open the file.

You now see the string we added in the index.rhtml. In the textarea at the bottom left, you can fill in your translation for that string. See the screenshot for the right area. I am now doing the dutch translation, thus I save the file as po/nl/myapp.po.

Step 6: Compile the translation

We now translated the application for one language, we could have done more, but we want to see it in action:

rake makemo

This will compile the translations to MO files, which are in a newly created directory: locale.

Step 7: See it in action

Start your server:

script/server

and go to see the text in it's original language:
http://localhost:3000/demo/

And now to see it in dutch:
http://localhost:3000/demo/?lang=nl

We translated the application!

Step 8: Modify the app

Now you want to add some more text or modify something. Modify it: just do

rake updatepo

again. This will update all of your po files. Edit them with POEdit. Do:

rake makemo

again. And there the modifications are!

In a next tutorial I will explain some more advanced Gettext issues, like mailers and choosing the right language on every request. Stay tuned!