# `Cldr.Trans.Translator`
[🔗](https://github.com/elixir-cldr/cldr_trans/blob/v1.1.3/lib/cldr/trans/translator.ex#L1)

Provides easy access to struct translations.

Although translations are stored in regular fields of a 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 `Cldr.Trans`
* Automatically inferring the [translation container](Cldr.Trans.html#module-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](Cldr.Trans.html#module-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"
         }
      }
    }

# `translate`
*since 2.3.0* 

```elixir
@spec translate(Cldr.Trans.translatable()) :: Cldr.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

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

    # Translate the entire article into Spanish
    article_es = Cldr.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 = Cldr.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 = Cldr.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"

# `translate`

```elixir
@spec translate(
  Cldr.Trans.translatable(),
  Cldr.Trans.locale_list() | Cldr.Trans.field()
) ::
  Cldr.Trans.translatable() | 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

Assuming the example article in this module:

    # We can get the Spanish title:
    Cldr.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:
    Cldr.Trans.Translator.translate(article, :title, :de)
    "How to Write a Spelling Corrector"

    # A fallback chain can also be used:
    Cldr.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:
    Cldr.Trans.Translator.translate(article, :fake_attr, :es)
    ** (RuntimeError) 'Article' module must declare 'fake_attr'  as translatable

# `translate`

```elixir
@spec translate(Cldr.Trans.translatable(), atom(), Cldr.Trans.locale_list()) :: any()
```

# `translate!`
*since 2.3.0* 

```elixir
@spec translate!(Cldr.Trans.translatable(), atom(), Cldr.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

Assuming the example article in this module:

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*