Trans
v3.0.1

View Source Trans.Translator (Trans v3.0.1)

Provides easy access to struct translations.

Although translations are stored in regular fields of an struct and can be accessed directly, it is recommended to access translations using the functions provided by this module instead. This functions present additional behaviours such as:

  • Checking that the given struct uses Trans
  • Automatically inferring the translation container when needed.
  • Falling back along a locale fallback chain (list of locales in which to look for a translation). If not found, then return the default value or raise and exception if a translation does not exist.
  • Translating entire structs.

All examples in this module assume the following article, based on the schema defined in Structured translations

article = %MyApp.Article{
  title: "How to Write a Spelling Corrector",
  body: "A wonderful article by Peter Norvig",
  translations: %MyApp.Article.Translations{
    es: %MyApp.Article.Translations.Fields{
      title: "Cómo escribir un corrector ortográfico",
      body: "Un artículo maravilloso de Peter Norvig"
    },
    fr: %MyApp.Article.Translations.Fields{
       title: "Comment écrire un correcteur orthographique",
       body: "Un merveilleux article de Peter Norvig"
     }
  }
}

Link to this section Summary

Functions

translate(translatable, locale)

Translate a whole struct into the given locale.

translate(translatable, field, locale)

Translate a single field into the given locale.

translate!(translatable, field, locale)

Translate a single field into the given locale or raise if there is no translation.

Link to this section Functions

Link to this function

translate(translatable, locale)

View Source (since 2.3.0) 
@spec translate(Trans.translatable(), Trans.locale_list()) :: Trans.translatable()

Translate a whole struct into the given locale.

Translates the whole struct with all translatable values and translatable associations into the given locale. Similar to translate/3 but returns the whole struct.

examples

 Examples

Assuming the example article in this module, we can translate the entire struct into Spanish:

# Translate the entire article into Spanish
article_es = Trans.Translator.translate(article, :es)

article_es.title #=> "Cómo escribir un corrector ortográfico"
article_es.body #=> "Un artículo maravilloso de Peter Norvig"

Just like translate/3, falls back to the default locale if the translation does not exist:

# The Deutsch translation does not exist so the default values are returned
article_de = Trans.Translator.translate(article, :de)

article_de.title #=> "How to Write a Spelling Corrector"
article_de.body #=> "A wonderful article by Peter Norvig"

Rather than just one locale, a list of locales (a locale fallback chain) can also be used. In this case, translation tries each locale in the fallback chain in sequence until a translation is found. If none is found, the default value is returned.

# The Deutsch translation does not exist but the Spanish one does
article_de = Trans.Translator.translate(article, [:de, :es])

article_de.title #=> "Cómo escribir un corrector ortográfico"
article_de.body #=> "Un artículo maravilloso de Peter Norvig"
Link to this function

translate(translatable, field, locale)

View Source 
@spec translate(Trans.translatable(), atom(), Trans.locale_list()) :: any()

Translate a single field into the given locale.

Translates the field into the given locale or falls back to the default value if there is no translation available.

examples

 Examples

Assuming the example article in this module:

# We can get the Spanish title:
Trans.Translator.translate(article, :title, :es)
"Cómo escribir un corrector ortográfico"

# If the requested locale is not available, the default value will be returned:
Trans.Translator.translate(article, :title, :de)
"How to Write a Spelling Corrector"

# A fallback chain can also be used:
Trans.Translator.translate(article, :title, [:de, :es])
"Cómo escribir un corrector ortográfico"

# If we request a translation for an invalid field, we will receive an error:
Trans.Translator.translate(article, :fake_attr, :es)
** (RuntimeError) 'Article' module must declare 'fake_attr'  as translatable
Link to this function

translate!(translatable, field, locale)

View Source (since 2.3.0) 
@spec translate!(Trans.translatable(), atom(), Trans.locale_list()) :: any()

Translate a single field into the given locale or raise if there is no translation.

Just like translate/3 gets a translated field into the given locale. Raises if there is no translation available.

examples

 Examples

Assuming the example article in this module:

Trans.Translator.translate!(article, :title, :de)
** (RuntimeError) translation doesn't exist for field ':title' in locale 'de'