vendor/plugins/globalize2/README.textile

   1 h1. Globalize2
   2
   3 Globalize2 is the successor of Globalize for Rails.
   4
   5 It is compatible with and builds on the new "I18n api in Ruby on Rails":http://rails-i18n.org. and adds model translations as well as a bunch of other useful features, such as Locale fallbacks (RFC4647 compliant) and automatic loading of Locale data from defined directory/file locations.
   6
   7 Globalize2 is much more lightweight and modular than its predecessor was. Content translations in Globalize2 use default ActiveRecord features and do not limit any functionality any more.
   8
   9 All features and tools in Globalize2 are implemented in the most unobstrusive and loosely-coupled way possible, so you can pick whatever features or tools you need for your application and combine them with other tools from other libraries or plugins.
  10
  11 h2. Requirements
  12
  13 Rails 2.2 (currently Rails edge)
  14
  15 h2. Installation
  16
  17 To install Globalize2 with its default setup just use:
  18
  19 <pre><code>
  20 script/plugin install git://github.com/joshmh/globalize2.git
  21 </code></pre>
  22
  23 This will:
  24
  25 * activate model translations
  26 * set I18n.load_path to an instance of Globalize::LoadPath
  27 * set I18n.backend to an instance of Globalize::Backend::Static
  28
  29 h2. Configuration
  30
  31 You might want to add additional configuration to an initializer, e.g. config/initializers/globalize.rb
  32
  33 h2. Model translations
  34
  35 Model translations (or content translations) allow you to translate your models' attribute values. E.g.
  36
  37 <pre><code>
  38 class Post < ActiveRecord::Base
  39   translates :title, :text
  40 end
  41 </code></pre>
  42
  43 Allows you to values for the attributes :title and :text per locale:
  44
  45 <pre><code>
  46 I18n.locale = :en
  47 post.title # Globalize2 rocks!
  48
  49 I18n.locale = :he
  50 post.title # גלובאלייז2 שולט!
  51 </code></pre>
  52
  53 In order to make this work, you'll need to add the appropriate translation tables. Globalize2 comes with a handy helper method to help you do this. It's called @create_translation_table!@. Here's an example:
  54
  55 <pre><code>
  56 class CreatePosts < ActiveRecord::Migration
  57   def self.up
  58     create_table :posts do |t|
  59       t.timestamps
  60     end
  61     Post.create_translation_table! :title => :string, :text => :text
  62   end
  63   def self.down
  64     drop_table :posts
  65     Post.drop_translation_table!
  66   end
  67 end
  68 </code></pre>
  69
  70 Note that the ActiveRecord model @Post@ must already exist and have a @translates@ directive listing the translated fields.
  71
  72 h2. Globalize::Backend::Static
  73
  74 Globalize2 ships with a Static backend that builds on the Simple backend from the I18n library (which is shipped with Rails) and adds the following features:
  75
  76 * It uses locale fallbacks when looking up translation data.
  77 * It returns an instance of Globalize::Translation::Static instead of a plain Ruby String as a translation.
  78 * It allows to hook in custom pluralization logic as lambdas.
  79
  80 h2. Custom pluralization logic
  81
  82 The Simple backend has its pluralization algorithm baked in hardcoded. This algorithm is only suitable for English and other languages that have the same pluralization rules. It is not suitable for, e.g., Czech though.
  83
  84 To add custom pluralization logic to Globalize' Static backend you can do something like this:
  85
  86 <pre><code>
  87 @backend.add_pluralizer :cz, lambda{|c|
  88   c == 1 ? :one : (2..4).include?(c) ? :few : :other
  89 }
  90 </code></pre>
  91
  92 h2. Locale Fallbacks
  93
  94 Globalize2 ships with a Locale fallback tool which extends the I18n module to hold a fallbacks instance which is set to an instance of Globalize::Locale::Fallbacks by default but can be swapped with a different implementation.
  95
  96 Globalize2 fallbacks will compute a number of other locales for a given locale. For example:
  97
  98 <pre><code>
  99 I18n.fallbacks[:"es-MX"] # => [:"es-MX", :es, :"en-US", :en]
 100 </code></pre>
 101
 102 Globalize2 fallbacks always fall back to
 103
 104 * all parents of a given locale (e.g. :es for :"es-MX"),
 105 * then to the fallbacks' default locales and all of their parents and
 106 * finally to the :root locale.
 107
 108 The default locales are set to [:"en-US"] by default but can be set to something else. The root locale is a concept borrowed from "CLDR":http://unicode.org and makes sense for storing common locale data which works as a last default fallback (e.g. "ltr" for bidi directions).
 109
 110 One can additionally add any number of additional fallback locales manually. These will be added before the default locales to the fallback chain. For example:
 111
 112 <pre><code>
 113 fb = I18n.fallbacks
 114
 115 fb.map :ca => :"es-ES"
 116 fb[:ca] # => [:ca, :"es-ES", :es, :"en-US", :en]
 117
 118 fb.map :"ar-PS" => :"he-IL"
 119 fb[:"ar-PS"] # => [:"ar-PS", :ar, :"he-IL", :he, :"en-US", :en]
 120 fb[:"ar-EG"] # => [:"ar-EG", :ar, :"en-US", :en]
 121
 122 fb.map :sms => [:"se-FI", :"fi-FI"]
 123 fb[:sms] # => [:sms, :"se-FI", :se, :"fi-FI", :fi, :"en-US", :en]
 124 </code></pre>
 125
 126 h2. Globalize::LoadPath
 127
 128 Globalize2 replaces the plain Ruby array that is set to I18n.load_path by default through an instance of Globalize::LoadPath.
 129
 130 This object can be populated with both paths to files and directories. If a path to a directory is added to it it will look up all locale data files present in that directory enforcing the following convention:
 131
 132 <pre><code>
 133 I18n.load_path << "#{RAILS_ROOT}/lib/locales"
 134
 135 # will load all the following files if present:
 136 lib/locales/all.yml
 137 lib/locales/fr.yml
 138 lib/locales/fr/*.yaml
 139 lib/locales/ru.yml
 140 lib/locales/ru/*.yaml
 141 ...
 142 </code></pre>
 143
 144 One can also specify which locales are used. By default this is set to "*" meaning that files for all locales are added. To define that only files for the locale :es are added one can specify:
 145
 146 <pre><code>
 147 I18n.load_path.locales = [:es]
 148 </code></pre>
 149
 150 One can also specify which file extensions are used. By default this is set to ['rb', 'yml'] so plain Ruby and YAML files are added if found. To define that only *.sql files are added one can specify:
 151
 152 <pre><code>
 153 I18n.load_path.extensions = ['sql']
 154 </code></pre>
 155
 156 Note that Globalize::LoadPath "expands" a directory to its contained file paths immediately when you add it to the load_path. Thus, if you change the locales or extensions settings in the middle of your application the change won't be applied to already added file paths.
 157
 158
 159 h2. Globalize::Translation classes
 160
 161 Globalize2's Static backend as well as Globalize2 model translations return instances of Globalize::Translation classes (instead of plain Ruby Strings). These are simple and lightweight value objects that carry some additional meta data about the translation and how it was looked up.
 162
 163 Model translations return instances of Globalize::Translation::Attribute, the Static backend returns instances of Globalize::Translation::Static.
 164
 165 For example:
 166
 167 <pre><code>
 168 I18n.locale = :de
 169
 170 # Translation::Attribute
 171 title = Post.first.title  # assuming that no translation can be found:
 172 title.locale              # => :en
 173 title.requested_locale    # => :de
 174 title.fallback?           # => true
 175
 176 # Translation::Static
 177 rails = I18n.t :rails     # assuming that no translation can be found:
 178 rails.locale              # => :en
 179 rails.requested_locale    # => :de
 180 rails.fallback?           # => true
 181 rails.options             # returns the options passed to #t
 182 rails.plural_key          # returns the plural_key (e.g. :one, :other)
 183 rails.original            # returns the original translation with no values
 184                           # interpolated to it (e.g. "Hi {{name}}!")
 185 </code></pre>
 186
 187 h2. Missing Translations Log Handler
 188
 189 A simple exception handler that behaves like the default exception handler but additionally logs missing translations to a given log.
 190
 191 Useful for identifying missing translations during testing.
 192
 193 E.g.
 194
 195   require 'globalize/i18n/missing_translations_log_handler
 196   I18n.missing_translations_logger = RAILS_DEFAULT_LOGGER
 197   I18n.exception_handler = :missing_translations_log_handler
 198
 199 To set up a different log file:
 200
 201   logger = Logger.new("#{RAILS_ROOT}/log/missing_translations.log")
 202   I18n.missing_translations_logger = logger