Courtesy of igrigorik.

The Rub

I needed a way of grabbing up to date currency information and an easy way to convert currencies using these up to date rates.

Normally this information requires signing up for premium accounts or writing web scrapers to do this for you.

It turns out that the European bank provides a daily xml for free that contains this information. It is specific to the euro but is fairly trivial to convert this into conversion rates for any of the other currency as the base currency.

Currency Rates is born

gem install currency_rates

It is a simple class for getting up to date currency rates in an array. You pass a base currency which the rates will be calculated against. Connects to the european bank to get a daily breakdown of the rates.

Deliberately lightweight to allow you to build on top of.

Example

#!/usr/bin/env ruby
 
require 'rubygems'
require 'currency_rates'
 
parser = CurrencyRates::Parser.new('GBP')
puts parser.engage.inspect

Valid values for the initialize call are:

"USD"
"JPY"
"BGN"
"CZK"
"DKK"
"EEK"
"GBP"
"HUF"
"LTL"
"LVL"
"PLN"
"RON"
"SEK"
"CHF"
"NOK"
"HRK"
"RUB"
"TRY"
"AUD"
"BRL"
"CAD"
"CNY"
"HKD"
"IDR"
"INR"
"KRW"
"MXN"
"MYR"
"NZD"
"PHP"
"SGD"
"THB"
"ZAR"
"EUR"

Example result array:

[{"currency"=>"USD", "rate"=>"1.58482"}, {"currency"=>"JPY", "rate"=>"130.28671"}, {"currency"=>"BGN", "rate"=>"2.26562"}, {"currency"=>"CZK", "rate"=>"28.05560"}, {"currency"=>"DKK", "rate"=>"8.63284"}, {"currency"=>"ILS", "rate"=>"5.71573"}, {"currency"=>"GBP", "rate"=>"1.00000"}, {"currency"=>"HUF", "rate"=>"317.67159"}, {"currency"=>"LTL", "rate"=>"3.99977"}, {"currency"=>"LVL", "rate"=>"0.81552"}, {"currency"=>"PLN", "rate"=>"4.48653"}, {"currency"=>"RON", "rate"=>"4.94642"}, {"currency"=>"SEK", "rate"=>"10.26180"}, {"currency"=>"CHF", "rate"=>"1.49690"}, {"currency"=>"NOK", "rate"=>"9.11266"}, {"currency"=>"HRK", "rate"=>"8.58558"}, {"currency"=>"RUB", "rate"=>"47.14741"}, {"currency"=>"TRY", "rate"=>"2.50090"}, {"currency"=>"AUD", "rate"=>"1.58992"}, {"currency"=>"BRL", "rate"=>"2.64361"}, {"currency"=>"CAD", "rate"=>"1.57892"}, {"currency"=>"CNY", "rate"=>"10.43290"}, {"currency"=>"HKD", "rate"=>"12.33837"}, {"currency"=>"IDR", "rate"=>"14323.90385"}, {"currency"=>"INR", "rate"=>"72.43649"}, {"currency"=>"KRW", "rate"=>"1770.37938"}, {"currency"=>"MXN", "rate"=>"19.10177"}, {"currency"=>"MYR", "rate"=>"4.83614"}, {"currency"=>"NZD", "rate"=>"2.06591"}, {"currency"=>"PHP", "rate"=>"70.20678"}, {"currency"=>"SGD", "rate"=>"2.02989"}, {"currency"=>"THB", "rate"=>"48.82247"}, {"currency"=>"ZAR", "rate"=>"11.25607"}, {"currency"=>"EUR", "rate"=>"1.15841"}]

Code is also available on github

Google storage was recently released as an open beta for developers to work with. All in all it seems like an Amazon S3 clone and whilst they have their REST api for integration they also support the Amazon S3 api.

Originally I was planning on writing a ruby wrapper of this api but decided to see if I could modify with existing aws-s3 gem to work with google storage.

After some in depth reading of both apis and understanding of the aws-s3 gem I have modified it to also work with google storage.

My github fork contains these modifications.

To use:

 
  require 'aws/s3'
  include AWS::S3
 
  Base.establish_connection!(
      :access_key_id     => 'abc',
      :secret_access_key => '123',
      :default_host => "commondatastorage.googleapis.com"
    )

Note the addition of the default_host to connect to google instead of AWS.

From then on you can use the gem as normal as is described in the Readme.

As git is distributed, the repository on your local machine is good enough to deploy from.

First start a git server on your local machine.

  git daemon --base-path=/projects/rails_apps/ --export-all

Then change your capistrano recipe to deploy with the copy command and change the repo to point to your local machine.

  set :deploy_via, :copy
  set :repository 'git://127.0.0.1/proj_name'

Where in this example the code resides at */projects/rails_apps/proj_name*

Now capistrano will deploy from your local repository, thus avoiding the currently melted github

There are other options which have been listed by chris wanstrath in the following article

Google sitemaps are nice for telling google what is where. Often clients want it for SEO or you have a site which has new content all the time and you want to keep google up to date.

Whatever the reason is thats you are interested in these little xml files, the following code allows you to generate a sitemap for a dynamic site in ruby.

Firstly the class:

  require 'net/http'
  require 'uri'
 
  # A class specific to the application which generates a google sitemap from
  # the contents of the database.
  # Author: Alastair Brunton
  class GoogleSitemapGenerator
 
    def initialize(base_url, sources)
      @base_url = base_url
      @sources = sources 
    end
 
    # The main generator method which in turn adds to the path_array from the different
    # sources.
    # Sources are: pages, events, properties
    def generate
      path_ar = Array.new
      @sources.each do |source|
        # initialize the class and call the get_paths method on it.
        path_ar = path_ar + eval("#{source}.get_paths")
      end
      xml = generate_xml(path_ar)
      save_file(xml)
      update_google
    end
 
    # This creates the xml document.
  	def generate_xml(path_ar)
  		xml_str = ""
  		xml = Builder::XmlMarkup.new(:target => xml_str)
 
  		xml.instruct!
  			xml.urlset(:xmlns=>'http://www.google.com/schemas/sitemap/0.84') {
    			path_ar.each do |path|
      	    xml.url {
        	    	xml.loc(@base_url + path[:url])
        			xml.lastmod(path[:last_mod])
        			xml.changefreq('weekly')
     			 }
    			end
  			}	
  		xml_str
  	end
 
  	# Saves the xml file to disc. This could also be used to ping the webmaster tools
  	def save_file(xml)
  		File.open(RAILS_ROOT + '/public/sitemap.xml', "w+") do |f|
  			f.write(xml)	
  		end		
  	end
 
  	# Notify google of the new sitemap
  	def update_google
  	    sitemap_uri = @base_url + '/sitemap.xml'
  	    escaped_sitemap_uri = URI.escape(sitemap_uri)
  	    Net::HTTP.get('www.google.com',
  	                  '/webmasters/sitemaps/ping?sitemap=' +
  	                  escaped_sitemap_uri)
  	end
 
 
  end

You will notice that an array of strings are passed when calling the generator. These are names of object which implement the get_paths method. An example get_paths class method is as follows:

  # for the google sitemap
   def self.get_paths
     path_ar = Array.new
     Property.live_properties.each do |property|
       path_ar << {:url => "/property/#{property.to_param}", :last_mod => property.updated_at.strftime('%Y-%m-%d')}
     end
     path_ar
   end

Basically, you need an array of hashes which each contain the url and the last_mod.

To call this little beastie it is best done from a cron on the production server. An example rake task to do this is as follows:

  namespace :google_sitemap do
    desc "Generate a google sitemap from the site."
    task(:generate => :environment) do
      sources = ['Page', 'Event', 'Property']
      sitemap = GoogleSitemapGenerator.new('http://www.your_url.com', sources)
      sitemap.generate
    end
  end

Remember when you are calling it from a cron to pass the RAILS_ENV. This generator does rely on rails but you could convert it to only rely on ruby by modifying the rake task and changing the RAILS_ROOT reference in the save_file method. Probably can be made to work with Merb but I am unsure of how merb and rake work together. Will hopefully get my hands dirty with Merb sometime soon.

   cd /var/www/apps/site/current /usr/bin/rake RAILS_ENV=production google_sitemap:generate

Throwing and catching exceptions can be a good design pattern in your rails app. Especially when you want to be able to deal with the unexpected in a clean way. Overuse is a no no as with most techniques but it is nice here and there.

I find that a good idea is to make your own exceptions when writing a rails app. This means that standard low level exceptions which often should not be caught are not.

eg.

(in config/initializers/custom_config.rb)

  class ApplicationError < RuntimeError
 
  end

This way in your application code you can do something like the following

  begin
    @user = User.find_by_password_reset_code(params[:id])
    raise ApplicationError if @user.nil?
 
  rescue ApplicationError => msg
    flash[:message] = "Sorry - That is an invalid password reset code. Please check your code and try again. (Perhaps your email client inserted a carriage return?"
    redirect_to logins_url
  end

In other news I have started testing deploying with git and capistrano. It is blazingly fast even for a full checkout. I cant get :remote_cache deploy via working due to an ancient version of git on LTS 6.06. But event with full checkout this is faster than deploy_via :remote_cache with subversion! (This is with 2 slices on a local network.)

sudo gem install hpricot -v0.5

This is a plugin which I have developed internally with Iformis. I realised it would be nice to share yet another pdf plugin with the rails community. This is designed to render pdfs with layouts. This is especially useful when working on projects where the pdf has to conform to a set design and where the data is presented in a generate report style. Banks often operate their tools in this manner.

Simple PDF reporting rails plugin designed to render layout based pdfs. Built on top of Ruport which is in turn built on top of pdf-writer.

Requires Ruport

Step 1: Install Ruport

gem install ruport

Step 2: Install the plugin (from RAILS_ROOT)

./script/plugin install http://iformis.svnrepository.com/svn/rupdf

Step 3: Create a class extending Rupdf::Base

Note: The only methods calls required are define_header, define_body and define_footer
The other methods are helper methods. Remember that html doesnt work in the body.

class Simple < Rupdf::Base
 
  define_variables :report_title
  renders :pdf, :for => Rupdf::Renderer
 
  define_header do
    add_header(report_title)
  end
 
  define_body do
    add_text("hello man\n\n\n")
    add_text("bye man.")
 
    add_text("bye man.")
    add_text("hello man\n\n\n")
    add_text("bye man.")
    add_text("hello man\n\n\n")
    add_text("bye man.")
 
    # add image (path defined at runtime)
    image(smile_path)
 
    add_text("hello man\n\n\n")
    add_text("bye man.")
    add_text("hello man\n\n\n")
 
  end
 
  define_footer do
    footer_text = %(
    This is the beautiful footer text.
    )
    add_footer(footer_text)
  end
 
 
 
  def add_header(title)
    rounded_text_box("<b>#{title}</b>") do |o|
      header_color = Color::RGB.from_html("#FFDE16")
      o.fill_color = header_color
      o.stroke_color = header_color
      o.radius     = 0
      o.width      = options.header_width || 550
      o.height     = options.header_height || 80
      o.font_size  = options.header_font_size || 12
      o.x          = pdf_writer.absolute_right_margin - o.width
      o.y          = pdf_writer.absolute_top_margin
    end
 
 
 
  end
 
  def add_footer(text, options = nil)
 
    unless options
      options = OpenStruct.new(:font_size => 6)
    end
 
    rounded_text_box(text) do |o|
      footer_color = Color::RGB.from_html("#EAECEE")
      o.fill_color = footer_color
      o.stroke_color = footer_color
      o.radius     = 0
      o.width      = options.header_width || 550
      o.height     = options.header_height || 60
      o.font_size  = options.font_size || 12
      o.x          = pdf_writer.absolute_right_margin - o.width
      o.y          = pdf_writer.absolute_bottom_margin + o.height
 
    end
 
  end
 
end

Step 4: Tie it into a controller and pass the variables at runtime.

class TestController < ApplicationController
 
  def pdf
    simple = Simple.new
    pdf = Rupdf::Renderer.render_pdf do |o|
      o.report_title = 'This is a test of a var being passed.'
      o.smile_path = RAILS_ROOT + '/public/images/smile.jpg'
    end
    send_pdf(pdf)
  end
 
end

The send_pdf function sends the rendered pdf to the browser.

If you need to perform more complicated pdf rendering operation
please refer to the API Documentation for pdf-writer. The API docs for
ruport will also be useful if you are involved in presenting tabular
data from activerecord.

Example programming code along with how to call it is supplied in the
examples directory. I suggest you use these as a base for pdf generation code you write.

This has been tested with both Rails 1.2 and Rails 2.01. Thanks for listening.

Recently signal vs noise showcased how their continuous integration tool posts to campfire using the tinder api. Well I thought that it looked cool so have thrown together a quick and dirty ruby script to do it as well.

It will integrate with anything which has an RSS feed. Cruisecontrol.rb does and works nicely. Its a bit rough around the edges but works as is. Run it from the crontab and you are sorted.

Improvements welcome.

Here is a screenshot of it posting on campfire:

Here is the code:

#!/usr/bin/ruby
 
require 'rubygems'
require 'active_record'
require 'simple-rss'
require 'open-uri'
require 'tinder'
include Tinder
 
# Author: Alastair Brunton
# http://www.simplyexcited.co.uk
# Rss to Campfire
 
campfire_domain = 'simplyexcited'
campfire_email = 'cheer@cheerfactory.co.uk'
campfire_password = 'xxxx'
feeds = %w(http://feedserver/edflats.rss)
 
 
ActiveRecord::Base.logger = Logger.new(STDERR)
ActiveRecord::Base.colorize_logging = false
 
ActiveRecord::Base.establish_connection(
:adapter => "mysql",
:username => "username",
:password => "password",
:database => "ci_to_campfire"
)
 
# uncomment this section the first time to create the table
 
# ActiveRecord::Schema.define do
#    create_table :items do |table|
#        table.column :feed_identifier, :string
#        table.column :title, :string
#        table.column :link, :string
#        table.column :description, :text
#    end
# end
 
class Item < ActiveRecord::Base
  def to_s
    %(Theres been some action:\n
    #{self.title}\n\n
    #{self.description}
    )
  end
end
 
 
campfire = Campfire.new campfire_domain
campfire.login campfire_email, campfire_password
room = campfire.find_room_by_name('The Office')
feeds.each do |rss_url|
  rss_user_agent = "RSS to Campfire"
 
  rss_items = SimpleRSS.parse open(rss_url ,"User-Agent" => rss_user_agent)
 
  for item in rss_items.items
 
    Item.transaction do
      unless existing_item = Item.find(:all, :conditions => ["link=? AND feed_identifier=?", item.link, rss_url]).first
        new_item = Item.create(:title => item.title, :link => item.link, :description => item.description, :feed_identifier => rss_url)
        room.paste(new_item.to_s)
      end
    end
  end
end
room.leave
campfire.logout

After it taking me 6 months to be converted to TDD, the last 6 months I have been improving my skills in the TDD arena. After developing some fairly complex systems I was finding fixtures to be far too brittle and was relying on the ar_fixtures plugin to generate fixture data.

The thing is, this isn’t right. You shouldn’t be generating the fixtures from data created by untested code!

To get straight to the point, the following 2 techniques are great for fixture-less testing.

1. Have a phat test_helper.rb

Use transactional fixtures.

In your test_helper.rb you should be extracting out all the object creation code so you can use it over multiple tests.

eg.

  def create_property(options={})
    Property.create!(
    {
      :title => 'Flat in Skye',
      :address_line_1 => 'Flat 2/1',
      :address_line_2 => '75 Old Dumbarton Road',
      :city => 'Glasgow',
      :postcode => 'G3 8RG',
      :short_description => 'Great flat in Yorkhill',
      :full_description => 'This is in a great location and has top views of the university',
      :min_people => 1,
      :max_people => 10,
      :tag_list => "Dishwasher\nTV",
      :landlord_id => 1,
      :is_live => true
    }.merge(options)
    )
  end

This is great because in my tests I can run something like.

  def test_special_dom
    p = create_property(:is_live => false)
    special_dom = p.special_dom('new')
    assert_not_nil(special_dom)
    assert_equal("property_#{p.id}_new", special_dom)
  end

This means that the setup and tear down for this test is done in the test method meaning I know exactly what I am working with. If you look at line 2 you will see you I can override the default options in the test method by passing a hash of new options. This is the beauty of the merge method in test_helper.rb

2. Use the setup method in both unit and functional tests.

This is not only great for logging in users, but it also is great for running the data creation methods before you run the test and make all your test methods a little more DRY.

eg.

  def setup
    @controller = LandlordAjaxController.new
    @request    = ActionController::TestRequest.new
    @response   = ActionController::TestResponse.new
    @property = create_property
    login_landlord
  end

Now all my tests in this functional test can use the @property object.

eg.

  def test_back_calendar
    xhr :post, :back_calendar, :property_id => @property.id, :month_date => Date.today.to_s(:db)
    assert_rjs :replace_html, 'months'
  end

Thats all for now. If you have any more tips for fixtureless testing please add them to the comments.

Ubuntu Dapper will only install ruby as high as 1.8.4 which is not ideal sometimes. To upgrade an existing ruby installation to 1.8.6 do the following.

  sudo apt-get install build-essential
sudo apt-get install libreadline5 libreadline5-dev
wget ftp://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6.tar.gz
tar -xzf ruby-1.8.6.tar.gz
cd ruby-1.8.6
./configure --prefix=/usr/local --enable-pthread --with-readline-dir=/usr/local
make
sudo make install

Even if you had rubygems you need to install it and all your gems! Again.

   wget http://rubyforge.org/frs/download.php/35283/rubygems-1.1.1.tgz
tar -xzf rubygems-1.1.1.tgz
cd rubygems-1.1.1
sudo ruby setup.rb

Now this is where you need to do a little fix. Openssl will not work out of the box and some application need it so you should just set it up now.

Note: If apt-get libssl-dev complains about a not found run: sudo apt-get update

  sudo apt-get install libopenssl-ruby
sudo apt-get install libssl-dev
 
cd ~/src/ruby-1.8.6/ext/openssl
ruby extconf.rb
make
sudo make install

And thats it!

This is more of an idea than something I have needed yet but I don’t see why it wouldn’t work.

• Open a twitter account if you haven’t already got one.
• Open another twitter account and call it something_notifier or something fun like that.
• Setup your mobile on the first account and set it up to follow the notifier account and receive SMS notifications when it updates.
• Test this.
• Now whenever the notifier twitter account it updated you will receive a text with the contents of the update.

For example, the next step could be to install a twitter API implementation on your servers then update twitter if something catastrophic happens. Remember to alter the privacy settings and set it so that only your followers can see your updates.

But I’m sure there are loads of uses for this; any ideas? Although SMS messaging from the internet is easy in the USA, its a lot more complicated in the UK and Europe.

I have been doing a bit of sysadmin stuff with iformis recently which has involved a bit of virtual host configuration for a number of sites. Although Nginx is top for rails, apache is still the king of PHP.

We use apache in a debian / ubuntu environment so I have gone and written a wee gem to make vhost configuration a bit easier.

1. Install apacheconf


sudo gem install apacheconf


2. Setup YAML Config


site_name: fun
server_name: fun.com
server_alias: www.fun.com
document_root: /var/www/apps/fun


3. Run apacheconf


apacheconf --enable fun.yml


4. There is no step 4!

Please contact me with any issues and ideas for improvements.

One thing: monit can have its own little http server which runs internally. This is off in the example config as you have to explicitly enable it.

I hope to release a monit config generator gem in the near future which makes this a lot quicker.

Also my modification to the Amazon S3Sync ruby library was accepted. Now everyone can enjoy a YAML config file rather than using environment variables.

Also my modification the Nginx config generator to add SSL support was also accepted. Get in.

In case you dont have the time to update your recipe and are setting up a new machine.

It has taken me a while to move from the custom checkout scripts that I use for rails deployment to move to the capistrano way of doing things. I am so excited about it that I have decided to write this blog post.

This is not a definitive guide to rails deployment with capistrano but is the way I do things when deploying to slicehost for an application which we will be releasing in the not too distant future. This should work out for other vps servers and can be modified for shared hosting where you dont have as many permissions such as sudo access. Also I am basically a capistrano beginner so take what I say with a pinch of salt.

Firstly, if you are not familiar with capistrano I recommend purchasing the peepcode episode titled Capistrano Concepts

Your using source control right?

So you need to have your application in a repository somewhere which your deployment box can access. You should also setup the repository to work with the rails app (ignore log files, ignore database.yml, ignore *.pid files etc.) There is a great rake task for setting up subversion on rails

You have installed and setup your vps?

You have also setup ssh key authentication to avoid typing in passwords all the time. You are also just deploying to a single server and only have one mongrel process to start with.

For installing and setting up nginx for your deployment its best just to install nginx from source and use the nginx config generator to configure nginx for your deployment. I am also loving the no_www option which redirects requests to www.example.org→example.org. Is it just me or do other people hate www.*

Setting up a deploy user on the VPS is also recommended for cleanliness.

You have setup a database and there is a domain you can run this off?

Install capistrano and railsmachine

This is a great little collection of capistrano tasks to organise the deployment by convention over configuration.

Setup your rails app and deploy

This creates a deploy.rb in your /config directory where you can setup the deployment. My deployment script can be found over at pastie

The tasks defined in the two bottom tasks are defined in a mycaptasks.rb file which I can move around projects. You could also set it up as an svn:external in your project if you want to be more DRY. It is also up on pastie

Now run:
cap setup

This sets up the folder structure that capistrano uses.

Now:
cap cold_deploy

To check everything is working ok.

Now:
cap deploy_with_migrations

This will build up your new database assuming you work withe database migrations.

From now on
cap deploy

To deploy your app.

Its in source control

Cheers for now

I recently finished Everyday Scripting with Ruby written by Brian Marick

Apart from using the pickaxe as a reference this is the first book on pure ruby that I have read. One big advantage that this book has is it uses ruby in a different context instead of the “rails way� that I am used to.

Over the last year I have been writing more and more scripts; mostly in Ruby and Bash. I have written everything from basic copy scripts to a more complicated website crawler called the harvester. I wont speak any more about the harvester as I am not proud of its application! It was great to read a book about the black art of scripting and get a strong grasp of how Ruby can be utilised in this context.

I thoroughly recommend getting this book and reading it cover to cover. The book starts easy then progresses in difficulty so is more of a cover to cover read than a reference. Apart from the chapter on regular expressions which is the most detailed description of ruby regular expressions I have seen to date.

TDD

I am of the mind that TDD is great if you go as far as to start extracting methods to a class. If however, you are just writing a simple single stream script as I mostly do, it is not worthwhile writing tests for something simple and throw-away.

Driving the Browser

There is also the mechanize ruby gem which can be used to build simple crawlers. This is interesting when you think about what is possible. I remember back in the day Alistair Burns and I wrote a bot for planetarion which would login every few hours and then send an email to your phone if you were under attack. We wrote it in PHP4 and it was a fairly dirty script. Nowadays you could do the same in ruby in an embarrassingly little amount of lines.

Modules, Classes and Monkey Patching

Top marks for this book. Buy it if you can.

I bet you have to type the same thing over and over in electronic communication day on day.

Be it signing emails, typing your address or even whole email replies texter is really floating my boat at the moment.

It allows you to abbreviate things into a few keystrokes. So for example in any text entry interface I can type gladdr then enter and it replaces this will my full address.

Add this to the keyboard shortcuts that gmail provides and you are on fire with blazing productivity.

Another cool thing I read in the great prag book Everyday Scripting with Ruby is to devote time everyday to making yourself more efficient. Attempting to remove all the repetitive tasks as much a possible from your everyday “workflow� is doing wonders for what I can accomplish on a day to day basis.

I’ll post a review of Everyday Scripting with Ruby when I’ve finished it.

The version of this document is optimized for Ruby-GetText 1.9.0 and Rails 1.2.

This is hosted here because the ruby manuals server seems to have died. Central documentation would be nice :-p

Introduction

Stand on the shoulders of Giants

So in this tutorial I am going to show you how to effectively use Gettext for all your translation needs in your Ruby on Rails application.

What can Gettext do for you?

• A set of conventions about how programs should be written to support message catalogs.


• A directory and file naming organization for the message catalogs themselves.


• A runtime library supporting the retrieval of translated messages.


• A few stand-alone programs to massage in various ways the sets of translatable strings, or already translated strings.

The only thing you have to do to your program sources is wrap all translatable strings with a method call: gettext(text) or shorter _(text). Example:

notice = ‘Thank you for buying our product.’

notice = _(‘Thank you for buying our product.’)

Preperation is everything—use UTF-8 everywhere

Edit your files with UTF-8 only

set encoding=utf8
set fileencoding=utf8

Feed your database with UTF-8

CREATE TABLE `pages` (
`id` int(10) unsigned NOT NULL auto<em>increment,
`title` varchar(255) default NULL,
`keywords` varchar(255) default NULL,
`description` varchar(255) default NULL,
`block1` text,
`block2` text,
`block3` text,
`block4` text,
`block5` text,
`lang` varchar(10) NOT NULL default &#226;&#8364;&#8482;en</em>EN&#226;&#8364;&#8482;,
`category` varchar(255) default NULL,
`path` varchar(255) default &#226;&#8364;&#732;/&#226;&#8364;&#8482;,
`updated<em>at` datetime default NULL,
`created</em>at` datetime default NULL,
`published<em>at` datetime default NULL,
`layout` varchar(255) default &#226;&#8364;&#732;main.rhtml&#226;&#8364;&#8482;,
`template` varchar(255) default NULL,
`access` tinyint(3) unsigned default &#226;&#8364;&#732;3&#226;&#8364;&#8482;,
`version` int(10) unsigned default &#226;&#8364;&#732;1&#226;&#8364;&#8482;,
`is</em>published` tinyint(3) unsigned default &#226;&#8364;&#732;0&#226;&#8364;&#8482;,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 ROW_FORMAT=DYNAMIC;

encoding: UTF8

If you still think you are going to tack on support for UTF-8 later you might reconsider after reading David’s and Jamis’ experiences: Forty-four grueling hours (or Welcome to 37s!) by David Heinemeier Hansson and On the job by Jamis Buck.

If for any reason you need to use anything other than UTF-8 you might want to know that you can use the Iconv module to convert between different character sets. This module should be installed by default on most distributions. If it is not it is usually easy to get. Just be sure to get it if you need charcter set conversion. On Debian you might need a apt-get install libiconv-ruby to get started. Here is a little example stolen from Pickaxe 2 page 686:

$ irb–riconv
>> Iconv.conv(‘ISO-8859-1’, ‘UTF-8’, “ol303251�)
=> “ol351�

Installing Ruby-GetText

$ gem install gettext
Select which gem to install for your platform (…)
1. gettext 1.9.0 (ruby)
2. gettext 1.9.0 (mswin32)
…>

Alternative: If you need the source you can get it from the author’s site: Ruby-GetText-Package. Besides installation instructions you will find a small HOWTO, API Reference and documentation on how to use provided tools.

Check the sample Rails application that is delivered with Ruby-GetText. If you installed via RubyGems it is most likely here: /usr/lib/ruby/gems/1.8/gems/gettext-1.9.0/samples/rails/, but it could be somewhere else depending on where your Ruby is installed. Later I will call that path $RUBYGETTEXTRAILSSAMPLE. So keep this in mind when you read.

Create the “po� directory structure

simplepages@colinux: /home/simplepages/rails/po:
$ d–T
/home/simplepages/rails/po/:
|-myapp.pot
|-de<em>DE/:
| `-myapp.po
|-en</em>GB/:
| `-myapp.po
|-en<em>US/:
| `-myapp.po
|-fr</em>FR/:
| `-myapp.po
|-fr_CH/:
| `-myapp.po
`-ja/:
`-myapp.po

Convert pofiles to mofiles

simplepages@colinux: /home/simplepages/rails/Rakefile
require ‘gettext/utils’
desc “Create mo-files for L10n�
task :makemo do
GetText.create_mofiles(true, “po�, "locale")
end

$ rake makemo

simplepages@colinux: /home/simplepages/rails/locale:
$ d–T
/home/simplepages/rails/locale/:
|-de<em>DE/:
| `-LC</em>MESSAGES/:
| |-myapp.mo
|-en<em>GB/:
| `-LC</em>MESSAGES/:
| |-myapp.mo
|-en<em>US/:
| `-LC</em>MESSAGES/:
| |-myapp.mo
|-fr<em>FR/:
| `-LC</em>MESSAGES/:
| |-myapp.mo
|-fr<em>CH/:
| `-LC</em>MESSAGES/:
| |-myapp.mo
`-ja/:
`-LC_MESSAGES/:
|-myapp.mo

Tools of trade

Gettext

Ruby-GetText and rgettext

ActiveRecord support rgettext extracts all the table names and field names within subclasses of ActiveRecord::Base.

poEdit

Collecting messages

simplepages@colinux: /home/simplepages/rails/Rakefile
desc “Update pot/po files to match new version.�
task :updatepo do
MY<em>APP</em>TEXT<em>DOMAIN = &#226;&#8364;&#339;myapp&#226;&#8364;?
MY</em>APP<em>VERSION = &#226;&#8364;&#339;myapp 1.1.0&#226;&#8364;?
GetText.update</em>pofiles(YOUR<em>APP</em>TEXT<em>DOMAIN,
Dir.glob(&#226;&#8364;&#339;/<strong>/</strong>.{rb,rhtml}&#226;&#8364;?),
MY</em>APP_VERSION)
end

$ rake updatepo

Translating and compiling with and without poEdit

simplepages@colinux: /home/simplepages/rails/po/de_DE:
$ ls
myapp.posimplepages@colinux: /home/simplepages/rails:
$ rake makemo

	
simplepages@colinux: /home/simplepages/rails/locale/de<em>DE/LC</em>MESSAGES:

$ ls

myapp.mo

See Documents for Translators for more details to translate the po-file.

msgid “"
msgstr "�
“POT-Creation-Date: 2007-02-19 17:15-0000n�
“PO-Revision-Date: 2003-04-03 10:49--500n�
“Last-Translator: Alastair Brunton n�
“Language-Team: fr_FR n�
“MIME-Version: 1.0n�
“Content-Type: text/plain; charset=UTF-8n�
“Content-Transfer-Encoding: 8bitn�

Implementing Ruby-GetText into your rails app

Including Ruby-GetText

simplepages@colinux: /home/simplepages/rails/app/controllers/application.rb:
require &#226;&#8364;&#732;gettext/rails&#226;&#8364;&#8482;class ApplicationController < ActionController::Base
init<em>gettext &#226;&#8364;&#339;myapp&#226;&#8364;?
	
#init</em>gettext &#226;&#8364;&#339;myapp&#226;&#8364;?, &#226;&#8364;&#339;UTF-8&#226;&#8364;?, &#226;&#8364;&#339;text/html&#226;&#8364;? # <= Also you can set charset and content_type.

end

Selecting the scope of your textdomain

1. If you call bindtextdomain in ApplicationControler, the textdomain applies to the entire application.


2. If you call bindtextdomain in any other controller with a different textdomain, this textdomain only applies to this specific controller. For example if you call a different textdomain in myapp<em>controller.rb</em> it will only be used in myappcontroller.rb.

The textdomains are applied to each controller/view/model.

Choosing the right language on every request

Ruby-GetText chooses the current language by following these rules in the given order:

1. the first value passed to the ‘locale’ parameter of GetText.bindtextdomain method call


2. ‘lang’ value of QUERY_STRING


3. ‘lang’ value of the Cookie


4. the value of HTTP<em>ACCEPT</em>LANGUAGE


5. or default ‘en’ (English).

The script $RUBYGETTEXT<em>RAILS</em>SAMPLE/vendor/plugins/lang_helper.rb is a sample that selects locale using the cookie value of the user.

class CookieController < ApplicationController
def set<em>cookie
code = params[:id]
cookies[:lang] =
{
:value => code,
:expires => Time.now + 1.year,
:path => &#226;&#8364;&#732;/&#226;&#8364;&#8482;
}
redirect</em>to home_url
end
end

Using the Locale in your templates

“http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd�>

= Locale.charset %>" />
…

Have your own textdomain for plugin applications

simplepages@colinux: /home/simplepages/rails/vendor/plugins/gettext/lib/gettext_plugin.rb:
require ‘gettext/rails’module LangHelper
	

		
If you need to bind yet another textdomain to your plugin.
			
Separate the name space from ActionView::Base/ApplicationController.

class YetanotherTextDomain

include GetText::Rails
	

	
def initialize
	

		
You need to call bindtextdomain in an instance of ActionView::Base.
			
The locale is used a same values which define ApplicationController#init<em>gettext instead of
			
the textdomain.

bindtextdomain("gettext</em>plugin")

end
	

	
def show<em>language(actionview)

langs = ["en"] + Dir.glob(File.join(RAILS</em>ROOT,&#226;&#8364;&#339;locale/*&#226;&#8364;?)).collect{|item| File.basename(item)}

langs.delete("CVS")

langs.uniq!

ret = &#226;&#8364;&#339;

<h4>&#226;&#8364;? + <em>&#226;&#8364;&#339;Select locale&#226;&#8364;?) + &#226;&#8364;&#339;</em></h4>

<em>&#226;&#8364;?

langs.sort.each do |lang|

ret << actionview.link</em>to(&#226;&#8364;&#339;#{lang}]&#226;&#8364;?, :action => &#226;&#8364;&#339;cookie_locale&#226;&#8364;?, :lang => lang)

end

ret

enddef cookie_locale(cookies, flash, params)

cookies["lang"] = params["lang"]

flash[:notice] = _(&#226;&#8364;&#732;Cookie "lang" is set: %s&#226;&#8364;&#8482;) % params["lang"]

end

end

	

		
This function shows supported languages with link to set cookie
			
action (cookie<em>locale).

def show</em>language

YetanotherTextDomain.new.show_language(self)

end
	

	

		
This function is called when the language link is set.

def cookie<em>locale

YetanotherTextDomain.new.cookie</em>locale(cookies, flash, params)

redirect_to :action => &#226;&#8364;&#732;list&#226;&#8364;&#8482;

end

end

Conclusion

You can now easily start to translate your application into all the different languages you want. I hope this guide helps you to get started. There are certainly many more aspects of internationalization that you will have to learn and apply. Remember that this is only one of many possible ways to do it. If you find any mistakes, shortcomings or have good suggestions on how to improve this guide I would be more than happy to hear from you.

If you want you can download the original Textile document, make modifications and send them back to me. I will be sure to include you in the credits section.

Sascha Ebach
se at digitale-wertschoepfung dot de

Credits

• David Heinemeier Hansson for creating the best web application framework that has ever existed P-E-R-I-O-D


• Masao Mutoh–The Author of Ruby-GetText: mutoh at highway dot ne dot jp. Thanks to Masao for extending the old version and making it more flexible.


• Alastair Brunton for providing some sorely needed modifications to this article.

Author

Appendix A: Downloads

Used files

/home/simplepages/using-gettext-with-rails/:
|-app/:
| `-controllers/:
| `-application.rb (the ApplicationController with the .init<em>gettext method)
`-po/: (sample directory structure)
|-de</em>DE/:
|-en<em>GB/:
`-en</em>US/: