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 toEcto.Query
for filtering values of translated fields. This module will be available only ifEcto
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
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