Skip to content

Localization

David Ciulla edited this page Nov 7, 2026 · 1 revision

Localization

Laravex's localization system is implemented in Laravex.Translation. It provides a simple way to retrieve translation strings from language files, with support for locale fallbacks and string replacement.


Configuration

The active locale and fallback locale are set in config/app.exs:

%{
  "locale"          => "en",
  "fallback_locale" => "en"
}

You can also read and set these at runtime through Laravex.Config.Repository.


Language Files

Translation strings are stored in lang/{locale}/{group}.exs files. Each file must evaluate to an Elixir map:

lang/
├── en/
│   ├── auth.exs
│   ├── messages.exs
│   └── validation.exs
└── fr/
    └── messages.exs
# lang/en/auth.exs
%{
  "failed"    => "These credentials do not match our records.",
  "password"  => "The provided password is incorrect.",
  "throttle"  => "Too many login attempts. Please try again in :seconds seconds."
}
# lang/en/messages.exs
%{
  "greeting" => "Hello, :name!",
  "farewell" => "Goodbye, :name."
}

Retrieving Translations

___/3 Helper

The ___ helper (three underscores) is the primary translation function, available via Laravex.Support.Helpers:

import Laravex.Support.Helpers

# Key format: "group.item"
___("auth.failed")
# => "These credentials do not match our records."

# With replacement parameters
___("auth.throttle", %{seconds: 30})
# => "Too many login attempts. Please try again in 30 seconds."

# Explicit locale override
___("messages.greeting", %{name: "Alice"}, "fr")

Laravex.Translation.get/3

You can call the translation module directly:

Laravex.Translation.get("auth.failed")
Laravex.Translation.get("messages.greeting", %{name: "Alice"})
Laravex.Translation.get("messages.greeting", %{name: "Alice"}, "fr")

Key Resolution

  • Keys follow the format "group.item" — the first segment is the filename (without .exs), the second is the map key.
  • If only a single segment is given (e.g. "failed"), Laravex looks in the messages group: lang/{locale}/messages.exs.
  • If the key is not found in the active locale, Laravex falls back to the fallback_locale. If the key is still not found, the raw key string is returned.

Parameter Replacement

Replacement parameters are prefixed with : in the translation string:

# lang/en/messages.exs
%{
  "greeting" => "Hello, :name!",
  "items"    => "You have :count :type in your cart."
}
___("messages.greeting", %{name: "Bob"})
# => "Hello, Bob!"

___("messages.items", %{count: 3, type: "items"})
# => "You have 3 items in your cart."

Both atom and string keys are accepted in the replacement map.


Checking if a Translation Exists

Laravex.Translation.has?("auth.failed")
# => true

Laravex.Translation.has?("auth.nonexistent")
# => false

# Check in a specific locale
Laravex.Translation.has?("messages.greeting", "fr")

In Blade Templates

Use the @lang directive or the {{ ___() }} syntax in Blade templates:

{{-- Using the __() helper --}}
<p>{{ ___("auth.failed") }}</p>

{{-- With replacements --}}
<p>{{ ___("messages.greeting", %{name: user.name}) }}</p>

{{-- @lang directive (equivalent) --}}
@lang("messages.farewell", %{name: user.name})

Adding a New Language

  1. Create a directory: lang/{locale}/ (e.g. lang/fr/)
  2. Add .exs files for each group you want to translate:
# lang/fr/messages.exs
%{
  "greeting" => "Bonjour, :name!",
  "farewell" => "Au revoir, :name."
}
  1. Update app.locale in config/app.exs or pass the locale explicitly to ___/3.

See Also

Clone this wiki locally