480 lines
17 KiB
HTML
480 lines
17 KiB
HTML
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
||
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||
|
|
<head>
|
||
|
|
<title>File: README</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
||
|
|
<meta http-equiv="Content-Script-Type" content="text/javascript" />
|
||
|
|
<link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
|
||
|
|
<script type="text/javascript">
|
||
|
|
// <![CDATA[
|
||
|
|
|
||
|
|
function popupCode( url ) {
|
||
|
|
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
|
||
|
|
}
|
||
|
|
|
||
|
|
function toggleCode( id ) {
|
||
|
|
if ( document.getElementById )
|
||
|
|
elem = document.getElementById( id );
|
||
|
|
else if ( document.all )
|
||
|
|
elem = eval( "document.all." + id );
|
||
|
|
else
|
||
|
|
return false;
|
||
|
|
|
||
|
|
elemStyle = elem.style;
|
||
|
|
|
||
|
|
if ( elemStyle.display != "block" ) {
|
||
|
|
elemStyle.display = "block"
|
||
|
|
} else {
|
||
|
|
elemStyle.display = "none"
|
||
|
|
}
|
||
|
|
|
||
|
|
return true;
|
||
|
|
}
|
||
|
|
|
||
|
|
// Make codeblocks hidden by default
|
||
|
|
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
|
||
|
|
|
||
|
|
// ]]>
|
||
|
|
</script>
|
||
|
|
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<div id="fileHeader">
|
||
|
|
<h1>README</h1>
|
||
|
|
<table class="header-table">
|
||
|
|
<tr class="top-aligned-row">
|
||
|
|
<td><strong>Path:</strong></td>
|
||
|
|
<td>README
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr class="top-aligned-row">
|
||
|
|
<td><strong>Last Update:</strong></td>
|
||
|
|
<td>Sun May 28 15:19:38 E. Australia Standard Time 2006</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- banner header -->
|
||
|
|
|
||
|
|
<div id="bodyContent">
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<div id="contextContent">
|
||
|
|
|
||
|
|
<div id="description">
|
||
|
|
<h1>About</h1>
|
||
|
|
<h3>Preface</h3>
|
||
|
|
<p>
|
||
|
|
I originally started designing this on weekends and after work in 2005. We
|
||
|
|
started to become very interested in Rails at work and I wanted to get some
|
||
|
|
experience with ruby with before we started using it full-time. I
|
||
|
|
didn’t have very many ideas for anything interesting to create so,
|
||
|
|
because we write a lot of multilingual webapps at my company, I decided to
|
||
|
|
write a localization library. That way if my little hobby project developed
|
||
|
|
into something decent, I could at least put it to good use. And here we are
|
||
|
|
in 2006, my little hobby project has come a long way and become quite a
|
||
|
|
useful piece of software. Not only do I use it in production sites I write
|
||
|
|
at work, but I also prefer it to other existing alternatives. Therefore I
|
||
|
|
have decided to make it publicly available, and I hope that other
|
||
|
|
developers will find it useful too.
|
||
|
|
</p>
|
||
|
|
<h3>About</h3>
|
||
|
|
<p>
|
||
|
|
<a href="../classes/GLoc.html">GLoc</a> is a localization library. It
|
||
|
|
doesn’t aim to do everything l10n-related that you can imagine, but
|
||
|
|
what it does, it does very well. It was originally designed as a Rails
|
||
|
|
plugin, but can also be used for plain ruby projects. Here are a list of
|
||
|
|
its main features:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>Lightweight and efficient.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Uses file-based string bundles. Strings can also be set directly.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Intelligent, cascading language configuration.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Create flexible rules to handle issues such as pluralization.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Includes a ActionController filter that auto-detects the client language.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Works perfectly with Rails Engines and allows strings to be overridden just
|
||
|
|
as easily as controllers, models, etc.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Automatically localizes Rails functions such as distance_in_minutes,
|
||
|
|
select_month etc
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Supports different charsets. You can even specify the encoding to use for
|
||
|
|
each language seperately.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Special Rails mods/helpers.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<h3>What does <a href="../classes/GLoc.html">GLoc</a> mean?</h3>
|
||
|
|
<p>
|
||
|
|
If you’re wondering about the name "<a
|
||
|
|
href="../classes/GLoc.html">GLoc</a>", I’m sure you’re not
|
||
|
|
alone. This project was originally just called "Localization"
|
||
|
|
which was a bit too common, so when I decided to release it I decided to
|
||
|
|
call it "Golly’s Localization Library" instead (Golly is my
|
||
|
|
nickname), and that was long and boring so I then abbreviated that to
|
||
|
|
"<a href="../classes/GLoc.html">GLoc</a>". What a fun story!!
|
||
|
|
</p>
|
||
|
|
<h3>Localization helpers</h3>
|
||
|
|
<p>
|
||
|
|
This also includes a few helpers for common situations such as displaying
|
||
|
|
localized date, time, "yes" or "no", etc.
|
||
|
|
</p>
|
||
|
|
<h3>Rails Localization</h3>
|
||
|
|
<p>
|
||
|
|
At the moment, unless you manually remove the <tt>require
|
||
|
|
‘gloc-rails-text’</tt> line from init.rb, this plugin overrides
|
||
|
|
certain Rails functions to provide multilingual versions. This
|
||
|
|
automatically localizes functions such as select_date(),
|
||
|
|
distance_of_time_in_words() and more… The strings can be found in
|
||
|
|
lang/*.yml. NOTE: This is not complete. Timezones and countries are not
|
||
|
|
currently localized.
|
||
|
|
</p>
|
||
|
|
<h1>Usage</h1>
|
||
|
|
<h3>Quickstart</h3>
|
||
|
|
<p>
|
||
|
|
Windows users will need to first install iconv. <a
|
||
|
|
href="http://wiki.rubyonrails.com/rails/pages/iconv">wiki.rubyonrails.com/rails/pages/iconv</a>
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>Create a dir "#{RAILS_ROOT}/lang"
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Create a file "#{RAILS_ROOT}/lang/en.yml" and write your strings.
|
||
|
|
The format is "key: string". Save it as UTF-8. If you save it in
|
||
|
|
a different encoding, add a key called file_charset (eg.
|
||
|
|
"file_charset: iso-2022-jp")
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Put the following in config/environment.rb and change the values as you see
|
||
|
|
fit. The following example is for an app that uses English and Japanese,
|
||
|
|
with Japanese being the default.
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
GLoc.set_config :default_language => :ja
|
||
|
|
GLoc.clear_strings_except :en, :ja
|
||
|
|
GLoc.set_kcode
|
||
|
|
GLoc.load_localized_strings
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li>Add ‘include <a href="../classes/GLoc.html">GLoc</a>’ to all
|
||
|
|
classes that will use localization. This is added to most Rails classes
|
||
|
|
automatically.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Optionally, you can set the language for models and controllers by simply
|
||
|
|
inserting <tt>set_language :en</tt> in classes and/or methods.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>To use localized strings, replace text such as <tt>"Welcome"</tt>
|
||
|
|
with <tt>l(:welcome_string_key)</tt>, and <tt>"Hello
|
||
|
|
#{name}."</tt> with <tt>l(:hello_string_key, name)</tt>. (Of course
|
||
|
|
the strings will need to exist in your string bundle.)
|
||
|
|
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>
|
||
|
|
There is more functionality provided by this plugin, that is not
|
||
|
|
demonstrated above. Please read the API summary for details.
|
||
|
|
</p>
|
||
|
|
<h3>API summary</h3>
|
||
|
|
<p>
|
||
|
|
The following methods are added as both class methods and instance methods
|
||
|
|
to modules/classes that include <a href="../classes/GLoc.html">GLoc</a>.
|
||
|
|
They are also available as class methods of <a
|
||
|
|
href="../classes/GLoc.html">GLoc</a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
current_language # Returns the current language
|
||
|
|
l(symbol, *arguments) # Returns a localized string
|
||
|
|
ll(lang, symbol, *arguments) # Returns a localized string in a specific language
|
||
|
|
ltry(possible_key) # Returns a localized string if passed a Symbol, else returns the same argument passed
|
||
|
|
lwr(symbol, *arguments) # Uses the default rule to return a localized string.
|
||
|
|
lwr_(rule, symbol, *arguments) # Uses a specified rule to return a localized string.
|
||
|
|
l_has_string?(symbol) # Checks if a localized string exists
|
||
|
|
set_language(language) # Sets the language for the current class or class instance
|
||
|
|
set_language_if_valid(lang) # Sets the current language if the language passed is a valid language
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
The <a href="../classes/GLoc.html">GLoc</a> module also defines the
|
||
|
|
following class methods:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
add_localized_strings(lang, symbol_hash, override=true) # Adds a hash of localized strings
|
||
|
|
backup_state(clear=false) # Creates a backup of GLoc's internal state and optionally clears everything too
|
||
|
|
clear_strings(*languages) # Removes localized strings from memory
|
||
|
|
clear_strings_except(*languages) # Removes localized strings from memory except for those of certain specified languages
|
||
|
|
get_charset(lang) # Returns the charset used to store localized strings in memory
|
||
|
|
get_config(key) # Returns a GLoc configuration value (see below)
|
||
|
|
load_localized_strings(dir=nil, override=true) # Loads localized strings from all YML files in a given directory
|
||
|
|
restore_state(state) # Restores a backup of GLoc's internal state
|
||
|
|
set_charset(new_charset, *langs) # Sets the charset used to internally store localized strings
|
||
|
|
set_config(hash) # Sets GLoc configuration values (see below)
|
||
|
|
set_kcode(charset=nil) # Sets the $KCODE global variable
|
||
|
|
similar_language(language) # Tries to find a valid language that is similar to the argument passed
|
||
|
|
valid_languages # Returns an array of (currently) valid languages (ie. languages for which localized data exists)
|
||
|
|
valid_language?(language) # Checks whether any localized strings are in memory for a given language
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
<a href="../classes/GLoc.html">GLoc</a> uses the following configuration
|
||
|
|
items. They can be accessed via <tt>get_config</tt> and
|
||
|
|
<tt>set_config</tt>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
:default_cookie_name
|
||
|
|
:default_language
|
||
|
|
:default_param_name
|
||
|
|
:raise_string_not_found_errors
|
||
|
|
:verbose
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
The <a href="../classes/GLoc.html">GLoc</a> module is automatically
|
||
|
|
included in the following classes:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
ActionController::Base
|
||
|
|
ActionMailer::Base
|
||
|
|
ActionView::Base
|
||
|
|
ActionView::Helpers::InstanceTag
|
||
|
|
ActiveRecord::Base
|
||
|
|
ActiveRecord::Errors
|
||
|
|
ApplicationHelper
|
||
|
|
Test::Unit::TestCase
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
The <a href="../classes/GLoc.html">GLoc</a> module also defines the
|
||
|
|
following controller filters:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
autodetect_language_filter
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
<a href="../classes/GLoc.html">GLoc</a> also makes the following change to
|
||
|
|
Rails:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>Views for ActionMailer are now #{view_name}_#{language}.rb rather than just
|
||
|
|
#{view_name}.rb
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>All ActiveRecord validation class methods now accept a localized string key
|
||
|
|
(symbol) as a :message value.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li><a
|
||
|
|
href="../classes/ActiveRecord/Errors.html#M000039">ActiveRecord::Errors.add</a>
|
||
|
|
now accepts symbols as valid message values. At runtime these symbols are
|
||
|
|
converted to localized strings using the current_language of the base
|
||
|
|
record.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li><a
|
||
|
|
href="../classes/ActiveRecord/Errors.html#M000039">ActiveRecord::Errors.add</a>
|
||
|
|
now accepts arrays as arguments so that printf-style strings can be
|
||
|
|
generated at runtime. This also applies to the validates_* class methods.
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
Eg. validates_xxxxxx_of :name, :message => ['Your name must be at least %d characters.', MIN_LEN]
|
||
|
|
Eg. validates_xxxxxx_of :name, :message => [:user_error_validation_name_too_short, MIN_LEN]
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li>Instances of ActiveView inherit their current_language from the controller
|
||
|
|
(or mailer) creating them.
|
||
|
|
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>
|
||
|
|
This plugin also adds the following rake tasks:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
* gloc:sort - Sorts the keys in the lang ymls (also accepts a DIR argument)
|
||
|
|
</pre>
|
||
|
|
<h3>Cascading language configuration</h3>
|
||
|
|
<p>
|
||
|
|
The language can be set at three levels:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
1. The default # GLoc.get_config :default_language
|
||
|
|
2. Class level # class A; set_language :de; end
|
||
|
|
3. Instance level # b= B.new; b.set_language :zh
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
Instance level has the highest priority and the default has the lowest.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Because <a href="../classes/GLoc.html">GLoc</a> is included at class level
|
||
|
|
too, it becomes easy to associate languages with contexts. For example:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
class Student
|
||
|
|
set_language :en
|
||
|
|
def say_hello
|
||
|
|
puts "We say #{l :hello} but our teachers say #{Teacher.l :hello}"
|
||
|
|
end
|
||
|
|
end
|
||
|
|
</pre>
|
||
|
|
<h3>Rules</h3>
|
||
|
|
<p>
|
||
|
|
There are often situations when depending on the value of one or more
|
||
|
|
variables, the surrounding text changes. The most common case of this is
|
||
|
|
pluralization. Rather than hardcode these rules, they are completely
|
||
|
|
definable by the user so that the user can eaasily accomodate for more
|
||
|
|
complicated grammatical rules such as those found in Russian and Polish (or
|
||
|
|
so I hear). To define a rule, simply include a string in the string bundle
|
||
|
|
whose key begins with "<em>gloc_rule</em>" and then write ruby
|
||
|
|
code as the value. The ruby code will be converted to a Proc when the
|
||
|
|
string bundle is first read, and should return a prefix that will be
|
||
|
|
appended to the string key at runtime to point to a new string. Make sense?
|
||
|
|
Probably not… Please look at the following example and I am sure it
|
||
|
|
will all make sense.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Simple example (string bundle / en.yml)
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
_gloc_rule_default: ' |n| n==1 ? "_single" : "_plural" '
|
||
|
|
man_count_plural: There are %d men.
|
||
|
|
man_count_single: There is 1 man.
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
Simple example (code)
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
lwr(:man_count, 1) # => There is 1 man.
|
||
|
|
lwr(:man_count, 8) # => There are 8 men.
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
To use rules other than the default simply call lwr_ instead of lwr, and
|
||
|
|
specify the rule.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Example 2 (string bundle / en.yml)
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
_gloc_rule_default: ' |n| n==1 ? "_single" : "_plural" '
|
||
|
|
_gloc_rule_custom: ' |n| return "_none" if n==0; return "_heaps" if n>100; n==1 ? "_single" : "_plural" '
|
||
|
|
man_count_none: There are no men.
|
||
|
|
man_count_heaps: There are heaps of men!!
|
||
|
|
man_count_plural: There are %d men.
|
||
|
|
man_count_single: There is 1 man.
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
Example 2 (code)
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
lwr_(:custom, :man_count, 0) # => There are no men.
|
||
|
|
lwr_(:custom, :man_count, 1) # => There is 1 man.
|
||
|
|
lwr_(:custom, :man_count, 8) # => There are 8 men.
|
||
|
|
lwr_(:custom, :man_count, 150) # => There are heaps of men!!
|
||
|
|
</pre>
|
||
|
|
<h3>Helpers</h3>
|
||
|
|
<p>
|
||
|
|
<a href="../classes/GLoc.html">GLoc</a> includes the following helpers:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
l_age(age) # Returns a localized version of an age. eg "3 years old"
|
||
|
|
l_date(date) # Returns a date in a localized format
|
||
|
|
l_datetime(date) # Returns a date+time in a localized format
|
||
|
|
l_datetime_short(date) # Returns a date+time in a localized short format.
|
||
|
|
l_lang_name(l,dl=nil) # Returns the name of a language (you must supply your own strings)
|
||
|
|
l_strftime(date,fmt) # Formats a date/time in a localized format.
|
||
|
|
l_time(date) # Returns a time in a localized format
|
||
|
|
l_YesNo(value) # Returns localized string of "Yes" or "No" depending on the arg
|
||
|
|
l_yesno(value) # Returns localized string of "yes" or "no" depending on the arg
|
||
|
|
</pre>
|
||
|
|
<h3>Rails localization</h3>
|
||
|
|
<p>
|
||
|
|
Not all of Rails is covered but the following functions are:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
distance_of_time_in_words
|
||
|
|
select_day
|
||
|
|
select_month
|
||
|
|
select_year
|
||
|
|
add_options
|
||
|
|
</pre>
|
||
|
|
<h1>FAQ</h1>
|
||
|
|
<h4>How do I use it in engines?</h4>
|
||
|
|
<p>
|
||
|
|
Simply put this in your init_engine.rb
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
GLoc.load_localized_strings File.join(File.dirname(__FILE__),'lang')
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
That way your engines strings will be loaded when the engine is started.
|
||
|
|
Just simply make sure that you load your application strings after you
|
||
|
|
start your engines to safely override any engine strings.
|
||
|
|
</p>
|
||
|
|
<h4>Why am I getting an Iconv::IllegalSequence error when calling <a href="../classes/GLoc.html#M000013">GLoc.set_charset</a>?</h4>
|
||
|
|
<p>
|
||
|
|
By default <a href="../classes/GLoc.html">GLoc</a> loads all of its default
|
||
|
|
strings at startup. For example, calling <tt>set_charset
|
||
|
|
‘iso-2022-jp’</tt> will cause this error because Russian
|
||
|
|
strings are loaded by default, and the Russian strings use characters that
|
||
|
|
cannot be expressed in the ISO-2022-JP charset. Before calling
|
||
|
|
<tt>set_charset</tt> you should call <tt>clear_strings_except</tt> to
|
||
|
|
remove strings from any languages that you will not be using.
|
||
|
|
Alternatively, you can simply specify the language(s) as follows,
|
||
|
|
<tt>set_charset ‘iso-2022-jp’, :ja</tt>.
|
||
|
|
</p>
|
||
|
|
<h4>How do I make <a href="../classes/GLoc.html">GLoc</a> ignore StringNotFoundErrors?</h4>
|
||
|
|
<p>
|
||
|
|
Disable it as follows:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
GLoc.set_config :raise_string_not_found_errors => false
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
<!-- if includes -->
|
||
|
|
|
||
|
|
<div id="section">
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<!-- if method_list -->
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
<div id="validator-badges">
|
||
|
|
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|