Trans v2.0.1 Trans

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

What does this package do?

Trans allows you to store translations for a struct embedded into a field of that struct itself.

Trans is split into two main components:

  • Trans.Translator - allows to easily access translated values from structs and automatically fallbacks to the default value when the translation does not exist in the required locale.
  • Trans.QueryBuilder - adds conditions to Ecto.Query for filtering values of translated fields. This module will be available only if Ecto is available.

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.

What does this module do?

This module provides the required metadata for Trans.Translator and Trans.QueryBuilder modules. You can use Trans in your module like in the following example (usage of Ecto.Schema and schema declaration are optional):

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

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

When used, Trans will define a __trans__ function that can be used for runtime introspection of the translation metadata.

  • __trans__(:fields) - Returns the list of translatable fields. Fields declared as translatable must be present in the module’s schema or struct declaration.
  • __trans__(:container) - Returns the name of the translation container field. To learn more about the translation container field see the following section.

The translation container

By default, Trans stores and looks for translations in a field named translations. This field is known as the translations container.

If you need to use a different field name for storing translations, you can specify it when using Trans from your module. In the following example, Trans will store and look for translations in the field locales.

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

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

Summary

Functions

Checks whether the given field is translatable or not

Functions

translatable?(module_or_struct, field)
translatable?(module | struct, String.t | atom) :: boolean

Checks whether the given field is translatable or not.

Important: This function will raise an error if the given module does not use Trans.

Usage example

Imagine that we have an Article schema declared as follows:

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

If we want to know whether a certain field is translatable or not we can use this function as follows (we can also pass a struct instead of the module name itself):

iex> Trans.translatable?(Article, :title)
true
iex> Trans.translatable?(%Article{}, :not_existing)
false