vendor/plugins/gibberish/README

   1 = Gibberish
   2
   3 Yet another localization library.  Maybe with the most agreeable API?
   4
   5 = Usage
   6
   7 It's simple.  Your default language, by default, is English (:en).
   8
   9   >> "Hey there!"[:hey]
  10   => "Hey there!"
  11
  12 Gibberish looks in RAILS_ROOT/lang/*.yml for translation files.  Say you have RAILS_ROOT/lang/es.yml,
  13 right?  Gibberish will detect that you know about the :es language and will serve up translations
  14 defined in that file if requested to do so.
  15
  16 Here's a real simple example file (it's just "key: translation"):
  17
  18   $ cat lang/es.yml
  19   hey: ¡Hey allí!
  20
  21 And, as follows, a real simple example session:
  22
  23   >> "Hey there!"[:hey]
  24   => "Hey there!"
  25   >> Gibberish.current_language
  26   => :en
  27   >> Gibberish.current_language = :es
  28   => :es
  29   >> "Hey there!"[:hey]
  30   => "¡Hey allí!"
  31   >> Gibberish.current_language = nil
  32   => nil
  33   >> "Hey there!"[:hey]
  34   => "Hey there!"
  35
  36 It even works with simple interpolation:
  37
  38   >> "Hey, {name}!"[:hey_name, 'Chris']
  39   => "Hey, Chris!"
  40   >> "{name} is from {place}"[:hey_place, 'Chris', 'the Dreamworld']
  41   => "Chris is from the Dreamworld"
  42
  43 Notice we don't use hashes (#) like normal Ruby interpolation.  Also, the names of the variables
  44 in the brackets don't really mean much.  Interpolation is done in order -- the first argument replaces
  45 the first variable in brackets, the second the second, etc.
  46
  47 This of course works with your translations:
  48
  49   $ cat lang/es.yml
  50   hey: ¡Hey allí!
  51   hey_name: ¡Hola {name}!
  52
  53   >> "Hey, {name}!"[:hey_name, 'Chris']
  54   => "Hey, Chris!"
  55   >> Gibberish.current_language = :es
  56   => :es
  57   >> "Hey, {name}!"[:hey_name, 'Cristóbal']
  58   => ¡Hola Cristóbal!
  59
  60 Neat.  What other methods do we get?
  61
  62 The classic around_filter:
  63
  64   class ApplicationController < ActionController::Base
  65     around_filter :set_language
  66
  67   private
  68     def set_language
  69       Gibberish.use_language(session[:language]) { yield }
  70     end
  71   end
  72
  73 For the duration of the block, :es is set as the language of choice.  After the block is run everything
  74 returns to normal.  Rad.
  75
  76 Finally, some checking methods, if you need them:
  77
  78   >> Gibberish.default_language?
  79   => true
  80   >> Gibberish.current_language = :es
  81   => :es
  82   >> Gibberish.current_language
  83   => :es
  84   >> Gibberish.default_language?
  85   => false
  86
  87 Languages are loaded by default at Rails startup.  In dev mode, language YAML files are reloaded when
  88 modified.  No need to reboot the server.
  89
  90   >> Gibberish.load_languages!
  91   => [:es, :fr, :de, :kl]
  92   >> Gibberish.languages
  93   => [:es, :fr, :de, :kl]
  94
  95 More as it's needed.
  96
  97 = Warning
  98
  99 By default, Ruby returns nil when a symbol is passed to String's [] method.  Some of Rails, it seems, depends
 100 on this behavior.  Yes, I am changing !!core Ruby behavior!!  The humanity!
 101
 102 To deal with this assumption, Gibberish has a reserved_keys array.  It, by default, contains :limit (so Rails
 103 migrations don't explode on you.)  To add to this array, just pass it more keys:
 104
 105   >> Gibberish.add_reserved_key :another_key
 106   => [:limit, :another_key]
 107   >> Gibberish.add_reserved_keys :more, :keys
 108   => [:limit, :another_key, :more, :keys]
 109
 110 You've been warned.  It really shouldn't affect you, though.
 111
 112 >> Chris Wanstrath
 113 => chris[at]ozmm[dot]org