# Lost In Translations
Super light Translation Ruby Gem agnostic to your framework and source data

[![Code Climate](https://codeclimate.com/github/Streetbees/lost_in_translations/badges/gpa.svg)](https://codeclimate.com/github/Streetbees/lost_in_translations)
[![Test Coverage](https://codeclimate.com/github/Streetbees/lost_in_translations/badges/coverage.svg)](https://codeclimate.com/github/Streetbees/lost_in_translations/coverage)
[![Build Status](https://travis-ci.org/Streetbees/lost_in_translations.svg?branch=master)](https://travis-ci.org/Streetbees/lost_in_translations)

## 1. Basic Usage
```ruby
class User < Struct.new(:title, :first_name, :last_name)
  include LostInTranslations

  translate :title, :first_name

  def translation_data
    {
      en: { first_name: 'Jon', last_name: 'Snow' },
      fr: { first_name: 'Jean', last_name: 'Neige' }
    }
  end
end
```
Class method **.translate** will redefine **#title** and **#first_name** instance methods in order to return the values that match the **I18n.locale** and the **attribute name** from the Hash returned by **#translation_data**, otherwise calls the original redefined method.

```ruby
@user = User.new('Cavaleiro', 'Joao', 'Neve')

I18n.locale = :fr

@user.first_name # returns 'Jean'
@user.last_name # returns 'Neve'
@user.title # returns 'Cavaleiro'

I18n.with_locale(:en) do
  @user.first_name # returns 'Jon'
  @user.last_name # returns 'Neve'
  @user.title # returns 'Cavaleiro'
end

I18n.with_locale(:de) do
  @user.first_name # returns 'Joao'
  @user.last_name # returns 'Neve'
  @user.title # returns 'Cavaleiro'
end
```

Instance method **#translate** is also available:
```ruby
@user.translate(:first_name, :fr) # returns 'Jean'
@user.translate(:first_name, :en) # returns 'Jon'
@user.translate(:first_name, :de) # returns 'Joao'
```

## 2. Ideal usage
If your ActiveRecord Model has a json attribute called **translation_data**.
```ruby
class CreateUsers < ActiveRecord::Migration
  def up
    create_table :users do |t|
      t.string :title
      t.string :first_name
      t.string :last_name
      t.json :translation_data
      t.timestamps
    end

    User.create \
      title: 'Cavaleiro',
      first_name: 'Joao',
      last_name: 'Neve'
      translation_data: {
        en: { first_name: 'Jon', last_name: 'Snow' },
        fr: { first_name: 'Jean', last_name: 'Neige' }
      }
  end
end
```

The usage becomes quite simple.
```ruby
class User < ActiveRecord::Base
  include LostInTranslations

  translate :title, :first_name
end

@user = User.find(1)

I18n.locale = :fr

@user.first_name # returns 'Jean'
@user.last_name # returns 'Neve'
@user.title # returns 'Cavaleiro'
```

## 3. Configuration

### 3.1 Your "translation_data" method (in all of your objects) is not called "translation_data"
```ruby
LostInTranslations.configure do |config|
  config.translation_data_field = 'my_translation_data_field'
end
```

```ruby
class User < ActiveRecord::Base
  include LostInTranslations

  translate :first_name

  def my_translation_data_field
    {
      en: { first_name: 'Jon', last_name: 'Snow' },
      fr: { first_name: 'Jean', last_name: 'Neige' }
    }
  end
end

I18n.locale = :fr

User.find(1).first_name # returns 'Jean'
```

### 3.2 Your "translation_data" method (in a particular object) is not called "translation_data"
```ruby
class User < ActiveRecord::Base
  include LostInTranslations

  translate :first_name

  self.translation_data_field = :my_translation_data_field

  def my_translation_data_field
    {
      en: { first_name: 'Jon', last_name: 'Snow' },
      fr: { first_name: 'Jean', last_name: 'Neige' }
    }
  end
end

I18n.locale = :fr

User.find(1).first_name # returns 'Jean'
```

### 3.3 Custom translation mechanism
```ruby
class MyTranslator
  def self.translate(object, field, locale)
    translations = #get_data_from_redis_or_yaml_file(object)

    (translations[locale] || {})[field]
  end
end
```

```ruby
LostInTranslations.configure do |config|
  config.translator = MyTranslator
end
```

```ruby
class User < ActiveRecord::Base
  include LostInTranslations

  translate :first_name
end

I18n.locale = :fr

User.find(1).first_name # returns 'Jean' from redis or yaml file
```

Don't forget that you can do the same at the object level
```ruby
class User < ActiveRecord::Base
  include LostInTranslations

  translate :first_name

  def translation_data
    # get_data_from_redis_or_yaml_file(self)
  end
end

I18n.locale = :fr

User.find(1).first_name # returns 'Jean' from redis or yaml file
```

## 4 Instalation

Add your application's Gemfile:
```
gem 'lost_in_translations'
```

And then execute:

```
$> bundle install
```