HOWTO for Rails Engines

ruby-gettext-howto-engines

Rails Engines are supported by Ruby-GetText-Package since 1.8.0. It's similar with supporting Rails. So you can understand this HOWTO well if you learn Rails localization with GetText before.

Read Ruby-GetText-Package HOWTO for Ruby on Rails first.

LoginEngine plugin

In this tutorial, I explain to localize LoginEngine plugin.

So you need to set up Rails Engines and LoginEngine first.

LoginEngine has its own database tables. Ruby-GetText-Package extracts the field names of these tables. So you need to create your database and database.yml, too.

The directories:

{RAILS_ROOT}/config/database.yml
{RAILS_ROOT}/vendor/plugins/login_engine

Rakefile

Add a Rakefile to the top of plugin directory.

desc "Create mo-files for L10n"
task :makemo do
  require 'gettext/utils'
  GetText.create_mofiles(true, "po", "locale")
end

$: << "../../../"
desc "Update pot/po files to match new version."
task :updatepo do
  require 'gettext/utils'
  GetText::ActiveRecordParser.init(:db_yml => "../../../config/database.yml")
  GetText.update_pofiles("login_engine", 
                         Dir.glob("{app,lib}/**/*.{rb,rhtml}"),
                         "login_engine 1.x.x")
end

The directories becomes:

{RAILS_ROOT}/config/database.yml
{RAILS_ROOT}/vendor/plugins/login_engine
                            +Rakefile

Controllers/Views/Models/Helpers

Translate all Controllers/Views/Models/Helpers like as Rails applications.

Controllers

Like Rails, set init_gettext the top of controllers.

class UserController < ApplicationController
  init_gettext "login_engine"
  model   :user

  def home
     :
     :
     @fullname = _("Not logged in...")
     :
     :

Models

Nothing special. In the Login Engine, you don't need to translate some fields and is required the field which is not in the database. So use untranslate and N_() methods here.

class User < ActiveRecord::Base
  include LoginEngine::AuthenticatedUser

  untranslate :salt, :salted_password, :verified, :role, :security_token,
              :token_expiry, :created_at, :updated_at, :logged_in_at,
              :deleted, :delete_after

  N_("User|Password")
end

Views

Just same as Rails views.

Run the tasks

Next step is same as Rails, but in the plugin directory.

$ cd {RAILS_ROOT}/vendor/plugins/login_engine

To create po/login_engine.pot, run "updatepo" task.

$ rake updatepo

To create mo-files, run "makemo" task.

$ rake makemo

To update po/{lang}/blog.po, run "updatepo" task again.

$ rake updatepo

See HOWTO maintain po/mo files for more details.

Update SVN

Now the directory becomes like:

{RAILS_ROOT}/config/database.yml
{RAILS_ROOT}/vendor/plugins/login_engine
                           +app/controllers/user_controller.rb
                            +po/
                            +locale/
                            +Rakefile
                            +others

If you manage your plugin in SVN for installing it using script/plugin script, you need to import "locale" directory and all of mo-files into the repository. Because users(the application developers) don't run "rake makemo" when the plugin users download your plugin.

Sample files

Here is the localized UserEngine v1.0.2 with Japanese locale.

login_engine_v1.0.2.gettext.tar.gz

ChangeLog

2006-09-16 Added - Masao