Translatable
<img src=“https://secure.travis-ci.org/kot-begemot/translatable.png” />
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.
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.
end
create_table(:news) do |t|
t.integer :author_id
t.
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.
Copyright
Copyright © 2012 E-Max. See LICENSE.txt for further details.