globalize-r5 5.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ce99c169b12c28c24f030dee7f36ffe81ed5d788
+  data.tar.gz: eb032c5d8f3aa55051125f34d53b5013e97c78e0
+SHA512:
+  metadata.gz: 91650619c80ef94c9ce665f3d1e56b7474f8c210f08fe5d2719e45c8dfb40258fcb3e78cb5cf04c7165d29049ebde89f76d3e140480dbb5be9fed8699e469030
+  data.tar.gz: e0e4ae3ed75bfb67e4164bad25c748a96a6c71c4a7f357e7bf50bc5b9ff62c8c239a1d35f72921dd1778c6062a03f87bcb54e3fd014d4552bcccbd8dfda0373d

data/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Globalize Changelog
+
+## 5.1.0 (unreleased)
+
+* Replaced `after_` callbacks with `before_` callbacks and set `autosave: true` by default. [#341](https://github.com/globalize/globalize/pull/341) by [Andrew Volozhanin](https://github.com/scarfacedeb)
+* Add [RequestStore](https://github.com/steveklabnik/request_store) to make Globalize thread-safe again [#420](https://github.com/globalize/globalize/pull/420)
+* Join the translations table when ordering by translated attributes (https://github.com/globalize/globalize/pull/447). (thanks [Thomas Maas](https://github.com/thomasmaas) & [Michal Cichra](https://github.com/mikz)).
+* Add `unique` to `with_translation` to prevent duplicates if fallbacks are defined and the queried locale is not the fallback language. [#489](https://github.com/globalize/globalize/pull/489) by [krisdigital](https://github.com/krisdigital)
+
+## 5.0.1 (2015-02-15)
+
+* Don't touch table when model is loaded. [#412](https://github.com/globalize/globalize/pull/412)
+* Remove handling for locale attribute on parent model [#411](https://github.com/globalize/globalize/pull/411) by awesome [Tekin Suleyman](https://github.com/tekin).
+
+## 5.0.0 (2015-02-03)
+* Added support for Rails 4.2, but removed support for every previous version of Rails.  This is a backward incompatible change, thus the version is now 5.0.0. (thanks [Nico Ritsche](https://github.com/ncri) and others). [#396](https://github.com/globalize/globalize/pull/396).
+
+## 4.0.3 (2014-11-24)
+* Fixes a problem where after dup the dup'd model and the original model shared a translation instance, which means that if you mutate a translated field on the dup and save it, the original becomes a clone of the dup. [#352](https://github.com/globalize/globalize/pull/352).
+* Deprecated `with_required_attributes`, `required_attributes`, and `required_translated_attributes`. `with_translations` no longer invokes `with_required_attributes`. [#355](https://github.com/globalize/globalize/pull/355).
+* Removed all usages of `Thread.local`. [#374](https://github.com/globalize/globalize/pull/374). (thanks [Hubert Lee](https://github.com/hube)).
+* Added `available_locales` method. This duplicates `translated_locales` method, but it doesn't use a separate `DISTINCT` query. [#339](https://github.com/globalize/globalize/pull/339). (thanks [Andrew Volozhanin](https://github.com/scarfacedeb)).
+
+## 4.0.2 (2014-06-29)
+* Use `reflections` class method so `ensure_foreign_key_for` works in AR >= 4.1.2, fixes [#353](https://github.com/globalize/globalize/pull/353).
+* Set `touch:true` on `belongs_to` for the globalized model, fixes [#330](https://github.com/globalize/globalize/pull/330) (thanks [shlensky](https://github.com/shlensky)).
+* Accept optional arguments passed to `where_values_hash`, fixes [#354](https://github.com/globalize/globalize/pull/354) (thanks [felixbuenemann](https://github.com/felixbuenemann)).
+
+## 4.0.1 (2014-03-29)
+* Fix bug where `with_translations` only works if called after `where` in relation chain, fixes [#343](https://github.com/globalize/globalize/issues/343).
+* Use `preload` and `joins` instead of `includes` in `with_translations`, fixes [#329](https://github.com/globalize/globalize/issues/329) (thanks [Andrew Volozhanin](https://github.com/scarfacedeb)).
+* Update `database_cleaner` dependency to 1.2.0.
+* Support use of `first`/`take`/`last` with limit on queries with translated attributes, fixes [#322](https://github.com/globalize/globalize/issues/322) (thanks [prusswan](https://github.com/prusswan)).
+* Ensure that options are always extracted from `attr_names` in `Globalize::ActiveRecord::ActMacro#translates`, PR [#319](https://github.com/globalize/globalize/pull/319) (thanks [Marek](https://github.com/keram)).
+
+## 4.0.0 (2014-01-04)
+* Extract all versioning-related code to separate [globalize-versioning](https://github.com/globalize/globalize-versioning) gem.
+
+## 4.0.0.alpha.5 (2014-01-04)
+* Fix issue where globalize breaks has_many through when model called with `where` (thanks [Paul McMahon](https://github.com/pwim)).
+* Modify dup so that translations are copied, and remove custom clone code to conform to Rails/AR semantics (thanks [Paul McMahon](https://github.com/pwim)).
+
+## 4.0.0.alpha.4 (2013-12-30)
+* Add this changelog.
+* Add contributing guidelines.
+* Group options into more structured methods in act_macro.rb.
+* Remove dynamic finder code from globalize3, no longer used in AR4.
+* Get hash of translated attributes by calling attribute on model, not translation.
+* Define translation readers/writers in separate methods.
+* Test against AR 4.1 and AR 4.0.
+* Switch to minitest-reporters for colouring output from minitest.
+* Remove find_or_instantiator_by_attributes which is no longer used in AR4.
+* Set I18n.available_locales in tests to avoid deprecation message.
+* Reorganize specs into describe blocks to clarify object of specs.
+
+## 4.0.0.alpha.3 (2013-12-18)
+
+* Move ActiveRecord::Relation#where_values_hash patch into globalize relation class to avoid monkeypatching.
+* Add Code Climate Score (thanks [BrandonMathis](https://github.com/BrandonMathis)).
+* Query using Globalize.fallbacks rather than locale only when fetching a record (thanks [@huoxito](https://github.com/huoxito)).
+* Use a module (QueryMethods) rather than a class for overriding functionality of ActiveRecord::Relation.
+* Use ActiveRecord::Relation#extending! to extend ActiveRecord::Base#relation with QueryMethods, works with associations as well.
+
+## 4.0.0.alpha.2 (2013-10-24)
+
+* Add license to gemspec.
+* Update references to ActiveRecord 3 -> ActiveRecord.
+* Replace references to globalize3 with globalize and remove references to ActiveRecord 3.x.
+* Document `3-0-stable` branch in readme.
+* Convert test syntax to MiniTest::Spec.
+* Extract easy accessors functionality, moved to new [globalize-accessors](https://github.com/globalize/globalize-accessors) gem.
+* Check that `first` is not nil before reloading translations, fixes [#282](https://github.com/globalize/globalize/issues/282).
+* Duplicate arguments in query finders before modifying them, fixes [#284](https://github.com/globalize/globalize/issues/284).
+* Add test for `find_or_create_by` with translated attribute.
+
+## 4.0.0.alpha.1 (2013-10-09)
+
+* Initial release of Rails 4-compatible gem.
+
+## 3.1.0 (2014-01-25)
+
+* Backport scope support on uniqueness validation from 4.0, drop support for ActiveRecord < 3.1, fixes [#324](https://github.com/globalize/globalize/issues/324).
+
+## 3.0.5 (2015-04-24)
+
+* Now working properly with the squeel library. (thanks [Toru Mori](https://github.com/torumori)). See [#437](https://github.com/globalize/globalize/pull/437)
+
+## 3.0.4 (2014-01-08)
+
+* Extract all versioning-related code to separate [globalize-versioning](https://github.com/globalize/globalize-versioning) gem.
+
+## 3.0.3 (2013-12-26)
+
+* Ensure that foreign key is always set when saving translations (thanks [Andrew Feng](https://github.com/mingliangfeng)).
+* Patch I18n to add back I18n.interpolate after it was removed (accidentally?) in v0.5.2 (see [svenfuchs/i18n#232](https://github.com/svenfuchs/i18n/issues/232). Hopefully this patch will be temporary.
+* Explicitly test compatibility with FriendlyId to avoid issues like [#306](https://github.com/globalize/globalize/issues/306).
+* Only override ActiveRecord::Base#relation to patch where_values_hash if using AR >= 3.2.1.
+
+## 3.0.2 (2013-12-07)
+
+* Alias `ActiveRecord::Base#relation` and include query method overrides as module, fixes [#306](https://github.com/globalize/globalize/issues/306) and [norman/friendly_id#485](https://github.com/norman/friendly_id/issues/485).
+
+## 3.0.1 (2013-11-07)
+
+* Move `ActiveRecord::Relation#where_values_hash` patch to Globalize-specific Relation class that inherits from `ActiveRecord::Relation` to fix compatibility issue with Squeel ([#288](https://github.com/globalize/globalize/issues/288)).
+* Use FriendlyId pattern for overriding `ActiveRecord::Base#relation` to avoid conflict.
+* Remove `:null => false` condition on reference to parent model in translation table migration, partial fix for [refinery/refinerycms#2450](https://github.com/refinery/refinerycms/issues/2450).
+
+## 3.0.0 (2013-10-24)
+
+* Initial release with new version numbering.

data/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to Globalize
+
+Globalize is a community project, and would not be here today if it were not for the support of the community of [contributors](https://github.com/globalize/globalize/graphs/contributors) that have kept it alive and running. Thank you for your support!
+
+## Bugs
+
+If you find a bug or something is not working as expected, please search through the [github issues](https://github.com/globalize/globalize/issues) and on [stackoverflow](http://stackoverflow.com/questions/tagged/globalize) first. If you cannot find any answers related to your issue, post a new one and we will try to address it as soon as we can. Note that we prioritize Rails 4 issues (`master` branch) over Rails 3 issues (`3-0-stable` branch).
+
+If you also have some idea how to fix the bug, then by all means post a pull request (see below).
+
+## Features
+
+Have an idea for a new feature? Great! Keep in mind though that we are trying to cut down on non-core functionality in the Globalize core and push it to separate extensions, such as [globalize-accessors](https://github.com/globalize/globalize-accessors). If you are proposing something like this, we would prefer you to create a separate repository and gem for it.
+
+If however your feature would improve the core functionality of Globalize, please do submit a PR, preferably to the `master` branch.
+
+## Refactoring
+
+Have some free time? Help us improve our [code climate score](https://codeclimate.com/github/globalize/globalize) by refactoring the codebase. If the tests still pass and the changes seem reasonable, we will happily merge them. As elsewhere, priority always goes to the Rails/AR 4 series (`master` branch).
+
+## Documentation
+
+Globalize needs better documentation. That includes more inline comments explaining clearly what code is doing, as well as reference documentation beyond the [readme](readme.md) -- possibly in the github wiki. Please contact us if you would like to help with documentation.
+
+## Pull Requests
+
+Have a bug fix, code improvement or proposed feature? Do the following:
+
+1. Fork the repository.
+2. Create your feature branch: `git checkout -b my_new_feature`
+3. Commit your changes: `git commit -am 'Add some new feature'`
+4. Push to the branch: `git push origin my_new_feature`
+5. Submit a pull request.
+
+For pull requests to Rails/ActiveRecord 4 version of Globalize (v3.x), post to the `master` branch. For pull requests to the Rails/ActiveRecord 3.x version of Globalize (3.x), post to the `3-0-stable` branch.
+
+When you submit the pull request, Travis CI will run the [test suite](https://travis-ci.org/globalize/globalize) against your branch and will highlight any failures. Unless there is a good reason for it, we do not generally accept pull requests that take Globalize from green to red.

data/Gemfile

@@ -0,0 +1,26 @@
+  source "https://rubygems.org"
+
+gemspec
+
+gem "pry"
+
+eval File.read(File.expand_path("../gemfiles/.gemfile.database-config.rb", __FILE__))
+
+platforms :rbx do
+  gem "rubysl", "~> 2.0"
+  gem "rubinius-developer_tools"
+end
+
+platforms :jruby do
+  if !ENV['TRAVIS'] || ENV['DB'] == 'sqlite3'
+    gem 'activerecord-jdbcsqlite3-adapter', github: "jruby/activerecord-jdbc-adapter"
+  end
+
+  if !ENV['TRAVIS'] || ENV['DB'] == 'mysql'
+    gem 'activerecord-jdbcmysql-adapter', github: "jruby/activerecord-jdbc-adapter"
+  end
+
+  if !ENV['TRAVIS'] || %w(postgres postgresql).include?(ENV['DB'])
+    gem 'activerecord-jdbcpostgresql-adapter', github: "jruby/activerecord-jdbc-adapter"
+  end
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2008-2014 Sven Fuchs, Joshua Harvey, Clemens Kofler, John-Paul
+Bader, Tomasz Stachewicz, Philip Arndt, Chris Salzberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,423 @@
+![Globalize](http://globalize.github.io/globalize/images/globalize.png)
+
+[![Build Status](https://travis-ci.org/globalize/globalize.svg?branch=master)](https://travis-ci.org/globalize/globalize) [![Code Climate](https://codeclimate.com/github/globalize/globalize.svg)](https://codeclimate.com/github/globalize/globalize)
+
+You can chat with us using Gitter:
+
+[![Gitter chat](https://badges.gitter.im/globalize/globalize.svg)](https://gitter.im/globalize/globalize)
+
+Globalize builds on the [I18n API in Ruby on Rails](http://guides.rubyonrails.org/i18n.html)
+to add model translations to ActiveRecord models.
+
+## Requirements
+
+* ActiveRecord >= 4.2.0 (see below for installation with ActiveRecord 3.x)
+* I18n
+
+## Installation
+
+To install the ActiveRecord 4.2.x compatible version of Globalize with its default setup, just use:
+
+```ruby
+gem install globalize
+```
+
+When using bundler put this in your Gemfile:
+
+```ruby
+gem 'globalize', '~> 5.0.0'
+```
+
+To use globalize with Rails 5 add this in your Gemfile
+
+```ruby
+gem 'activemodel-serializers-xml'
+```
+
+To use the version of globalize for ActiveRecord 4.0 or 4.1, specify:
+
+```ruby
+gem 'globalize', '~> 4.0.3'
+```
+
+To use the version of globalize for ActiveRecord 3.1 or 3.2, specify:
+
+````ruby
+gem 'globalize', '~> 3.1.0'
+````
+
+(If you are using ActiveRecord 3.0, use version 3.0: `gem 'globalize', '3.0.4'`.)
+
+The [`3-1-stable` branch](https://github.com/globalize/globalize/tree/3-1-stable) of this repository corresponds to the latest ActiveRecord 3 version of globalize. Note that `globalize3` has been deprecated and you are encouraged to update your Gemfile accordingly.
+
+## Model translations
+
+Model translations allow you to translate your models' attribute values. E.g.
+
+```ruby
+class Post < ActiveRecord::Base
+  translates :title, :text
+end
+```
+
+Allows you to translate the attributes :title and :text per locale:
+
+```ruby
+I18n.locale = :en
+post.title # => Globalize rocks!
+
+I18n.locale = :he
+post.title # => גלובאלייז2 שולט!
+```
+
+You can also set translations with mass-assignment by specifying the locale:
+
+```ruby
+post.attributes = { title: 'גלובאלייז2 שולט!', locale: :he }
+```
+
+In order to make this work, you'll need to add the appropriate translation tables.
+Globalize comes with a handy helper method to help you do this.
+It's called `create_translation_table!`. Here's an example:
+
+Note that your migrations can use `create_translation_table!` and `drop_translation_table!`
+only inside the `up` and `down` instance methods, respectively. You cannot use `create_translation_table!`
+and `drop_translation_table!` inside the `change` instance method.
+
+### Creating translation tables
+
+Also note that before you can create a translation table, you have to define the translated attributes via `translates` in your model as shown above.
+
+```ruby
+class CreatePosts < ActiveRecord::Migration
+  def change
+    create_table :posts do |t|
+      t.timestamps
+    end
+
+    reversible do |dir|
+      dir.up do
+        Post.create_translation_table! :title => :string, :text => :text
+      end
+
+      dir.down do 
+        Post.drop_translation_table!
+      end
+    end
+  end
+end
+```
+
+Also, you can pass options for specific columns. Here’s an example:
+
+```ruby
+class CreatePosts < ActiveRecord::Migration
+  def change
+    create_table :posts do |t|
+      t.timestamps
+    end
+    
+    reversible do |dir|
+      dir.up do
+        Post.create_translation_table! :title => :string,
+          :text => {:type => :text, :null => false, :default => 'abc'}
+      end
+      
+      dir.down do 
+        Post.drop_translation_table!
+      end
+    end
+  end
+end
+```
+
+Note that the ActiveRecord model `Post` must already exist and have a `translates`
+directive listing the translated fields.
+
+## Migrating existing data to and from the translated version
+
+As well as creating a translation table, you can also use `create_translation_table!`
+to migrate across any existing data to the default locale. This can also operate
+in reverse to restore any translations from the default locale back to the model
+when you don't want to use a translation table anymore using `drop_translation_table!`
+
+This feature makes use of `untranslated_attributes` which allows access to the
+model's attributes as they were before the translation was applied. Here's an
+example (which assumes you already have a model called `Post` and its table
+exists):
+
+```ruby
+class TranslatePosts < ActiveRecord::Migration
+  def change
+    reversible do |dir|
+      dir.up do
+        Post.create_translation_table!({
+          :title => :string,
+          :text => :text
+        }, {
+          :migrate_data => true
+        })
+      end
+      
+      dir.down do 
+        Post.drop_translation_table! :migrate_data => true
+      end
+    end
+  end
+end
+```
+
+NOTE: Make sure you drop the translated columns from the parent table after all your data is safely migrated.
+
+To automatically remove the translated columns from the parent table after the data migration, please use option `remove_source_columns`.
+
+```ruby
+class TranslatePosts < ActiveRecord::Migration
+  def self.up
+    Post.create_translation_table!({
+      :title => :string,
+      :text => :text
+    }, {
+      :migrate_data => true,
+      :remove_source_columns => true
+    })
+  end
+
+  def self.down
+    Post.drop_translation_table! :migrate_data => true
+  end
+end
+```
+
+
+In order to use a specific locale for migrated data, you can use `I18n.with_locale`:
+
+```ruby
+    I18n.with_locale(:bo) do
+      Post.create_translation_table!({
+        :title => :string,
+        :text => :text
+      }, {
+        :migrate_data => true
+      })
+    end
+```
+
+## Adding additional fields to the translation table
+
+In order to add a new field to an existing translation table, you can use `add_translation_fields!`:
+
+```ruby
+class AddAuthorToPost < ActiveRecord::Migration
+  def change
+    reversible do |dir|
+      dir.up do
+        Post.add_translation_fields! author: :text
+      end
+      
+      dir.down do 
+        remove_column :post_translations, :author
+      end
+    end
+  end
+end
+```
+
+NOTE: Remember to add the new field to the model:
+
+```ruby
+translates :title, :author
+```
+## Gotchas
+
+Because globalize uses the `:locale` key to specify the locale during
+mass-assignment, you should avoid having a `locale` attribute on the parent
+model.
+
+## Known Issues
+
+If you're getting the `ActiveRecord::StatementInvalid: PG::NotNullViolation: ERROR: null value in column "column_name" violates not-null constraint` error, the only known way to deal with it as of now is to remove not-null constraint for the globalized columns:
+
+```ruby
+class RemoveNullConstraintsFromResources < ActiveRecord::Migration
+  def change
+    change_column_null :resources, :column_name, true
+  end
+end
+```
+
+## Versioning with Globalize
+
+See the [globalize-versioning](https://github.com/globalize/globalize-versioning) gem.
+
+## I18n fallbacks for empty translations
+
+It is possible to enable fallbacks for empty translations. It will depend on the
+configuration setting you have set for I18n translations in your Rails config.
+
+You can enable them by adding the next line to `config/application.rb` (or only
+`config/environments/production.rb` if you only want them in production)
+
+```ruby
+config.i18n.fallbacks = true
+```
+
+By default, globalize will only use fallbacks when your translation model does
+not exist or the translation value for the item you've requested is `nil`.
+However it is possible to also use fallbacks for `blank` translations by adding
+`:fallbacks_for_empty_translations => true` to the `translates` method.
+
+```ruby
+class Post < ActiveRecord::Base
+  translates :title, :name
+end
+
+puts post.translations.inspect
+# => [#<Post::Translation id: 1, post_id: 1, locale: "en", title: "Globalize rocks!", name: "Globalize">,
+      #<Post::Translation id: 2, post_id: 1, locale: "nl", title: '', name: nil>]
+
+I18n.locale = :en
+post.title # => 'Globalize rocks!'
+post.name  # => 'Globalize'
+
+I18n.locale = :nl
+post.title # => ''
+post.name  # => 'Globalize'
+```
+
+```ruby
+class Post < ActiveRecord::Base
+  translates :title, :name, :fallbacks_for_empty_translations => true
+end
+
+puts post.translations.inspect
+# => [#<Post::Translation id: 1, post_id: 1, locale: "en", title: "Globalize rocks!", name: "Globalize">,
+      #<Post::Translation id: 2, post_id: 1, locale: "nl", title: '', name: nil>]
+
+I18n.locale = :en
+post.title # => 'Globalize rocks!'
+post.name  # => 'Globalize'
+
+I18n.locale = :nl
+post.title # => 'Globalize rocks!'
+post.name  # => 'Globalize'
+```
+
+## Fallback locales to each other
+
+It is possible to setup locales to fallback to each other.
+
+```ruby
+class Post < ActiveRecord::Base
+  translates :title, :name
+end
+
+Globalize.fallbacks = {:en => [:en, :pl], :pl => [:pl, :en]}
+
+I18n.locale = :en
+en_post = Post.create(:title => 'en_title')
+
+I18n.locale = :pl
+pl_post = Post.create(:title => 'pl_title')
+en_post.title # => 'en_title'
+
+I18n.locale = :en
+en_post.title # => 'en_title'
+pl_post.title # => 'pl_title'
+```
+
+
+## Scoping objects by those with translations
+
+To only return objects that have a translation for the given locale we can use
+the `with_translations` scope. This will only return records that have a
+translations for the passed in locale.
+
+```ruby
+Post.with_translations('en')
+# => [
+  #<Post::Translation id: 1, post_id: 1, locale: "en", title: "Globalize rocks!", name: "Globalize">,
+  #<Post::Translation id: 2, post_id: 1, locale: "nl", title: '', name: nil>
+]
+
+Post.with_translations(I18n.locale)
+# => [
+  #<Post::Translation id: 1, post_id: 1, locale: "en", title: "Globalize rocks!", name: "Globalize">,
+  #<Post::Translation id: 2, post_id: 1, locale: "nl", title: '', name: nil>
+]
+
+Post.with_translations('de')
+# => []
+```
+
+## Show different languages
+
+In views, if there is content from different locales that you wish to display,
+you should use the `with_locale` option with a block, as below:
+
+```erb
+<% Globalize.with_locale(:en) do %>
+  <%= render "my_translated_partial" %>
+<% end %>
+```
+
+Your partial will now be rendered with the `:en` locale set as the current locale.
+
+## Interpolation
+
+Globalize supports interpolation in a similar manner to I18n.
+
+```ruby
+class Post < ActiveRecord::Base
+  translates :title
+end
+
+I18n.locale = :en
+post.title = "Globalize %{superlative}!"
+
+post.title
+# #=> "Globalize %{superlative}!"
+
+post.title(:foo => "bar")
+# SomeError: missing interpolation argument :superlative
+
+post.title(:superlative => "rocks")
+# #=> "Globalize rocks!"
+```
+
+## Fragment caching
+
+Don't forget to add globalize locale into the `cache_key` to separate different localizations of the record.
+One of the possible ways to implement it:
+
+```ruby
+# inside translated model
+def cache_key
+  super + '-' + Globalize.locale.to_s
+end
+```
+
+## Thread-safety
+
+Globalize uses [request_store](https://github.com/steveklabnik/request_store) gem to clean up thread-global variable after every request.
+RequestStore includes a Railtie that will configure everything properly for Rails 3+ apps.
+
+If you're not using Rails, you may need to consult a RequestStore's [README](https://github.com/steveklabnik/request_store#no-rails-no-problem) to configure it.
+
+## Tutorials and articles
+* [Go Global with Rails and I18n](http://www.sitepoint.com/go-global-rails-i18n/) - introductory article about i18n in Rails (Ilya Bodrov)
+
+## Official Globalize extensions
+
+* [globalize-accessors](https://github.com/globalize/globalize-accessors) - generator of accessor methods for models. *(e.g. title_en, title_cz)*
+* [globalize-versioning](https://github.com/globalize/globalize-versioning) - versioning support for using Globalize with [`paper_trail`](https://github.com/airblade/paper_trail). (compatible with Globalize 3.x and 4.x)
+
+## Alternative solutions
+
+* [Traco](https://github.com/barsoom/traco) - use multiple columns in the same model (Barsoom)
+* [hstore_translate](http://github.com/robworley/hstore_translate) - use PostgreSQL's hstore datatype to store translations, instead of separate translation tables (Rob Worley)
+* [Trasto](https://github.com/yabawock/trasto) - store translations directly in the model in a Postgres Hstore column
+
+## Related solutions
+
+* [friendly_id-globalize](https://github.com/norman/friendly_id-globalize) - lets you use Globalize to translate slugs (Norman Clarke)