1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
|
<?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>
|
