File: README — Documentation for translatable (1.2.2)

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:

field *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:
    field :title,   :presence => true, :uniqueness => true
    field :content, :presence => true
    field :notes

class_name 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:
    class_name "TranslatedNews"
    OR
    class_name :TranslatedNews

foreign_key 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:
    foreign_key :message
    OR
    foreign_key :post

locale_key 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:
    locale_key :language
    OR
    locale_key :lang

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(:translated_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 News < ActiveRecord::Base

  belongs_to  :author

  translatable do
    field  :title, :presence => true, :uniqueness => true
    field  :content, :presence => true
    class_name "TranslatedNews"
    foreign_key :origin_id
  end

  accepts_nested_attributes_for :translations, :current_translation
  attr_accessible :translations_attributes, :current_translation_attributes
  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"

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

news.set_current_translation :de
news.content
# => nil

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

Testing

Run the tests with ‘VERBOSE=true` to see SQL queries

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.