Generates a SQL fragment for accessing a translated field in an Ecto.Query.

The generated SQL fragment can be coupled with the rest of the functions and operators provided by Ecto.Query and Ecto.Query.API.

safety

Safety

This macro will emit errors when used with untranslatable schema modules or fields. Errors are emitted during the compilation phase thus avoiding runtime errors after the queries are built.

examples

Examples

Assuming the Article schema defined in Trans:

# Return all articles that have a Spanish translation
from a in Article, where: translated(Article, a, :es) != "null"
#=> SELECT a0."id", a0."title", a0."body", a0."translations"
#=> FROM "articles" AS a0
#=> WHERE a0."translations"->"es" != 'null'

# Query items with a certain translated value
from a in Article, where: translated(Article, a.title, :fr) == "Elixir"
#=> SELECT a0."id", a0."title", a0."body", a0."translations"
#=> FROM "articles" AS a0
#=> WHERE ((a0."translations"->"fr"->>"title") = "Elixir")

# Query items using a case insensitive comparison
from a in Article, where: ilike(translated(Article, a.body, :es), "%elixir%")
#=> SELECT a0."id", a0."title", a0."body", a0."translations"
#=> FROM "articles" AS a0
#=> WHERE ((a0."translations"->"es"->>"body") ILIKE "%elixir%")

fallback-chains

Fallback chains

Just like when using Trans.Translator.translate/2 you may also pass a list of locales. In that case the query will automatically fall back through the list of provided locales until it finds an existing translation.

# Query items translated into FR or ES (if FR translation does not exist)
from a in Article, where: not is_nil(translated(Article, a.body, [:fr, :es]))

If you plan to use fallback chains in the database you will need to set up the Trans DB translation functions.

mix do trans.gen.translate_function, ecto.migrate

more-complex-queries

More complex queries

The translated/3 macro can also be used with relations and joined schemas. For more complex examples take a look at the QueryBuilder tests (the file is located in test/trans/query_builder_test.ex).

Generates a SQL fragment for accessing a translated field in an Ecto.Query select clause and returning it aliased to the original field name.

Therefore, this macro returned a translated field with the name of the table's base column name which means Ecto can load it into a struct without further processing or conversion.

In practise it call the macro translated/3 and wraps the result in a fragment with the column alias.