This eBook covers:

• Why bother internationalizing in the first place?
• The Rails 2.2 API for internationalization
• How to internationalize your Rails application
• How to get your application translated with minimal pain
• Using Google Translate to get quick, cheap translations of your Ruby on Rails application (and why this is important, even with a mediocre-quality translation).
• And more!

So don’t wait–download it now and get your Ruby on Rails application internationalized today! (Really, it takes less than an hour for the entire process.)

Huh? REST_AUTH_SITE_KEY? Some googling revealed fairly little information. After some digging, though, the pieces fell into place; so what follows is a (hopefully thorough-enough) explanation.

First of all, to generate a secret key, just use the “secret” rake command:

rake secret

This will generate a sufficiently-long, sufficiently-strong key. And you’re done. Restful Authentication is happy.

Interestingly enough, if you look in config/environment.rb, under config.action_controller.session, there’s something called “secret.” And this is the very thing that spurned the creation of the secret rake task.

So what is this secret? And can you reuse the same secret for your session? (The answer is “probably yes,” but I’m not 100% sure what the implications are–since it’s impossible for end-users to know either or both secret keys.)

Some time ago (in Rails 2.0), they changed the way they handle sessions, so that Rails stores sessions on the client side. Isn’t this a security risk? Yes! So they implemented this secret-key (the one in environment.rb), so that the client-side session is encrypted–using the secret key.

“But wait,” the security experts cry, “can’t you still crack the key by brute-forcing it (by testing every possible combination of characters)? Yes! But given a sufficiently large-enough and convulted enough (i.e. mix of letters and numbers) key, this is computationally infeasible (it’ll take millions of years to try all the combinations).

And that’s what rake secret is for–to generate a strong enough, long enough key, to keep your session state safe.

So, again–Restful Authentication needs a secure key. So generate it with rake secret. It’s strong enough that you don’t need to worry about it being cracked. (It generates a 128-character key, there are 1.61 x 10¹⁹⁹ possible combinations–that’s with 199 zeros.)

Resources:

• Rails 2.0 cookies – Ruby on Rails Security Project


ruby script/generate model Post
ruby script/generate controller Post


After which, you go in and edit the views for post to create the form with the title, body, etc. All manually.

The great news is that there’s a shortcut! This shortcut:

1. Creates the model class
2. Creates the views and controller
3. Populates the new and edit views with the class’s fields
4. Creates the schema migration with the class’s fields

How do you do it? Surprisingly easy:

ruby script/generate scaffold Post title:string body:text

Rails then takes those fields and populates them everywhere necessary. Brilliant! Easy! Use it, it’ll save you a few minutes of time (which adds up every time you need to create another class)!


class Player
attr_accessor :x, :y
end


What does this mean? It means you can do things like:


p = Player.new
p.x = 2;
p.y += 3;
puts "Player is at (#{p.x}, #{p.y})."


i.e. you get the ability to both read and write to x and y, for FREE–without any additional code. Smooth!

But, if you’re like me, you will probably reach a point where you want to add some member variables, but not make them publically accessible. How do you do it?

The answer is to use the @name convention, like so:


class Player
def initialize(x, y)
@x = x
@y = y
end
end


Unlike the attr_accessor code above, this does NOT allow you to do things like:


p = Player.new(3, 4)
puts "Player is at #{p.x}, #{p.y}" # raises an error: X and Y don't exist


But, as I mentioned, that’s what this is for–creating private member variables.

Also, realize that in Ruby, objects are very dynamic–you can add properties on the fly! We didn’t explicitly “declare” x and y anywhere in our Player class; yet we can access them.

And that, in a nutshell, is private member variables. One last thing to note–you can almost think of attr_accessor :some_thing as equivalent to:


class Whatever
@some_thing = nil
def some_thing
return @some_thing
end
def some_thing=(value)
@some_thing = value
end
end


But of course, all this is free by using attr_accessor. So use it!

Before we dive into the implementation, we’re going to discuss a bit of the evolution of this solution.

In the Good Old Days (possibly before the Internet was widespread in usage), applications hard-coded their strings. So if you had a login form/box/control/screen/something, you’d have something like:


Login:
Password:


What, then, happens if you want to translate your application into another language like French? You could always hard-code the new values, and maintain a second version; but that’s expensive to maintain.

Then an idea emerged–how about storing the strings in a file somewhere, and using some sort of class to get the strings?

So you might have a class like this:


class LanguagePack
def get_string(string_key)
# open up a text file specified in LanguageManager.language
# look for the line with string_key
# return the actual text
end
end


This class contains the strings. Accompanying this would be the strings file, like so:


# en.txt
password = Password:
login = Login:


To obtain strings, you ask the LanguageManager, like so:


class LanguageManager

def get_string(key)
LanguagePack.get_string(key)
end
end


So you can do things like this:


LanguageManager.get_string("password") # => "Password: "
LanguageManager.language = "fr" # use French, search fr.txt
LanguageManager.get_string("password") # => "Mot de Passe: "


As you can see, changing languages is easy–just call LanguageManager.language = fr", for example, to use French. C’est bon!

Your form would then be:


<%= LanguageManager.get_string(login) %>
<%= LanguageManager.get_string(password) %>


And this is precisely how Rails 2.2 handles internationalization! The above form is written as:


<%= I18n.t :login %>
<%= I18n.t :password %>


Why? Because I18n.t takes a string key, and returns the text, like so:


I18n.t("login") => "Login: "
I18n.t("password") => "Password: "


Where are the actual keys and strings stored? They’re inside config/locales/LANGCODE.yml. For example, English keys (since English is the default language) are stored in en.yml.

When you invoke the rails command to build a new app, by default, en.yml will have these contents:


# Sample localization file for English. Add more files in this directory for other locales.
# See http://github.com/svenfuchs/rails-i18n/tree/master/rails%2Flocale for starting points.

en:
hello: "Hello world"


You can easy add new strings; for our input form, we’d use something like:


login: "Login: "
password: "Password: "
# ...


And so on. Also, note that in your environment.rb file, there’s a new (commented-out) line, like so:

# config.i18n.default_locale = :de

You can uncomment this to set the default locality to German. Or French. Or Japanese. Or Arabic. Or whatever you want!

Also, what about templated strings–like “Hello, <your name>?” The solution is something well-used in different programming languages–simply use a token in your string, and spcify the value on-the-fly, like so:


# in en.yml
greeting: Hello, {first_name}!

# in the code
<%= I18n.t :greeting, :first_name => "Muhammad" # => Hello, Muhammad!


Finally, how do you change the locale? By specifying I18n.locale, like so:

I18n.locale = "de-DE" # German

There’s more to it than this, but we’ll leave it at this for now. So enjoy!

And don’t forget the key lesson of this whole shpiel–internationalize your application! Gone are the days of relying on just one language! The web is too big! (And your users will love you for it!)

What does this mean?

Prior to Rails 2.1, when you added a migration, the number would be a simple three-digit number, like so.


ruby script/generate migration create_some_table
=> create db/migrate/008_create_some_table


Imagine, now, you have a multi-developer environment. Jack’s next task is to create a migration that populates some hello-world data; so he does this:


ruby script/generate migration populate_hello_world_data
=> create db/migrate/008_populate_hello_world_data


His local application sees only 7 migrations, so it labels the next migration as 008.

Salman, on the other hand, has another task–to add created_on and updated_on fields to every single table; so he does this:


ruby script/generate migration add_created_and_updated_fields
=> create db/migrate/008_add_created_and_updated_fields


His local application sees only 7 migrations–Jack didn’t check his migration in yet! So when both of them are checked in, Rails gets confused–it sees two migrations numbered 007.

Enter UTC-timestamped migrations. Instead of a number, Rails applies a timestamp, like so:


=> create db/migrate/20081121203844_some_migration


Notice the timestamp instead of the number. This is good–it means unless two developers create a migration at the exact same second, they’ll have different timestamps. (Really, don’t argue this point–it’s easy enough to resolve this if it becomes a conflict, or to shout out “Incoming migration!” when you’re creating a migration.)

Unfortunately, for the rest of us single-developer Rails coders who don’t need UTC-timestamped migrations (or don’t know how to specify a specific version–whatever happened to rake db:migrate version=7?), you can force the old-school migration numbering system, by adding this one line to your environment.rb file:

config.active_record.timestamped_migrations = false

So enjoy! Use these new timestamped migrations if you need them–personally, I find the older migration system easier to manage. But I guess it’s a matter of choice, since I don’t need to worry about migration conflicts.


(1..5).each do |i|
puts i
end


This will print:

1
2
3
4
5


But how about going backwards? Can you do this?


(5..1).each do |i|
puts i
end


No! This won’t print anything out! Boo!

Edit: The solution is, happily, as easy as:

5.downto(1).do |i|
puts i
end


Props out to Wayne Conrad for mentioning it in the comments! In any case, you can read on to see a discussion of some other solutions to this problem–solutions that will work if you don’t know if you’re going to be counting up or counting down.

Ok, so you might do this, instead:


count = 5
while count > 0
puts count
count -= 1
end


Ok, that’ll work. But what if you have two variables, x and y, and you want to iterate from x and y–except you never know if x is less than y or greater than y? (If x is less than y, you can use the usual (x..y).each do |i|, but if not, what then?)

There are a couple of ways you can tackle this–one is swapping, and the other is using min/max, and we discuss the reverse series method.

Swapping means swapping x and y if x > y, like so:


x = #...
y = #...

(x..y).each do #...


This is a great solution. Sometimes, though, it doesn’t work–like in my case, I had an issue where I go from x to y, and then from y to some other value. Swapping just destroys the second part of the process.

Which brings us to solution two–using min/max functions (which, incidentally, don’t come built-in to Ruby). So you would write:


(min(x, y)..max(x, y)).each do #...


And this will iterate properly, without destroying the values of x and y. Of course, you can define min/max as:


def min(a, b)
return b unless a < b
return a
end



def max(a, b)
return b unless a > b
return a
end


And you can use this solution. AND, if you don't know if x is greater than or less than y, then this solution will STILL work! Yay!

BUT! this solution still iterates forward! If that's a problem, you can try solution three, the reverse series. Observe:


steps = y - x
while (steps > 0)
i = y - steps #(y, y-1, y-2 ... x)
# do something for step i
end


This iterates backwards; the value of i is y, then y-1, then y-2, and so on, up to x. (Or, as mentioned before, you can use downto.)

Phew! So that covers a few different ways of iterating backwards; use whatever works for your needs.

What does eval do? Quite simply, you pass in some Ruby code in a string, and it’ll evaluate it. Observe:


eval "puts 2+2" # => 4
eval "'hello world!'.upcase # => HELLO WORLD


Clearly, this is useful stuff–you can pass in arbitrary code, even assemble your strings on the fly for truly complicated code.

But, eval is a dangerous tool–because it can execute arbitrary code. For example, if you have some code like this:


input = # ... read from some form
eval input
# ...


Some clever script kiddie will send the input system 'rm -rf *', you can kiss your application goodbye. And your family photo-collection. And your MP3 collection. And your hard-drive.

Some people brand eval as an “evil,” “insidious,” “destructive” function. Which is true–it has destructive potential. That’s why you need to sanitize your input. Don’t just send it as-is. Don’t risk it.

On the other hand, eval has a lot of tricky uses for things you might not otherwise be able to do. For example, how would you create a generic “shutdown hook” system for your Ruby application? other programming languages have pointers–in .NET, for example, you can accumulate a collection of pointers, and run those. What can you do in Ruby? You can accumulate a collection of strings to eval!


shutdown_hooks = ["Logger.write 'normal termination'", "Logger.close", "DatabaseConnector.close"]


Voila! You can iterate through them and execute them, just like any set of pointers in other languages.

To recap:

• eval is merely a tool. It can be used, and abused, like any tool.
• Use eval as necessary, but avoid it if possible.
• Sanitize your input! Don’t risk it! Script kiddies abound!

In other programming languages, one of the concerns raised with reflection is that it’s a “heavy” process. How does Ruby stack up? If you know, share it in the comments!


/*
This is a block comment. You can put whatever you want here.
Even ASCII art! For REAL! o[+++]XXXXXXXXXXXX>
*/
// ...


But what about Ruby?

Ruby has two special tags that you use: =begin and =end. So your Ruby comment would look like this:


=begin
This function returns the minimum of A or B.
For example, if A is 3 and B is 7, it'll return 3.
=end
def self.min(a, b)
# ...
end


Yes, yes! It’s easy!

Wait! What’s that, you say? You say it doesn’t work? Well, that’s tragic–and in fact, it happened to me, too. The key is that these tokens cannot be preceded by whitespace. If they are, it won’t work.

What? Ghetto, you say? Well, tough luck, my friend–this is how Ruby deals with block comments. Just use it, OK? It’s easier than commenting out 130+ lines of code one by one. (Or if you have an IDE that does it in one-shot, great, even better!)

And that’s Ruby comment blocks! Simple!