Manage translations embedded into translation structs.

Although it can be used with any struct Cldr.Trans shines when paired with an Ecto.Schema. It allows you to keep the translations into a field of the schema and avoids requiring extra tables for translation storage and complex joins when retrieving translations from the database.

Cldr.Trans is split into two main components:

• Cldr.Trans.Translator - provides easy access to struct translations.
• Cldr.Trans.QueryBuilder - provides helpers for querying translations using Ecto.Query (requires Ecto.SQL).

When used, Cldr.Trans accepts the following options:

• :translates (required) - list of the fields that will be translated.
• :default_locale (optional) - declares the locale of the base untranslated column. Defaults to the default_locale configured for the Cldr backend.

Structured translations

Structured translations are the preferred and recommended way of using Trans. To use structured translations, use the translations/1 macro when defining a schema. The translations/1 macro will define an embedded schema with the name being the parameter passed to the translations/1 macro. Within the :translations field that is generated, an embeds_one/2 call is added for locale configured in the MyApp.Cldr backend module. Here's an example schema configuraiton:

defmodule MyApp.Article do
  use Ecto.Schema
  use MyApp.Cldr.Trans, translates: [:title, :body]

  schema "articles" do
    field :title, :string
    field :body, :string
    translations :translations
  end
end

When expanded by the Elxir compiler, the example above will look like the following code (assuming the MyApp.Cldr is configured with three locales: :en, :es and :fr). It is provided here only as an example to show what the translations/1 macro compiles to.

defmodule MyApp.Article do
  use Ecto.Schema
  use MyApp.Cldr.Trans, translates: [:title, :body]

  schema "articles" do
    field :title, :string
    field :body, :string

    embeds_one :translations, Translations, on_replace: :update, primary_key: false do
      embeds_one :es, MyApp.Article.Translations.Fields
      embeds_one :fr, MyApp.Article.Translations.Fields
    end
  end
end

defmodule MyApp.Article.Translations.Fields do
  use Ecto.Schema

  @primary_key false
  embedded_schema do
    field :title, :string
    field :body, :string
  end
end

Reflection

Any module that uses Trans will have an autogenerated __trans__ function that can be used for runtime introspection of the translation metadata.

• __trans__(:fields) - Returns the list of translatable fields.
• __trans__(:container) - Returns the name of the translation container.
• __trans__(:default_locale) - Returns the name of default locale. The locale of the fields in the main schema are considered to be in the language of the default locale.