== Translatable

{<img src="https://secure.travis-ci.org/kot-begemot/translatable.png" />}[http://travis-ci.org/kot-begemot/translatable]

Whenever you have to deal with multilingual project, where users may fill the post
in different languages, or you have to provide the content in the same way, this
gem will save your day.
This is ActiveRecord version.

== What it does?

This gem interferes heavily with I18n.
First you need to do is to define the model that accepts multilingual context (there
might me more than one of them). There you have to specify the fields that are translatable
and some other details.
Well,that is pretty much it. Now you can create a model with translations, and
switching current locale you will get different translations.
If there is no translation available, you will get nil.

Meanwhile, it validates that the :original_id and :locale are presented, :locale has correct format (two lower letters) and
verifies that :locale in unique within :original_id scope.

Check out the examples below.

== How to use?

Just define inside of your model `translatable` with block.
Block accepts following methods:

  translatable *args
    Params:
      first - Here should be specified an attribute that will be translated.
      second - Define here a hash that will be later provided for validation to model.

      This method may be called multiple times.
    Examples:
      translatable :title,   :presence => true, :uniqueness => true
      translatable :content, :presence => true
      translatable :notes

  translatable_model model_name
    Params:
      model_name - Define the model name here if it is different from following "Translatable<CURRENT_MODEL>".
        For News model, TranslatableNews will be used as the one that keeping translations. It can be defined 
        in a three ways: as constant, string or symbol.
    Examples:
      translatable_model TranslatedNews
      OR
      translatable_model "TranslatedNews"
      OR
      translatable_model :TranslatedNews

  translatable_origin origin_key
    Params:
      origin_key - This key will be used to define the the relations for translations model.
      By default it will be :origin. Translations model should also have such attribute defined.

      This value will also be used for validation, as its presence is compulsory for translations model.
    Examples:
      translatable_origin :message
      OR
      translatable_origin :post

  translatable_locale locale_attr
    Params:
      locale_attr - This key will be used to define the attribute that is keeping the locale of the translation.
      By default it will be :locale. Translations model should also have such attribute defined.

      This value will also be used for validation, as its presence is compulsory for translations model.
    Examples:
      translatable_locale :language
      OR
      translatable_locale :lang

  translatable_attr_accessible
  translatable_attr_protected
    If this line is set then the attributes :locale and :origin will be allowed or protected
    from for mass-assigment.

    Note: Note sure that this is the best implementation. Would appreciate any better ideas.

== Now to create the translations?

 They can be created in two different ways:

First is using the original model. Just provide the translations attributes within `translations_attributes` array.
Second - just create a new translation as if it would be independent model.
For details see Examples below.

== Examples

Migrations:

    class CreateTables < ActiveRecord::Migration
      def up
        create_table(:authors) do |t|
          t.string :name, :null => false

          t.timestamps
        end

        create_table(:translatable_news) do |t|
          t.string :title, :null => false
          t.string :content, :null => false
          t.integer :origin_id, :null => false
          t.string :locale, :null => false, :limit => 2

          t.timestamps
        end

        create_table(:news) do |t|
          t.integer :author_id

          t.timestamps
        end
      end

      def down
        drop_table(:authors)
        drop_table(:translatable_news)
        drop_table(:news)
      end
    end

Models:

    class Author < ActiveRecord::Base
      validates :name, :presence => true
    end

    class TranslatableNews < ActiveRecord::Base
      attr_accessible :title, :content
    end

    class News < ActiveRecord::Base

      belongs_to  :author

      translatable do
        translatable  :title, :presence => true, :uniqueness => true
        translatable  :content, :presence => true
        translatable_model "TranslatedNews"
        translatable_origin :origin_id
        translatable_attr_accessible
      end

      attr_accessible :author_id, :author
    end

An example of application:

    news = News.create :translations_attributes => [{title: "Resent News", content: "That is where the text goes", locale: "en"}]
    news.translations.create title: "Заголовок", content: "Содержание",locale: "ru"

    news.content
    # => "That is where the text goes"

    ::I18n.locale = "ru"
    news.content
    # => "Сюди идет текст"

    ::I18n.locale = "de"
    news.content
    # => nil

    ::I18n.locale = ::I18n.default_locale
    news.content
    # => "That is where the text goes"

== Contributing to translatable
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2012 E-Max. See LICENSE.txt for
further details.