Trans v1.0.1 Trans

Trans provides a way to manage and query translations embedded into schemas and removes the necessity of maintaing extra tables only for translation storage.

Trans is split into 2 main components:

  • Trans.Translator - provides functions to easily access translated values from schemas and fallback to a default locale when the translation does not exist in the required one. If you want to get translations from a schema you should take a look at this module.
  • Trans.QueryBuilder - provides functions that can be chained in queries and allow filtering by translated values. If you want to filter queries using translated fields you should take a look at this module.

What does this package do?

Trans allows you to store translations of a Struct as an extra field of that Struct.

Trans sees its main utility when it is used on Ecto.Schema modules. When paired with an Ecto.Schema, Trans allows you to keep the schema and its translations on the same database table. This removes the necessity of spreading the schema and its translations on multiple tables and reduces the number of required JOINs that must be performed on queries.

The field that stores the translations on the Struct is called the translation container and by default it is expected to be named translations, but that can be easily overriden.

What does this module do?

Although it does not provide any functions that can be used directly (those functions are provided by the Trans.Translator and Trans.QueryBuilder modules), using the Trans module provides two main benefits:

  • Checking the safety of the translation operations - When your schema uses Trans it will safe check the queries that filter on a translated field. This means that trying to set a translation filter for an untranslated field will produce a error when building the query.

  • Avoiding the repetition of default options - If your schema’s translation container receives a different name than the default translations, it would have to be specified on every call to Trans.QueryBuilder or Trans.Translator functions. When using the Trans module, this setting can be specified once an applied automatically when required.

Usage examples

The general way to use Trans in a module is:

use Trans, translates: [:field_1, :field_2][, defaults: [...]]

Suppose that you have an Article schema that has a title and a body that must be translated. You can set up the convenience functions in your module like the following example:

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

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

Now imagine that the Article schema uses a different translation container to store the translations. This should be specified when using Trans so it can automatically provide the required defaults to Trans.QueryBuilder and Trans.Translator like the following example:

defmodule Article do
  use Ecto.Schema
  use Trans, defaults: [container: :article_translations],
    translates: [:title, :body]

  schema "articles" do
    field :title, :string
    field :body, :string
    field :article_translations, :map
  end
end