toretore / translatable_attributes Goto Github PK

TranslatableAttributes
===================

TranslatableAttributes provides simple translations for model attributes. All
translations are stored in a single table which is linked polymorphically to
each model having translatable attributes. Nothing gets stored on the models
that provide the translatable attributes, the methods provided just proxy the
call to the model responsible for storing the translation.

The table storing the translations should be named "attribute_translations"
and contain the columns translatable_type, translatable_id, attribute, locale
and text. TranslatableAttributes has a default AttributeTranslation model which
will just work, but you can create your own with:

script/generate model AttributeTranslation translatable_type:string translatable_id:integer attribute:string locale:string text:text

When storing translations for a given record, TranslatableAttributes will only
find_or_initialize the AttributeTranslation record and update its "text"
attribute, but not save it. The saving usually happens automatically when you
save the parent object as long as there are no errors. The AttributeTranslation
model by default has no validations, so this will work as it should, but if you
want to perform validations on the translation objects, that's entirely up to
you, and it's up to you to make sure validation errors are handled properly.


Example
=======

class Product < ActiveRecord::Base

  translates_attributes :name, :description
  #Product now has_many :attribute_translations

end

product = Product.new
product.name_en = "Chair"
product.name_no = "Stol"

product.name_en
#=> "Chair"
product.name_no
#=> "Stol"

#The record can set a default locale
product.locale = "en"
product.description = "Sit on me"
product.description
#=> "Sit on me"
product.description == product.description_en
#=> true

#If not set, Product#locale uses TranslatableAttributes.locale which uses I18n.locale
I18n.locale = "no"
product.locale = nil
product.description = "Sitt på meg"
product.description_no
#=> "Sitt på meg"



CAVEATS
=======

This plugin uses method_missing to provide getters and setters for translatable
attributes. This means that any methods with the same names defined on the model
class or instance will override these, as it will never get to method_missing.
ActiveRecord defines methods for every column in the associated table, which
means you can't have actual columns on the table for the attributes that are
going to be translated.

  Product
  #=> Product(name:string foo:string)
  Product.translatable_attributes
  #=> ["name", "description"]
  p = Product.new
  p.locale = "nl"
  p.name_en = "Donkey"
  p.name_nl = "Ezel"
  p.name
  #=> nil
  p.name = "Little horse"
  p.name
  #=> "Little horse"
  p.name_nl #nl is the set locale
  #=> "Ezel" #should have been "Little horse"
  p.description = "Groen met turbocompressor"
  p.description_en = "It's just like, it's just like, a mini-horse"
  p.description_nl
  #=> "Groen met turbocompressor"
  p.locale = "en"
  p.description
  #=> "It's just like, it's just like, a mini-horse"

If you really need those columns to be there, you can work around this by
undefing the getter and setter created by AR:

  #Continuing session from above..
  Product.undef_method :name
  Product.undef_method :name=
  p.name
  #=> "Donkey"
  p.locale = "nl"
  p.name
  #=> "Ezel"

You can also read the translations directly using the association extensions:

  p.attribute_translations.text_for_attribute("name", "nl")
  #=> "Ezel"


Copyright (c) 2009 Tore Darell, released under the MIT license