This is the first part of a four-part series on Globalizing your Mephisto application.

• Part 1 – Installation and usage for single site mephisto
• Part 2 – Deployment and production issues
• Part 3 – Installation and usage for multi site mephisto
• Part 4 – Using a path parameter to define the locale

In this article I hope to walk you through the successful installation of the mephisto_i18n plugin.

In the forthcoming article I’m going to cover getting your web server properly configured and other issues related to the plugin.

Background history

From the clients requirements, we knew that our latest project had to have a decent cms tool. Since we wanted to write this using rails, we searched around and after having looked at a few possibilities we settled on Mephisto.

However, one other important requirement was for the site to be available in multiple languages (at least spanish, catalan, english and french). We knew we had more or less just the one real option, the Globalize plugin.

So I set about to “Globalize” Mephisto.

Globalizing Mephisto

As Mephisto is still in beta (though currently it’s stable for production use) I didn’t want to modify mephsito code directly, rather I set about writing a rails plugin which would monkey patch mephisto to add globalize support.

I decided to use subdomains to indicate the current locale of the application, mostly because it was a lot easier. Otherwise, I’d have had to add in the locale extra parameter all over the place in mephisto code.

So I decided to setup a system where by:

example.com/ www.example.com => base locale is current
es.example.com => es (spanish) locale is current
fr.example.com => fr (french) locale is current

i.e. Several virtual hosts, each of which would have their own document roots:

RAILS_ROOT/public       => doc root for base locale
RAILS_ROOT/public/es    => doc root for es locale
RAILS_ROOT/public/fr    => doc root for fr locale

With the version of Globalize at that time being 1.1, the going was quite tough, mainly because of the select/include limitations enforced by Globalize’s external storage mechanism. As time went on it became progressively more and more difficult to override the mephisto code with the globalize limitations without touching the mephisto code itself (which was my aim).

The story now diverges to the creation of the Globalize internal storage mechanism which is nicely described here so I won’t go into any more detail, suffice to say that with this new way of storing translations, it suddenly became a lot easier to globalize the mephisto models and I quickly got to the point where all my tests were passing.

I then had to deal with things like caching & sweeping for multple doc roots, permalinks and other bits and pieces.

For our application, I then went on to create another couple of plugins to add in extra functionality specific to our application but for the needs of this article that’s enough history for now.

I’ve since cleaned up the plugin a lot, added in rake tasks to simplify the operation of migrating to the globalized system and integrated a number of extra features from our application specific code.

So let me take you through what’s necessary to migrate your mephisto installation to a fully internationalised Mephisto instance.

It just so happens, I want to do the same thing for my own personal blog so I’m going to walk you through what I did to get my own site migrated.

Migrating http://saimonmoore.net; step by step

So my current site is running a stock mephisto instance (Rev:2812).

Note: This plugin has only really been tested with Rails 1.2.x but there are changes in trunk (.e.g multiple controller view paths) that will simplify this plugin a bit but I haven’t got round to testing it with trunk yet.

Let’s go…

We start off by installing Globalize release for-1.2

Installing the Globalize plugin

Open up a shell and type:

$script/plugin install -x http://svn.globalize-rails.org/svn/globalize/branches/for-1.2
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test/unit
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test/view_picking_test.rb
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test/render_test.rb
...
Obtained revision: 91
(in /home/saimon/dev/projects/saimonmoore.net)
Globalize has not been setup yet. Generate a migration via script/generate globalize or run rake globalize:setup

Note that the globalize install has detected that the globalize project files haven’t been installed yet and suggests a couple of ways for you to get them in your db.

Before we setup the globalize tables I’m just going to rename the plugin to globalize as it was saved as for-1.2

$svn pe svn:externals vendor/plugins/
globalize http://svn.globalize-rails.org/svn/globalize/branches/for-1.2
$svn up
Obtaining external item in 'vendor/plugins/globalize'
A    vendor/plugins/globalize/test
A    vendor/plugins/globalize/test/unit
...
$rm -fR vendor/plugins/for-1.2
$svn ci vendor/plugins

Let’s check that globalize was installed properly. We should see the globalize rake tasks:

$rake -T | grep globalize
rake globalize:create_tables              # Create Globalize database tables
rake globalize:drop_tables                # Drops Globalize database tables
rake globalize:load_locale_data           # Load locale data
rake globalize:purge_locale_data          # Purge locale data
rake globalize:reset                      # Reset the Globalize data
rake globalize:setup                      # Create Globalize database tables and load locale data
rake globalize:teardown                   # Remove all globalizedata
rake globalize:test                       # Run tests
rake globalize:upgrade_schema_to_1_dot_2  # Upgrade to Globalize 1.2 schema

Looking good…

So let’s create and populate the globalize tables:

$rake globalize:setup
(in /home/saimon/dev/projects/saimonmoore.net)
NOTICE:  CREATE TABLE crear una secuencia implícita `globalize_countries_id_seq` para la columna serial `globalize_countries.id`
NOTICE:  CREATE TABLE / PRIMARY KEY crear el índice implícito `globalize_countries_pkey` para la tabla `globalize_countries`
NOTICE:  CREATE TABLE crear una secuencia implícita `globalize_translations_id_seq` para la columna serial `globalize_translations.id`
NOTICE:  CREATE TABLE / PRIMARY KEY crear el índice implícito `globalize_translations_pkey` para la tabla `globalize_translations`
NOTICE:  CREATE TABLE crear una secuencia implícita `globalize_languages_id_seq` para la columna serial `globalize_languages.id`
NOTICE:  CREATE TABLE / PRIMARY KEY crear el índice implícito `globalize_languages_pkey` para la tabla `globalize_languages`

I’m also going to update db/schema.rb:

$rake db:schema:dump

That’s globalize installed. On to the next step which is installing the mephisto_i18n plugin.

Installing the Mephisto_I18n plugin

$script/plugin install -x svn://rubyforge.org/var/svn/sidirodromos/plugins/mephisto_i18n/trunk
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/mephisto_i18n/test
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/mephisto_i18n/test/unit
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/mephisto_i18n/test/unit/asset_test.rb
...

The plugin install hook prints out the plugin’s INSTALL file for us so we can immediately see what the next steps are.

Before we continue let’s have a look at the rake tasks available to us:

$rake -T | grep 18
rake mephisto:i18n:bootstrap                      # Bootstrap translations / Bootstrap translations
rake mephisto:i18n:set_plugin_order               # Modify config.plugins order in environment.rb to add this plugin last
rake mephisto:i18n:ui:modify_mephisto_resources   # Modify mephisto resources as needed for i18n UI
rake mephisto:i18n:ui:rename_index_file           # Rename the public/index.html file
rake mephisto:i18n:ui:restore_index_file          # Restore the public/index.html file renamed by mephisto:i18n:ui:rename_index_file task
rake mephisto:i18n:ui:restore_mephisto_resources  # Restore the mephisto resources modified by mephisto:i18n:ui:modify_mephisto_resources task
rake mephisto:i18n:ui:setup                       # Setup resources for i18n plugin / Setup resources for i18n UI plugin
rake mephisto:i18n:ui:setup_subroots              # Create the subroots according to the currently supported locales
rake mephisto:i18n:ui:teardown                    # Undo changes caused by the mephisto::i18n:ui:setup task
rake mephisto:i18n:ui:teardown_subroots           # Remove the subroots created by mephisto:i18n:ui:setup_subroots task

As you can see there are quite a few tasks there to help out with the installation process.

Setting up your application for mephisto_i18n.

Well, we’ve already installed globalize and created it’s tables, so let’s continue the installation with the following step which is:

"Setup the plugin order in environment.rb".

$cat config/environment.rb | grep config.plugins
  # config.plugins= %W( exception_notification ssl_requirement )

$rake mephisto:i18n:set_plugin_order

$cat config/environment.rb | grep config.plugins
  config.plugins= %W(a_gems acts_as_paranoid acts_as_versioned attachment_fu dialog_helper filtered_column filtered_column_code_macro filtered_column_flickr_macro globalize labeled_form_helper liquid manage_fixtures mephisto mephisto_converters mocha permalink_fu request_routing simply_bdd simply_helpful white_list mephisto_i18n)

The “mephisto:i18n:set_plugin_order” task has modified the config/environment.rb file to ensure that the mephisto_i18n plugin is loaded after all the other plugins have loaded.

To do so it creates a list of the existing plugins in the plugins directory, sorts it and tags on the mephisto_i18n plugin at the end.

Don’t worry if you’ve already set the config.plugins option, the task will not delete your current plugin order, but rather check for the mephisto_i18n and tag it on at the end.

Warning: This task assumes you’re running mephisto trunk so it’s expecting the config.plugins property to be there (either commented or uncommented)

Next step according to the INSTALL document:

“Define your base locale and supported locales”

I want to support English, Spanish, Catalan and Greek in my blog, with English being the base locale.

So edit the config/environment.rb to look something like this:

$tail -n3 config/environment.rb
include Globalize
SupportedLocales.define(['gr-GR', 'es-ES', 'ca-ES'],'en-UK')

We’re now ready to globalize the mephisto tables which couldn’t be easier.

“Globalize the Mephisto tables”

Just run:

$script/runner 'Mephisto::Plugins::MephistoI18n.install'
./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:291:in `setup': Language for code: gr-GR doesn't exist! Check globalize tables. (RuntimeError)    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:289:in `collect'
from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:289:in `setup'
    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:68:in `initialize'
    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:44:in `new'
    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:44:in `define'
    from ./script/../config/../config/environment.rb:95
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `gem_original_require'
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `require'
    from /usr/lib/ruby/gems/1.8/gems/rails-1.2.2/lib/commands/runner.rb:39
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `gem_original_require'
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `require'
    from script/runner:3

Oops what happened there? Ah I see the problem. ‘gr’ is not a valid language code. The correct code is ‘el’ for greek. Quick fix and …

$tail -n3 config/environment.rb
include Globalize
SupportedLocales.define(['el-GR', 'es-ES', 'ca-ES'],'en-UK')

$script/runner 'Mephisto::Plugins::MephistoI18n.install'
Run 'script/runner -h' for help.

Hmm…. that didn’t work either. If you get this, this is just a typo in the INSTALL document which I’ve now corrected.

The correct command is:

$script/runner 'Mephisto::Plugins::I18n.install'
Adding globalize columns
-- add_column(:assets, "title_el", :string)
   -> 0.1035s
-- add_column(:contents, "title_el", :string)
   -> 0.0166s
-- add_column(:contents, "excerpt_el", :text)
   -> 0.0284s
-- add_column(:contents, "body_el", :text)
   -> 0.0164s
....

You can rollback these changes at any time via:

$script/runner 'Mephisto::Plugins::I18n.uninstall'
-- remove_column(:assets, "title_el")
   -> 0.3864s
-- remove_column(:contents, "title_el")
   -> 0.0209s
-- remove_column(:contents, "excerpt_el")
...

Let’s save these changes to the schema.rb file:

$rake db:schema:dump

Have a look at the db/schema.rb file to see the changes the plugin has made to the mephisto tables.

Finally, the last part of the installation has to do with setting up the different document roots for each of the virtual hosts (each representing one of the non-base locales).

“Setting up the Mephisto I18n resources”

Thankfully, another rake task sets this all up for us nicely:

I’m going to show you what changes the task makes by showing you before and after snapshots of certain directories:

$ls -la public/
total 33
drwxr-xr-x  8 saimon users  488 mar 19 13:26 .
drwxr-xr-x 15 saimon users  520 mar 19 16:19 ..
-rw-r--r--  1 saimon users  619 sep 11  2006 404.html
-rw-r--r--  1 saimon users  684 sep 11  2006 500.html
drwxr-xr-x  4 saimon users   96 mar 19 13:43 assets
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.cgi
-rwxr-xr-x  1 saimon users  859 jun 14  2006 dispatch.fcgi
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.rb
drwxr-xr-x  5 saimon users  120 nov  6 15:08 documents
-rw-r--r--  1 saimon users    0 dic 29  2005 favicon.ico
drwxr-xr-x  4 saimon users   96 oct 11 09:27 images
-rw-r--r--  1 saimon users 3325 nov  4 18:06 install.html
drwxr-xr-x  4 saimon users   96 oct 11 09:27 javascripts
-rw-r--r--  1 saimon users   99 dic 29  2005 robots.txt
-rw-r--r--  1 saimon users  631 nov  9 14:56 sitemap.txt
drwxr-xr-x  4 saimon users   96 oct 11 09:27 stylesheets
drwxr-xr-x  7 saimon users  296 mar 19 16:19 .svn

$rake mephisto:i18n:ui:setup

$ls -la public
total 33
drwxr-xr-x 11 saimon users  560 mar 19 16:54 .
drwxr-xr-x 15 saimon users  520 mar 19 16:19 ..
-rw-r--r--  1 saimon users  619 sep 11  2006 404.html
-rw-r--r--  1 saimon users  684 sep 11  2006 500.html
drwxr-xr-x  4 saimon users   96 mar 19 13:43 assets
drwxr-xr-x  2 saimon users  280 mar 19 16:54 ca
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.cgi
-rwxr-xr-x  1 saimon users  859 jun 14  2006 dispatch.fcgi
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.rb
drwxr-xr-x  5 saimon users  120 nov  6 15:08 documents
drwxr-xr-x  2 saimon users  280 mar 19 16:54 el
drwxr-xr-x  2 saimon users  280 mar 19 16:54 es
-rw-r--r--  1 saimon users    0 dic 29  2005 favicon.ico
drwxr-xr-x  4 saimon users   96 oct 11 09:27 images
-rw-r--r--  1 saimon users 3325 nov  4 18:06 install.html
drwxr-xr-x  4 saimon users   96 oct 11 09:27 javascripts
-rw-r--r--  1 saimon users   99 dic 29  2005 robots.txt
-rw-r--r--  1 saimon users  631 nov  9 14:56 sitemap.txt
drwxr-xr-x  4 saimon users   96 oct 11 09:27 stylesheets
drwxr-xr-x  7 saimon users  296 mar 19 16:19 .svn

$ls -la public/es/
total 1
drwxr-xr-x  2 saimon users 280 mar 19 16:54 .
drwxr-xr-x 11 saimon users 560 mar 19 16:54 ..
lrwxrwxrwx  1 saimon users  67 mar 19 16:54 404.html-> /home/saimon/dev/projects/saimonmoore.net/config/../public/404.html
lrwxrwxrwx  1 saimon users  67 mar 19 16:54 500.html-> /home/saimon/dev/projects/saimonmoore.net/config/../public/500.html
lrwxrwxrwx  1 saimon users  70 mar 19 16:54 favicon.ico-> /home/saimon/dev/projects/saimonmoore.net/config/../public/favicon.ico
lrwxrwxrwx  1 saimon users  65 mar 19 16:54 images-> /home/saimon/dev/projects/saimonmoore.net/config/../public/images
lrwxrwxrwx  1 saimon users  71 mar 19 16:54 install.html-> /home/saimon/dev/projects/saimonmoore.net/config/../public/install.html
lrwxrwxrwx  1 saimon users  70 mar 19 16:54 javascripts-> /home/saimon/dev/projects/saimonmoore.net/config/../public/javascripts
lrwxrwxrwx  1 saimon users  69 mar 19 16:54 robots.txt-> /home/saimon/dev/projects/saimonmoore.net/config/../public/robots.txt
lrwxrwxrwx  1 saimon users  70 mar 19 16:54 stylesheets-> /home/saimon/dev/projects/saimonmoore.net/config/../public/stylesheets

$ls -la app/views/layouts/
total 8
drwxr-xr-x  3 saimon users  192 mar 19 16:54 .
drwxr-xr-x 11 saimon users  320 mar 19 16:54 ..
-rw-r--r--  1 saimon users 3683 feb 19 14:52 application.original.rhtml
lrwxrwxrwx  1 saimon users  125 mar 19 16:54 application.rhtml-> /home/saimon/dev/projects/saimonmoore.net/config/../vendor/plugins/mephisto_i18n/tasks/../app/views/layouts/application.rhtml
-rw-r--r--  1 saimon users 1367 nov 22 16:07 simple.rhtml
drwxr-xr-x  7 saimon users  296 mar 19 16:19 .svn

$ls -la app/views
total 1
drwxr-xr-x 11 saimon users 320 mar 19 16:54 .
drwxr-xr-x 11 saimon users 272 mar 18 20:02 ..
drwxr-xr-x  3 saimon users 136 mar 18 20:02 account
drwxr-xr-x 19 saimon users 488 mar 18 20:07 admin
drwxr-xr-x  3 saimon users  72 mar 18 20:02 assets
drwxr-xr-x  3 saimon users  72 mar 18 20:02 comments
drwxr-xr-x  3 saimon users 168 mar 18 20:02 feed
lrwxrwxrwx  1 saimon users 104 mar 19 16:54 i18n-> /home/saimon/dev/projects/saimonmoore.net/config/../vendor/plugins/mephisto_i18n/tasks/../app/views/i18n
drwxr-xr-x  3 saimon users 192 mar 19 16:54 layouts
drwxr-xr-x  3 saimon users 168 mar 18 20:02 mephisto
drwxr-xr-x  7 saimon users 296 mar 19 16:19 .svn
drwxr-xr-x  3 saimon users 112 mar 18 20:02 user_mailer

As you can see it has made a few changes including:

• Creating three extra subdirectories in RAILS_ROOT/public, one for each non-base locale (Remember the base locale’s doc root is just RAILS_ROOT/public) and symlinked in common files from RAILS_ROOT/public.

• Overriding the admin layout template, symlinking it to one provided with the plugin. (The original is still there just in case)

• Adding an extra folder ‘i18n’ to the views directory (symlinked). This is for a custom controller that takes care of switching the current locale in the admin interface.

If you decide that you didn’t really want to install this plugin in the first place and you want to rollback all these changes then just run:

rake mephisto:i18n:ui:teardown

This will return your original files and directories to their rightfull places.

“Modify the session domain”

Finally, the last step in the INCLUDE document advises us to modify the ession_domain option in ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS so that when we switch between subdomains in the same session, the session doesn’t get lost.

$tail -n1 config/environments/development.rb
ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.update(:session_domain => '.saimonmoore.net')

$tail -n1 config/environments/production.rb
ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.update(:session_domain => '.saimonmoore.net')

Phew…that was quite a bit of work. Let’s see what this plugin has actually bought us.

The Final Result

We start up mongrel:

$ mongrel_rails start
 ** Starting Mongrel listening at 0.0.0.0:3000
 ** Starting Rails with development environment...
 ** Mongrel is serving static files.
 ** Rails loaded.
 ** Loading any Rails specific GemPlugins
 ** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
 ** Rails signals registered.  HUP => reload (without restart).  It might not work well.
 ** Mongrel available at 0.0.0.0:3000
 ** Use CTRL-C to stop.

Let’s go to the administration interface of our globalized mephisto application.

Note: I’ve temporarily redirected the .saimonmoore.net domain to localhost for testing purposes.

I’ve made a wink presentation out of this next part as I think it’s the quickest way to see what exactly you can do.

Click here to see the presentation.

Next week, I’ll conclude this two-part series with the second part where I’ll be talking about the production deployment issues that arise with this plugin.

[Update] I’ve just detected a slight problem with the symlinking in the mephisto:i18n:ui:setup rake task. It creates absolute symlinks which isn’t very handy for deployment. I’ll be fixing this asap.

[Update] This is now fixed so you’ll want at least revision 26 of the plugin

[Update] Currently there is a requirement to install the ‘unicode’ gem. I’m working to remove this dependency from the plugin.

Ready to deploy? Read *Part 2