# Translator

Translator is a simple model translation/globalization/localization library for Elixir, inspired by [globalize](https://github.com/globalize/globalize).

## Dependencies

You need to use ecto 2.0 or higher.

## Installation

Add translator to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [{:translator, github: "kenta-aktsk/translator"}]
end
```

Ensure translator is started before your application:

```elixir
def application do
  [applications: [:translator]]
end
```

## Basic Usage

Assume that you have user model like below:

```elixir
defmodule MyApp.User do
  use MyApp.Web, :model

  schema "users" do
    field :email, :string
    field :name, :string
    field :profile, :string

    timestamps
  end

  @required_fields ~w(email name)a
  @optional_fields ~w(profile)a

  def changeset(user, params \\ %{}) do
    user
    |> cast(params, @required_fields ++ @optional_fields)
    |> validate_required(@required_fields)
  end
end
```

And assume that you have user record in your db table like below:

```elixir
%{id: 1, email: "user01@example.com", name: "Kenta Katsumata", profile: "Engineer, Writer"}
```

First of all, define migration file for translation table like below:

```elixir
defmodule MyApp.Repo.Migrations.CreateUserTranslation do
  use Ecto.Migration

  def change do
    create table(:user_translations) do
      add :user_id, references(:users, on_delete: :delete_all), null: false
      add :locale, :string, null: false
      add :name, :string, null: false
      add :profile, :text

      timestamps
    end

    create index(:user_translations, [:user_id, :locale], unique: true)
  end
end
```

Next, execute migration.

```
mix ecto.migrate
```

Next, define UserTranslation model like below:

```elixir
defmodule MyApp.UserTranslation do
  use MyApp.Web, :model
  use Translator.TranslationModel,
    schema: "user_translations", belongs_to: MyApp.User, required_fields: [:name], optional_fields: [:profile]
end
```

Next, define `has_one` association and preload query function in User model. (function name is up to you.)

```elixir
defmodule MyApp.User do
  alias MyApp.UserTranslation
  ...
  schema "users" do
    ...
    has_one :translation, UserTranslation
    ...
  end
  def preload_all(query, locale) do
    from query, preload: [translation: ^UserTranslation.translation_query(locale)]
  end
end
```

Next, insert some translation record like below:

```
INSERT INTO user_translations (user_id, locale, name, profile) VALUES (1, "en", "Kenta Katsumata", "living in Tokyo");
INSERT INTO user_translations (user_id, locale, name, profile) VALUES (1, "ja", "勝又健太", "東京在住");
```

Now you can get associated translation record like below:

```elixir
alias MediaSample.{Repo, User}
user = User |> User.preload_all("ja") |> Repo.get!(1)
user.translation
# => %{user_id: 1, name: "勝又健太", profile: "東京在住"}

```

## Insert, Update

You can use `insert_or_update/4` function for inserting or updating translation record like below:

```elixir
# create action in user controller 
def create(conn, %{"user" => user_params}) do
  changeset = User.changeset(%User{}, user_params)

  Repo.transaction fn ->
    user = Repo.insert!(changeset)
    UserTranslation.insert_or_update(Repo, user, user_params, "ja")
  end
end

# update action in user controller 
def update(conn, %{"id" => id, "user" => user_params}) do
  user = Repo.get!(User, id)
  changeset = User.changeset(user, user_params)

  Repo.transaction fn ->
    user = Repo.update!(changeset)
    UserTranslation.insert_or_update(Repo, user, user_params, "ja")
  end
end
```

It is up to you to decide what locale to be passed.

## View helper

You can use view helper to get translated field like below:

```elixir
# web.ex
def view do
  quote do
    ...
    import Translator.TranslationHelpers
  end
end

# templates/user/show.html.eex
<li>
  <%= translate(@user, :name) %>
</li>
```

## Example

You can check some example at my phoenix example repository [media_sample](https://github.com/kenta-aktsk/media_sample).