Globalize » Home

Home

2008-06-25T00:37:40+02:00

Globalize for Rails 1.2 released!

The Globalize’s developer team is happy to annouce the official release of Globalize for Rails 1.2

Besides being compatible with the latest shiny & jaw-dropping Ruby on Rails 1.2 release this Globalize release adds two new major features:

alternative way of storing ModelTranslations in the model table
namespaced ViewTranslations

For a smooth upgrade please note that a minor change to the database schema is required.

NOTE: If you install the plugin via script/plugin install, then your schema will be automatically updated (default rails environment).

You can also accomplish this by running the included Rake task:

rake globalize:upgrade_schema_to_1_dot_2

(This in fact doesn’t do anything more than add a string column ‘namespace’ to the table globalize_translations, so you could do that manually, too.)

Posted on 01 Mar 2007

Overview for busy people

Globalize implements three basic types of translation:

Dates, currencies, etc: language dependent, but also (often) country/locale dependent. This feature provides convenient methods for relevant data types. 12345.67.localize → 12.345,67
Content in the database, for specific fields in specific tables: once the translates method is added to the relevant model, the fields indicated with that method call gain the ability to have translated content sitting in the database. An operator (possibly the developer) will need to add these translated texts.
Arbitrary strings: any string that you would like, with added flexiblity for including parameters (for example: ‘one’ in the singular form of a phrase and an actual number for the plural form)

Using these three mechanisms, all user-facing content ought to be translatable.

For a quick overview of Globalize usage see: How to use. For more walkthroughs, articles and howtos see: Documentation

Screencast(s)

We’d like to publish a screencast here – or better yet, a short screencast for each of several aspects of using Globalize.

If you’re volunteering for this, please contact us.

Features

2008-06-25T00:38:15+02:00

Translation

Supports translation of views and db content.
Supports pluralization, even in languages with multiple plural forms like Polish, via the String division method (’/’).
Automatic routing to locale-specific templates (e.g. show.es-ES.rhtml).
Automatically chooses locale-specific ActionMailer template.

Easy to Use

It’s transparent: You’ll mostly just use Locale.set, "string".t, and translates :field. The rest is automatic.
All translation and localization data is in three database tables: globalize_countries, globalize_languages, and globalize_translations.
Comes with a free Currency class, especially designed for Rails. Prints out numbers correctly for each locale, and supports currency formatting (¥2300.00, 23 000,00 kr). Values are stored internally and in the database as integers, for maximum precision.

Built-in Data

Comprehensive list of 7599 languages and 239 countries, with pluralization rules, native language names (Spanish is Español) and number formatting.
Supplies Time#localize and Date#localize to print out times and dates in strftime format in 92 languages. Other languages can be added by simply supplying translations.

Efficiency

Efficient querying for db translations. One DB call loads models and translations for current language.
Additionally, there’s a piggyback feature for associations. So, Product.find(:all, :include_translated => :manufacturer) is one DB call, but gives you product.manufacturer_name in your current language.
Caches view translations to cut down on db queries.

Databases

Supports PostgreSQL, MySQL and Sqlite3

And, it’s ridiculously easy to add to your app.

Comparison to others

Globalize is generally said to be the most powerful all-in-one solution for Internationalization of Ruby on Rails applications.

(more to come soon … until then please refer to the comparison on the Rails wiki.)

Getting started

2008-06-25T00:38:39+02:00

Get Globalize!

Generally we recommend using the Rails plugin install script via Subversion:

script/plugin install http://svn.globalize-rails.org/svn/globalize/branches/for-1.2 (this is for Rails 1.2)
script/plugin install http://svn.globalize-rails.org/svn/globalize/branches/for-1.1 (this is for Rails 1.1)
script/plugin install http://svn.globalize-rails.org/svn/globalize/trunk (this is edge Globalize)

If you have problems with Subversions, e.g. because you’re behind a restrictive firewall, you might want to use the tar files:

How to install

From your rails app root directory:

script/plugin install svn://svn.globalize-rails.org/globalize/branches/for-1.1
rake globalize:setup

...and you’re globalized, dude!

Also, you might want to:

Get edge Globalize instead of stable: svn://svn.globalize-rails.org/globalize/trunk
Add include Globalize to your environment.rb file, so that you won’t have to type Globalize::Locale.set all the time. Instead, you can just type Locale.set.
Add Language and Country fixtures if your code references any models provided Globalize. Look in vendor/plugins/globalize/test/fixtures for a template.

Optionally, try:

rake globalize:test
globalize plugin testing has it’s own database.yml file, so make sure to configure it before running the tests. it’s found in the directory RAILS_ROOT/vendor/plugins/globalize/test/config
rake doc:plugins
This creates HTML documentation in the RAILS_ROOT/doc/plugins/globalize directory.

Get started

There are several walkthrough- or howto-style articles available, each taking a different approach. We don’t garantuee for the freshness of the presented information though.

Sven’s Globalize Writeup – has sometimes been refered to as “the best documentation available for Globalize”
Example Application – takes you step by step through the process of creating a Globalized example application
Unit-tested Example – a walkthrough using a test-driven approach by Josh Harvey

Also relevant:

The Internal Storage Mechanism For Globalize for Rails Model Translations – Saimon’s comprehensive intro and overview to Globalize’s alternative model translations storage mechanism

Find more howtos, tutorials and articles in the documentation section

Also, be sure to subscribe to our mailing list and check out our documentation

Documentation

2008-06-25T00:38:57+02:00

Frequently Asked Questions

You can find our FAQ here.

API Docs

Our API docs are here (currently not up to date though, sorry)

Howtos

There are several walkthrough- or howto-style articles available, each taking a different approach. We don’t guarantee the freshness of the presented information though.

Sven’s Globalize Writeup – has sometimes been refered to as “the best documentation available for Globalize”
Example Application – takes you step by step through the process of creating a Globalized example application
Unit-tested Example – a walkthrough using a test-driven approach

Overviews

Jeremy Voorhis’ Canada on Rails slides – a presentation’s slides, cool for a short overview [pdf]

Recipes

HowTo: recipes – some tips, tricks and recipes
The Internal Storage Mechanism For Globalize for Rails Model Translations – Saimon’s comprehensive intro and overview to Globalize’s alternative model translations storage mechanism
Making migrating to Globalize’s internal storage mechanism easy – when you’re already using the default storage method for model translations: how do you migrate to the alternative mechanism easily?
Namespaced View Translations – Saimon’s intro to namespacing viewtranslations with Globalize

Troubleshooting

Troubleshooting – some things that might go wrong and what to do about them

Internals

How Globalize works – explanation of the database tables (partly dated and incomplete)

Community

2008-06-25T00:39:23+02:00

Mailinglist

Our mailing list is the best place to ask questions and get support, give feedback, point us to problems or generally have some fun ;-)

To join the mailinglist send a message to users-subscribe@list.globalize-rails.org. You will get a confirmation message before you join. To unsubscribe, send a message to users-unsubscribe@list.globalize-rails.org from the address you have subscribed with.

And yes, our mailing list is archived. You can find the archive at http://www.nabble.com/Globalize-rails.org-f17045.html

Issue tracker

You can use our issue tracker to report bugs, check for existing issues, recent developments and browse the Subversion source code repository.

Team & Acknowledgements

Globalize has intially been build by Josh Harvey but since the developer team has expanded. You can find out more about the dev core team and Globalize’s history here

Who’s using it?

You can find some projects that use Globalize here: Globalize powered sites

Example application

2008-06-25T00:39:53+02:00

NOTE
If you want the latest API reference for globalize plugin, run rake doc:plugins to generate rdoc documentation. You can find it later in app/doc/plugins/globalize directory.

NOTE
You need to apply some changes below to make it work with Oracle.

2. Creating rails application

Firstly create a very simple rails app (just one table) to work with.

rails globalize

This should create a skeleton of your application.

Now you need to create a database to work with, i.e. “globalize_development” and configure config/database.yml file correctly.

Next create the only model:

script/generate model Product

This will create also a migrate file db/migrate/001_create_products.rb, which you can use to create products table.


class CreateProducts < ActiveRecord::Migration
  def self.up
    create_table :products do |t|
      t.column :name, :string
      t.column :company, :string
      t.column :description, :text
      t.column :price, :integer, :default => 0
      t.column :created_on, :date
      t.column :updated_on, :date
    end
  end
  def self.down
    drop_table :products
  end
end

Run

rake migrate

and if there were no errors you should have new products table in your database.

Now you can add some functionality to your app:


script/generate scaffold admin/product
script/generate controller product

The first line will generate the whole admin panel for your products table and the second one will add a controller, which will be used by “user” part of the app.

Now it’s time for some cosmetic changes:

remove created_on and updated_on input elements from app/views/admin/products/_form.rhtml partial – you don’t need them as they these fields are updated automatically
copy index, list and show actions from app/controllers/admin/products_controller.rb to app/controllers/product_controller.rb
copy list.rhtml and show.rhtml files from app/views/admin/products/ to app/views/product/
remove edit, destroy and new functionality from list.rhtml and show.rhtml files you’ve just copied
delete or rename public/index.html
add layouts for admin and user parts

Next add routing rules for user and admin parts. Add these 2 lines to your config/routes.rb file:


# You can have the root of your site routed by hooking up '' 
# -- just remember to delete public/index.html.
map.connect '', :controller => 'product', :action => 'index'
map.connect 'admin', :controller => 'admin/products', :action => 'index'

Now you’ve got your own basic rails app with full CRUD functionality for admin and read functionality for user.

3. Installing globalize plugin

To install the plugin just type:
script/plugin install svn://svn.globalize-rails.org/globalize/branches/for-1.1

Now go to vendor/plugins and rename for-1.1 directory to globalize.

Now run:

rake globalize:setup

and you’ve just finished installing globalize!

NOTE
You can run rake -T to see all available rake tasks – including these added by globalize.

WARNING
In current revision (197) there’s a problem with built_in column in globalize_translation table, which causes all translations added by the user to be marked as built in.
I’m not sure if it’s just problem with my configuration, but to check if you also have this problem, type this in the console:


include Globalize
Locale.set "en-US" 
Locale.set_translation("foo", "bar")
ViewTranslation.find(:first, :conditions => "tr_key = 'foo'").built_in?

If you get false, then your translation is not being set as built-in and everything is ok.
If not, close the console and open the file vendor/plugins/globalize/tasks/data.rake and change line #63:
t.column :built_in, :boolean, :default => true
to
t.column :built_in, :boolean#, :default => true
Now run


rake globalize:teardown
rake globalize:setup

Open the console and set all fields in globalize_translation table as built_in


include Globalize
ViewTranslation.update_all "built_in = true"

Now it should work correctly: all translations that already exist in the table should be marked as built-in and all new translations added by you won’t be anymore.
Note that due to the unorthodox way Globalize handles the database (without migrations), this change won’t be reflected in schema.rb.

4. Making your application globalized

4.1 Configuration

First you need to set the base language. Add these lines to config/environment.rb file:


# Include your application configuration below
include Globalize
Locale.set_base_language 'en-US'
LOCALES = {'pl' => 'pl-PL',
           'en' => 'en-US',
           'es' => 'es-ES',
           'fr' => 'fr-FR'}.freeze

Of course you can select any language as your base language. In LOCALES hash we will store all available locales for this app. Remember to restart the server after you made changes in environment.rb file.

NOTE
It’s important to never change the base language once you’ve started populating the database.

You can pass the information about the language, which should be displayed, in the session variable or in the url. Here just the second method is presented, as it allows you i.e. to bookmark the page in selected language etc.

Now you need to modify your config/routes.rb file a bit. Add this line before the lines you added before:


map.connect ':locale/:controller/:action/:id'

You also need to set the current language somewhere. Edit your app/controllers/application.rb file:


class ApplicationController < ActionController::Base
  before_filter :set_locale
  def set_locale
    if !params[:locale].nil? && LOCALES.keys.include?(params[:locale])
      Locale.set LOCALES[params[:locale]]
    else
      redirect_to params.merge( 'locale' => Locale.base_language.code )
    end
  end
end

Try to display your main page again – you should see “en” in the url before the controller name.

Now just add possibility to switch between languages and move to the next chapter.

To switch between languages you can use i.e. following link:


<%= link_to "pl", {:controller => controller.controller_name, :action => controller.action_name, :locale => 'pl', :id => params[:id]} %>

This will display current page in selected language, but it will only work with the default route.

NOTE
You could iterate through LOCALE hash to create a link for every supported language or create select input field.

NOTE by Marc-André Lafortune
I prefer to use the preferences set in the user’s client to determine the default locale. The user can then decide to override it by clicking on a button you provide, in which case I want to store that in a cookie so that preference is remembered forever. Here’s my filter:


# Will set the cookie 'locale' if (and only if) an explicit parameter 'locale'
# is passed (and is acceptable)
# If no cookie exists, we look through the list of desired languages for the
# first one we can accept.
#  
  def set_locale
    accept_locales = LOCALES.keys # change this line as needed, must be an array of strings
    cookies[:locale] = params[:locale] if accept_locales.include?(params[:locale])
    Locale.set(cookies[:locale] || (request.env["HTTP_ACCEPT_LANGUAGE"] || "").scan(/[^,;]+/).find{|l| accept_locales.include?(l)})
  end

4.2 Translating static content.

First you need to generate translate controller.


script/generate controller admin/translate

Now edit your new controller:


class Admin::TranslateController < ApplicationController
  def index    
    @view_translations = ViewTranslation.find(:all, :conditions => [ 'built_in IS NULL AND language_id = ?', Locale.language.id ], :order => 'text')
  end
  def translation_text
    @translation = ViewTranslation.find(params[:id])
    render :text => @translation.text || ""  
  end
  def set_translation_text
    @translation = ViewTranslation.find(params[:id])
    previous = @translation.text
    @translation.text = params[:value]
    @translation.text = previous unless @translation.save
    render :partial => "translation_text", :object => @translation.text  
  end
end

Let’s focus on the index action. We fetch all non-built-in translations for current locale and order them by text column. This will put all untranslated fields at the beginning of @view_translation array.
You can change the conditions i.e.:


  def index
    @view_translations = ViewTranslation.find(:all, 
      :conditions => [ 'text IS NULL AND language_id = ?', Locale.language.id ], :order => 'tr_key')
  end

This way you’ll get untranslated fields only.
Remember to set admin layout for this controller.

Now create app/views/admin/translate/_translation_text.rhtml partial, which is used in translation_text action.


<%= translation_text || '[no translation]' %>

To translate the static content you can use in_place_editor helper, which is built-in in Rails 1.1. Just remember to add


<%= javascript_include_tag :defaults %>

in the layout file for the admin part (e.g. create an application-wide app/views/layouts/application.rhtml layout – you can copy most of the generated products.rhtml layout there, just change the title and add the javascript tag).

Next create app/views/admin/translate/_translation_form.rhtml partial for the form, which will be used to provide translations.


<!--[form:translate]-->
<p>
<label for="tr_<%= tr.id %>"><%=tr.tr_key%></label>
<br />
<span id="tr_<%= tr.id %>">
<%= render :partial => 'translation_text', :object => tr.text %>
</span>
<%= in_place_editor "tr_#{tr.id}", 
    :url => { :action => :set_translation_text, :id => tr.id },
    :load_text_url => url_for({ :action => :translation_text, :id => tr.id })%>
</p>
<!--[eoform:translate]-->

NOTE
If you want more information about in_place_editor helper look here.

In the next step we will use 2 useful helpers. Add the following code to app/helpers/application_helper.rb file:


  def base_language_only
    yield if Locale.base?
  end
  def not_base_language
    yield unless Locale.base?
  end

NOTE
These helpers come from Jeremy Voorhis’ Canada on Rails slides, which you can find here.

Still in app/views/admin/translate, create index.rhtml and edit it:


<% base_language_only do -%>
<div id="language"><h1>Please choose language for translation</h1></div>
<% end -%>
<% not_base_language do -%>
<div id="language"><h1><%= "Language: " + Locale.language.native_name %></h1></div>
<div>
<% @view_translations.each do |tr| -%>
  <%= render :partial => 'translation_form', :locals => {:tr => tr}%>
<% end -%>
</div>
<% end  -%>

We don’t want to translate english strings to english again, so the translation forms will only be displayed if current language is different than the base one.

Add a new product if you haven’t done this already – go to localhost:3000/admin/, press ‘New product’ and fill out the form.

Open app/views/product/list.rhtml and show.rhtml and add .t method to all strings you want to translate i.e. change 'Show' to 'Show'.t etc. This way you’ll get translated user part of the application.

To add these strings to the database they must be displayed first, so go to localhost:3000/pl/product. Next go to localhost:3000/pl/admin/translate. You should see the list of strings to which you’ve added .t method. Translate them and go to localhost:3000/pl/product again.

NOTE
If you don’t get any strings on localhost:3000/pl/admin/translate page to translate, make sure that:

you’re not displaying that page with the base locale
you added .t method to the strings
you displayed pages, to which you added .t method

NOTE
Here’s useful thread showing how to add untranslated strings automatically: http://rubyforge.org/pipermail/railsi18n-discussion/2006-August/000124.html

4.3 Translating model data.

First you need to decide which fields you want to translate. In our Product model we’ll translate name and description fields.

Add this line to app/models/product.rb:


translates :name, :description

We will allow adding new products only for the base language. Modify app/views/admin/products/list.rhtml file:


<% base_language_only do -%>
<%= link_to 'New product', :action => 'new' %>
<% end -%>

In the same directory create new file _translation_form.rhtml. Copy contents of _form.rhtml partial to this new file, but remove company and price input fields as they won’t be translated. As you may have already figured out this form will be used to provide translations for the Product model.

Now create another file _translation_data.rhtml and put the following code inside:


<div>
  <b>Name:</b> <%=h @product.name %>
  <b>Description:</b> <%=h @product.description %>
</div>

This file will be used as the reference and will show data in the base language.

Now it’s time to modify edit.rhtml file.


<h1>Editing product</h1>
<% base_language_only do -%>
  <%= start_form_tag :action => 'update', :id => @product %>
    <%= render :partial => 'form' %>
    <%= submit_tag 'Edit' %>
  <%= end_form_tag %>
<% end -%>
<% not_base_language do -%>
<div style="float:left;">
  <h2><%= Locale.language.native_name%></h2>
  <%= start_form_tag( {:action => 'update', :id => @product} ) %>
    <%= render :partial => 'translation_form' %>
    <%= submit_tag 'save translation' %>
  <%= end_form_tag %>
</div>
<div style="float:right;">
  <% @product.switch_language(Locale.base_language.code) do -%>
    <h2><%= Locale.base_language.native_name%></h2>
    <%= render :partial => 'translation_data' %>
  <% end -%>
</div>
<% end -%>
<%= link_to 'Show', :action => 'show', :id => @product %> | 
<%= link_to 'Back', :action => 'list' %>

Navigate to localhost:3000/pl/admin/products, find the product you added, and click on Edit.
If the current language is the base one, the full version of the edit form is displayed. If not, the translation form is displayed on the left and the original data on the right, as the reference for the translator.

NOTE
.switch_language method used in this code is provided by globalize_extension plugin written by Olivier Amblet from Liquid Concept, which can be found here. It provides many other useful extensions for globalize plugin. Just install it into your vendor/plugins directory

NOTE
If you’re going to translate many models it would probably be good idea to put the code above into a partial and just pass an object to translate:


render :partial "translation_page", :locals => {:object => @product}

To inform user that the text hasn’t been yet translated you can use the following helper (also from Jeremy Voorhis’ slides mentioned above):


  def translation_availability_for object_name, facet, message = nil
    not_base_language do
      message ||= content_tag 'p', '(Translation not available)'.t
      object = instance_variable_get "@#{object_name}" 
      message if object && !object.send( facet ).blank? &&
      object.send( "#{facet}_is_base?" )
    end
  end

Here’s the example of its usage:


<%= translation_availability_for :product, :description %>
<%=h @product.description %>

4.4 Translating dates

To translate dates you can use localize method or its shorter form loc. It takes format string as the paramater, exactly the same as strftime method.
I.e.


Product.find(:first).created_on.loc("%A %d-%B-%Y")

should give “Wednesday 14-June-2006” for English language and “Środa 14-Czerwiec-2006” for Polish.

countries table has field date_format, which you can use to specify custom format for different languages. Example for Polish language:


country = Country.find(:first, :conditions => "code = 'PL'")
country.update_attribute(:date_format, "%d/%m/%y")

Globalize uses cache to minimize database usage, so sometimes you need to clear it to make changes visible:


Locale.clear_cache
Locale.set "pl-PL" 
Locale.country.date_format

Now you can just use


product.created_on.loc(Locale.country.date_format)

and you’ll get different date format for every language.

In a template use for example:


@product.send(column.name).localize("%d %B %Y") if column.name.to_s == 'created_on'

4.5 Translating error messages

Globalize provides modified version of error_messages_for helper. Unfortunatelly it doesn’t have translated error messages in the database yet. But you can easily add them by yourself. Here’s how to do it.

—-
I couldn’t find any way to do it on this page, so I came up with my own solution, using the rails console script. Fairly simple:


Locale.set 'pl-PL' # you might want to iterate throught LOCALES.each_value here
ActiveRecord::Errors.default_error_messages.each_value do |error_msg|
  error_msg.translate
end

Benol

and if your base language isn’t English?
—-

4.6 Translating currency

WARNING
Current implementation of Currency class has some bugs. They should be fixed in the next revision.

Globalize provides specialized class to represent money in ActiveRecord models – Globalize::Currency.
To use it you need to modify app/models/product.rb file. Add the following line:


composed_of :price, :class_name => "Globalize::Currency", :mapping => [ %w(price cents) ]

Now product.price will return Globalize:Currency object. To display the actual value you’ve got 2 possibilities:

.to_s method
.format method, which can take optional parameters: if :code => true is specified, format using international 3-letter currency code; if :country is specified as well, use that country’s currency code for formatting

Text by: szymek (83.15.148.82)

Unit tested example

2008-06-25T00:40:35+02:00

Here’s a Unit Test (you do know how to test your Rails app, right?) which shows a way to work with the Globalize plugin. Far easier than playing around in the console to see if you can get it to work.

Ensure compatability

Globalize uses its own models – e.g. Language, Country and Translation. If you have models or database tables with these names, they might conflict with testing later on. Better now create a migration to rename these tables and then rename the models, and you’ll be fine.

Install Globalize

In your RAILS_ROOT, execute the following to install the Globalize plugin.

script/plugin install http://svn.globalize-rails.org/svn/globalize/globalize/trunk

Create the model

The test assumes the presence of a model called Newsitem. So go ahead and generate the model and modify it like so:

class Newsitem < ActiveRecord::Base
  translates    :title, :excerpt, :body
end

See the Globalize API docs for translates. Basically, it means Globalize will give the specified columns special treatment.

Create the table

The following migration might help you create the table:

class AddNewsTable < ActiveRecord::Migration
  def self.up
    create_table :newsitems do |t|
      t.column :title, :string
      t.column :excerpt, :string
      t.column :body, :text
      t.column :lock_version, :integer, :default => 0
      t.column :user_id, :integer
      t.column :updated_at, :datetime
      t.column :created_at, :datetime
    end
  end
  def self.down
    drop_table :newsitems
  end
end

You’re ready to migrate the table into your database by running rake migrate. Of course, not all columns are needed for this example, but it might be an incentive to find the meaning of one or two things in the Rails API.

Globalize it

script/generate globalize tiny
rake migrate

This will take a while. You have been warned.

Setup the test fixtures

You need to tell globalize which languages/countries it should know about. The previous migration made sure to fill up the globalize tables with a large number of preconfigured languages and countries all ready for you to use in your development database.

However as we are using the test database, you’ll need to create fixtures for the globalize tables. You can either create them from scratch (Have a look at the globalize tables in your dev tables) or copy over the fixtures used in globalize’s own test which are located in the test directory


vendor/plugins/globalize/test/fixtures/globalize_languages.yml
#You only really need the languages fixtures but chances are
#you'll want to copy over these two as well for more tests
vendor/plugins/globalize/test/fixtures/globalize_countries.yml
vendor/plugins/globalize/test/fixtures/globalize_translations.yml

The globalize test fixtures do not include dutch so you’ll have to add it in for the newsitem_test (or you could just modify the test to use any of the languages in the fixtures):


#globalize_languages.yml
...
dutch:
  id: 7
  iso_639_1: nl
  iso_639_2: nld
  english_name: Dutch
  native_name: Nederlands
  scope: L
  macro_language: false
  pluralization: 'c == 1 ? 1 : 2'
#globalize_countries.yml
...
holland:
  id: 6
  code: NL
  english_name: Netherlands
  currency_format: '€ %n'
  currency_code: EUR
  thousands_sep: '.'
  decimal_sep: ','
  currency_decimal_sep: '.'

The Unit Test

First of all, this is not a real unit test. It’s just an easy way to show you how to work with Globalize.

When you generated your model, the rails command was smart enough to create a test for it. You can find the test in RAILS_ROOT/test/unit/newsitem_test.rb. Just copy the paste below and replace the content of the original file with it.

require File.dirname(__FILE__) + '/../test_helper'
class NewsitemTest < Test::Unit::TestCase
  def test_add_content_translations
    Newsitem.delete_all
    Globalize::Locale.set_base_language('en-US')
    # create a row in the base language
    Globalize::Locale.set('en-US')
    assert_nothing_raised() do
      assert_kind_of Newsitem, Newsitem.create!(:title => 'US Title',
                                                :excerpt => 'US excerpt',
                                                :body => 'US body copy')
    end
    assert_equal 1, Newsitem.find(:all).size
    # retrieve row
    newsitem = Newsitem.find(:first)
    assert_kind_of Newsitem, newsitem
    assert_equal 'US Title', newsitem.title
    # create a translation by switching the locale and updating attributes
    Globalize::Locale.set('nl-NL')
    # newsitem.title = 'NL Titel'
    # newsitem.excerpt = 'NL samenvatting.'
    # newsitem.body = 'NL Broodtekst.'
    # assert_nothing_raised() {newsitem.save!}
    # either use the commented out code above or the line below
    # You cannot fetch a row in one language and save it in another.
    # So just switch language, fetch again, and then update_attributes
    newsitem = Newsitem.find(:first)
    newsitem.update_attributes(:title => 'NL Titel',
                                :excerpt => 'NL samenvatting.',
                                :body => 'NL broodtekst')
    # check if the translated row has been saved
    assert_equal 'NL Titel', newsitem.title
    # check if the base language row still exists
    Globalize::Locale.set('en-US')
    # now see if the example from the wiki gives the expected result
    newsitem = Newsitem.find(:first)
    assert_equal 'US Title', newsitem.title
    Globalize::Locale.set('nl-NL')
    newsitem = Newsitem.find(newsitem.id)
    assert_equal 'NL Titel', newsitem.title
  end
  def test_add_string_translations
    Globalize::Locale.set_base_language('en-US')
    Globalize::Locale.set('en-US')
    language = Globalize::Language.pick 'nl-NL'
    Globalize::Locale.set_translation(
      "This is written in English",
      language,
      "Dit is geschreven in het Nederlands" 
    )
    assert_equal 'This is written in English', "This is written in English".t
    Globalize::Locale.set('nl-NL')
    assert_equal 'Dit is geschreven in het Nederlands', "This is written in English".t
  end
end

Run the test

From your RAILS_ROOT, run the test. The expected result should be something like shown below.

aluminum:~/dev/projects/my_app/trunk charles$ ruby test/unit/newsitem_test.rb 
Loaded suite test/unit/newsitem_test
Started
..
Finished in 1.986655 seconds.
2 tests, 10 assertions, 0 failures, 0 errors
aluminum:~/dev/projects/my_app/trunk charles$

Help!

If you have more questions, you can find us in #globalize on Freenode or on the Rails mailing list. Make sure the first word of your subject line is Globalize, so your message is easier to spot.

Frequently asked questions

2008-06-25T00:40:56+02:00

NOTE: The best way to get help now is on the MailingList.

Q: Do methods like truncate still work on translated/unicode strings?

A: Good question, I haven’t looked into this much, but it’s more of a Ruby thing. Ruby doesn’t seem to handle String#length correctly for unicode strings, although I believe there are libraries that correct this. Better Unicode support is also planned for future Ruby releases. —JH

Meanwhile Globalize code doesn’t care that String.length returns size of string in bytes.
E.g. there is no support for multibyte UTF8 chars in methods globalize/rails/active_record.rb:
ActiveRecord::Errors#add_on_boundary_breaking,
ActiveRecord::Validations#validates_length_of,
or globalize/models/language.rb

Globalize::Language#after_initialize:


   if !pluralization.nil? && pluralization.size > 200
      raise SecurityError, "Pluralization field for #{self.english_name} language " + "contains potentially harmful code. " + "Must be less than 200 characters in length. Was #{pluralization.size} characters." 
   end

Be honest, say validates_bytes_length_of, “must be less then 200 bytes” or address this issue.

Q: The installation looks too easy. In fact, I tried it out.

I see this:

242:~/CD/railsdemos oracle$ rails globize  
...
242:~/CD/railsdemos oracle$ cd globize
242:~/CD/railsdemos/globize oracle$  script/plugin install svn://www.diluvia.net/rails-plugins/globalize/trunk
/opt/local/lib/ruby/1.8/open-uri.rb:87:in `initialize': No such file or directory - svn://www.diluvia.net/rails-plugins/globalize/trunk (Errno::ENOENT)
    from /opt/local/lib/ruby/1.8/open-uri.rb:87:in `open_uri_original_open'
...
    from     from script/plugin:3

What am I doing wrong?

-Dan
Dan.Bikle@gmail.com

A: Dan, do you have subversion installed? Is it in your path? Also, which version of Ruby are you running?

Q: I’ve also go a weird error, when using PostGreSQL 8.0. Everything works fine on my debian server (live box), but on my Ubuntu box (devel box) things are a little screwy.

Everytime I try to rake migrate I get the following error:

 RuntimeError: ERROR     C55000  Mcurrval of sequence "globalize_countries_id_seq" is not yet defined in this session    Fsequence.c        L598    Rcurrval: SELECT currval('public.globalize_countries_id_seq')

Anyone have any idea what I’m doing wrong ?

A: Which versions of Rails, Globalize and Postgresql do you have?—JH

I got the data to load by modifying the migration to ignore the row id. Here is a patch:

--- 002_globalize_migration.rb.orig     2005-12-30 17:38:33.000000000 +0800
+++ 002_globalize_migration.rb  2005-12-29 02:24:22.000000000 +0800
@@ -72,13 +72,20 @@
       reader = CSV::Reader.create(data)
       columns = reader.shift.map {|column_name| cnx.quote_column_name(column_name) }
+      columns.shift # added for PostgreSQL
       column_clause = columns.join(', ')
       reader.each do |row|
         next if row.first.nil? # skip blank lines
         raise "No table name defined" if !table_name
         raise "No header defined" if !column_clause
-        values_clause = row.map {|v| cnx.quote(v).gsub('
', " 
").gsub('
', " 
") }.join(', ')
+
+       # Changed for PostgreSQL
+        #values_clause = row.map {|v| cnx.quote(v).gsub('
', " 
").gsub('
', " 
") }.join(', ')
+        values = row.map {|v| cnx.quote(v).gsub('
', " 
").gsub('
', " 
") }
+       values.shift
+        values_clause = values.join(', ')
+
         sql = "INSERT INTO #{table_name} (#{column_clause}) VALUES (#{values_clause})" 
         cnx.insert(sql)
       end

—Jake Morrison

I had the same trouble with Postgres. The issue is that Postgres does not define currval() before the sequence is used. What I did was add a call to set the values on the sequences after the creation of the tables (around line 55):

    # Added for PostgresSQL
    tables = ['globalize_countries', 'globalize_translations', 'globalize_languages']
    tables.each do |table|
      sql = "SELECT setval('#{table}_id_seq', 1)" 
      ActiveRecord::Base.connection.execute(sql)
    end

-Daniel Wiesmann

Why is :select not allowed in the replacement for ActiveRecord::find? (in Globalize::DbTranslate)

Because Globalize modifies the :select portion of the query, so overriding it would break the functionality. —JH

I can see that I’m to use “string”.t to translate strings in my app, but where do I actually put the translated strings? Am I just blind, or is this not covered anywhere?

The translated strings go in the globalize_translations table in the db. Use Globalize::Locale.set_translation(key, *translations) to write new translations to the db. —JH

rails validation error gives me a ’%d’ i.s.o a number

There were problems with the following fields:
    * Desc short is too short (min is %d characters)

BTW is is an idea to have these validation errors also in the translation database?

_cies breijs.

Answer: Actually, I’ve been seeing that, too—I’m going to look into it. —JH

i think this is an error generating an other error.
when i get globalize out of the plugin-path and environment.rb i get to see a normal error.

ActionView::ActionViewError (No rhtml, rxml, or delegate template found for /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/templates/rescues/diagnostics.rhtml):
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_view/base.rb:281:in `pick_template_extension'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_view/base.rb:195:in `globalize_old_render_file'
    /vendor/plugins/globalize/lib/globalize/rails/action_view.rb:15:in `render_file'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/rescue.rb:73:in `rescue_action_locally'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/rescue.rb:31:in `rescue_action'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/rescue.rb:108:in `perform_action'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/base.rb:369:in `send'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/base.rb:369:in `process_without_session_management_support'
    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.11.2/lib/action_controller/session_management.rb:116:in `process'
    /usr/local/lib/ruby/gems/1.8/gems/rails-1.0.0/lib/dispatcher.rb:38:in `dispatch'
    /usr/local/lib/ruby/gems/1.8/gems/rails-1.0.0/lib/fcgi_handler.rb:141:in `process_request'
    /usr/local/lib/ruby/gems/1.8/gems/rails-1.0.0/lib/fcgi_handler.rb:53:in `process!'
    /usr/local/lib/ruby/gems/1.8/gems/rails-1.0.0/lib/fcgi_handler.rb:52:in `each_cgi'
    /usr/local/lib/ruby/gems/1.8/gems/fcgi-0.8.6.1/./fcgi.rb:597:in `each'
    /usr/local/lib/ruby/gems/1.8/gems/fcgi-0.8.6.1/./fcgi.rb:597:in `each_cgi'
    /usr/local/lib/ruby/gems/1.8/gems/rails-1.0.0/lib/fcgi_handler.rb:52:in `process!'
    /usr/local/lib/ruby/gems/1.8/gems/rails-1.0.0/lib/fcgi_handler.rb:22:in `process!'
    dispatch.fcgi:24

_cies breijs.

Is there a way to make globalization work with pagination? I’m getting an error about :select, which was explained, but any ways to get it to work?

Answer: Good question, I’m looking into it. —JH

Any plan to make this module install via rubygem?

—CC

Answer: Not at this point. Since it’s a per application modification, I’m not sure how that would work. —JH

I have installed globalize according to the instruction provided in the home page. I populated the development database and test database. When I test run the test_plugins, I got an error loading sqlite3 as the following.

/usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:21:in `require__': no such file to load -- sqlite3 (MissingSourceFile)

Why do I have to have sqlite installed? I use mysql only. Any idea how to workaround this?

—CC

Answer: You don’t really have to have sqlite installed. That’s just the default so that it will work out of the box with no extra db setup. Just change the globalize/test/config/database.yml file to reflect your mysql globalize test db. —JH

Are translations by language or by locale? As far as I can see they are by language, i.e.,

Locale.set("en-CA")
Locale.set_translation("a test","Canadian test")
Locale.set("en-US")
Locale.set_translation("a test","American test")

ends up with only one translation, and

<% Locale.set("en-CA") %>
<%= "a test".t %><br/>
<% Locale.set("en-US") %>
<%= "a test".t %><br/>

prints out

American test
American test

Am I missing something? Thanks,

Dave

Answer: Yes, translations are keyed by language, however a language can be a localized dialect, such as en-CA (this is standardized as RFC 3066, and the Language model has a column for it). All you have to do is add rows to the globalize_languages table for the dialects you need. Then, when you do something like Locale.set(‘en-CA’), the referenced language will be the new en-CA language you added. —JH

More: I have run into a problem with this. The translation
cacheing uses the language first, then the locale
RFC 3066 locale. That is, cache_key in
Globalize::DbViewTranslator

  def cache_key(key, language, idx)
    [ key, language.code, idx ].join(':')
  end

uses language.code, which is defined like this:

  def code; iso_639_1 || iso_639_3 || rfc_3066; end

So it seems that either code needs to try rfc_3066 first, or cache_key does, i.e.

  def code; rfc_3066 || iso_639_1 || iso_639_3; end

Or you have to null out the iso_639_1 and iso_639_3 fields
if you are going to use rfc_3066. I have modified code on my site. —Jake Morrison

I already have a small web app which is translated into a number of langs (about 7). It’s perl on top of mysql. I’m looking at maybe migrating to ROR in future.

My app is organised in a very simple way – I have a table called sitetext:

id en fr es de cn

this handles the majority of small words and phrases used. I use substitution like $VAR to make things flexible. There are other tables too that work similarly.

How is underlying content organised in globalize? How hard would it be to write a script to migrate my content?
Also, suppose a pages content changes – the author changes the english text. Does globalise track the fact that other langs are out of date? This is the way I will definitely need to go in future.

thanks

Answer: I don’t understand how you’re currently doing it, but you should definitely be able to write a migration script. As for question 2, Globalize is not currently tracking that, but it’s in the works.

response
My current layout is just one col in a table per language, plus an id – that’s what I meant. How is the database laid out in your code? is it documented somewhere here (even just an sql script or something?) thanks for the answer.

Jan 05, 2006:

I’m using ubuntu “hoary”, ruby 1.83, rails 1.0, postgres 7.4.7, and globalize svn version 155. The first two steps in the installation worked fine, but the third, “rake migrate” failed, in the same way described by Jake Morrison in his post above. I also had success by changing my db/migrate/001_globalize_migration.rb script as Jake described, after dropping the tables created in the database on the first attempt of running “rake migrate”

It’d be nice to patch the file. I suspect that the patched file would run on mysql also – the generated sql is standard sql.

OK, off to testing out globalizing my app.

Thanks for writing Globalize!

2006-01-25:

The plugin seems to be very useful. Only I’m worried that storing both app-translations (interface) and user-translations (user data) in the same database/table might make development as well as deployment harder. How do you handle this?

I imagine there could be benefits of a YAML based (or similar) solution for the view translations, and maybe even the languages and countries tables. (Version control, separation of user data and app data and more.) (Note that this is ment as a question, not a flame.)

2006-01-31

I would like to feed all translation strings from external script in shell, but I have no idea how to make it… I can load those data only from controller and browser, but it is not efficient :(

class WelcomeController < ApplicationController
  include Globalize
  def load
      Locale.set_base_language('en')
      rows = [
        {:key=>'title', :language=>'pl', :translations=>['Tytuł', 'Tytuły', 'Tytuły', 'Tytuły', 'Tytułów']},
        {:key=>'title', :language=>'en', :translations=>['The title', 'The titles']},
        {:key=>'title', :language=>'de', :translations=>['Der Titel']},
      ]
      for row in rows
        Locale.set(row[:language])
        Locale.set_translation(row[:key], Locale.language, row[:translations]) 
      end
  end
end

There would be very usefull to have an option for extract all globalize strings into one place (like gettext). And, after translation, upgrade the database with one script.

2006-02-07

I have been trying using Globalize plugin from external Ruby script, but it I do not know how. I created folder ‘work’ in my RoR application and I try to use script from this place:

1st try:

require File.dirname(__FILE__) + '/../vendor/plugins/globalize/init.rb')

does not work:

undefined local variable or method `directory' for main:Object (NameError)

2nd try:

require 'active_record'
def directory_binding
  directory = File.dirname(__FILE__)+"/../vendor/plugins/globalize/lib/" 
  Dir.chdir(directory)
  binding
end
eval(IO.read(File.dirname(__FILE__) + '/../vendor/plugins/globalize/init.rb'), directory_binding)

also does not work:

./globalize/rails/action_view.rb:4:in `alias_method': undefined method `render_file' for class `ActionView::Base'

2006-02-21

I really need some help in using the Globalize plugin. I’m currently developing on OSX 10.4.4, RoR 1.0, Postgres 8.0, and Ruby 1.8.2_4. My problem is making Globalize work with my models. Here a sample of my code:

environment.rb:

include Globalize

controllers/application.rb:

class ApplicationController < ActionController::Base
  Locale.set_base_language('en-US')
end

models/trial.rb:

class Trial < ActiveRecord::Base
  translates :name
end

trial_controller.rb:

class TrialController < ApplicationController
  def index
    Locale.set('en-US')
    Trial.create(:name => 'One')
    Locale.set('es-ES')
    trial = Trial.find(1)
    trial.name = 'Uno'
    if trial.save
       render_text("#{trial.name")
    end
  end
end

When running the app I get this error:

RuntimeError: ERROR    C42601    Msyntax error at or near "WHERE"    P20 
Fscan.l    L639    Ryyerror: UPDATE trials SET  WHERE id = 1

Looking at it closely, it seems that on the intiall save on the
database, no data is being saved on the globalize_translation table so
when I try to update the data from my trials table no value is being
passed.

I know that I have configured the app properly because data is being
passed to the globalized_translation folder when I do “foo”.t on the views but I
really can’t make it work with my models.

Q: How do i prevent the base language text from being displayed when there’s no translation available for the current language?

Q: How do i find out (at runtime) if a model has a translation in the current language?

A: Globalize adds the methods xxx_is_base? to ActiveRecord, where xxx stands for the attribute name. before using the attribute, first check if it’s translated.

Example:
I have lots of Page objects, the property content is translated into several languages. To display all the pages that still need to be translated, do the following:

# somewhere in the controller
include Globalize
Locale.set_base_language('en')
Locale.set('es')
@pages = Page.find(:all)
# in the view
<%
@pages.each do |page|
  if page.content_is_base? %>
    <%= puts 'Page still needs to be translated!' %>
<% end %>
(not tested, hope there's no bug.)

Q: When I do a rake migrate I get this error. How do I fix it?

rake migrate
(in /home/brian/pken)
rake aborted!
undefined method `namespace' for #<Object:0x400b59c0>

A: You need to update rake to 0.7 which adds namespace support. `sudo gem update rake` will do that for you.

2006-05-15

Q How much effort would it be to implement Oracle support? What are the DB-depencies?

Q Is possible to implement a runtime URL name translation?
...
map.connect /:language/ “restaurant”.t ”/” + “parmesan”.t
...
So that /en/restaurant/parmesan and /it/ristorante/parmigiano are logically the same page?

—> that would be amazing!
or some other possibility to support localizing urls, too. how are you guys doing this?
http://rails.techno-weenie.net/question/2006/5/23/url_reverse_translation

Acknowledgements

2008-06-25T00:41:12+02:00

This project grew out of many discussions I had with Josh Sierles. A lot of the view translation stuff is inspired by Per Wigren’s MLR code. I also used a lot of his localization data to populate the globalize tables. I have no idea how he compiled all that data, but it’s great stuff.

A lot of people have helped iron out initial bugs (and I’m sure there will be many more opportunities to do the same), but I’d like to thank Andreas Roedl especially, for the many hours he’s put in.

Jeremy Voorhis and Olivier Amblet and Yann Lugrin (http://liquid-concept.ch) are the core dev faithful. Obviously, I wouldn’t be doing this if it weren’t for the phenom that is Ruby on Rails. Thanks, DHH.

All code and accompanying documentation was originally written and is copyrighted by Josh Harvey. It is released under the MIT license.

How to use globalize

2008-06-25T00:41:28+02:00

In your models


  class Product < ActiveRecord::Base
    translates :name, :description, :specs
  end

Create a row and its translation:


  Locale.set_base_language('en-US')
  Locale.set('en-US')
  Product.create!(:name => 'Meatballs')
  Locale.set('es-ES')
  prod = Product.find(1)
  prod.name = 'Albóndigas'
  prod.save

Then:


  Locale.set("en-US")
  prod = Product.find(1) 
  prod.name -> "Meatballs" 
  Locale.set("es-ES")
  prod = Product.find(1) 
  prod.name -> "Albóndigas"

In your views (or anywhere else)


  Locale.set("he-IL")
  <%= "Thanks for ordering!".t %> -> "תודה על ההזמנה!" 
  <%= "You've got %d items in your cart" / 5 %> -> "יש 5 מוצרים בסל שלך" 
  Locale.set("es-ES")
  <%= Time.now.localize("%d %B %Y") %> -> "17 Octubre 2005" 
  <%= 12345.45.localize %> -> "12.345,45"

There’s more, see Features.

Globalize powered sites

2008-06-25T00:42:03+02:00

Rash Gash Guitars — This is the reason Globalize exists. I needed the site to work in English and Hebrew.
CrispyNews — Create your own community news site! We’ve gotten alot of international interest in our application, but we only support english. We’re currently installing globalize and our intention is to have a globalization module that’ll let anyone port crispynews into their own language.

Update: Globalize was successfully installed, and we’ve even extended it into an interesting “fun project” which retreives automatic translations from sites like Babelfish and Google translate for phrases that have not been translated yet. The translations are not really usable without significant modification, but those interested in making similar enhancements can read the article Internationalization with Rails, Globalize and Google We chose it over some other Ruby globalization libraries because of its rails-y feel. We look forward to continually incorporating future versions as they make further optimizations and improvements are released. – crispynews coders.
South America Travelogue — Photos, travel stories and a map of my 8-month backpacking trip through South America. All in English and German using Globalize – Ole Begemann.
Equal project — This is Latvia’s government project site.
media.nikefootball.com – provides multimedia content to the press for Nike’s 2006 football campaign. Also the subject of screenshots in Jeremy Voorhis’ slides from the Canada on Rails Globalize talk.
www.trikr.net – A collaborate project time tracker tool.
www.keysearch.ch — Banking Executive Search in Switzerland
www.sgsm.ch — Schweizerische Gesellschaft für Sportmedizin
Tomislav Filipčić – Photography — Art photography. In English and Croatian using globalize.