Will the publishing today of localize version 0.33.0 and localize_web version 0.7.0 its now possible to take advantage of some macro magic to make localizing templates that much easier.
Message Format 2 translation sigils for Phoenix, with inline markup
Localize and localize_web add a small set of compile-time tools for writing ICU MessageFormat 2 translations directly in Elixir and HEEx — including translations that contain inline markup like {#bold}…{/bold} or {#link navigate=…}…{/link}.
The design borrows heavily from gettext_sigils — that package’s ~t sigil for terse Gettext interpolation is one of the most pleasant translation APIs in any language, and the new tools here are a direct homage. If you’re using plain Gettext today, gettext_sigils is still the right choice; the new sigils make sense only if you want MF2’s features (selectors, plurals, gender, locale-aware formatters) or inline markup.
What’s new
~t sigil — plain-text translation with compile-time MF2 binding extraction
use Localize.Message.Sigils, backend: MyApp.Gettext
~t"Hello, #{user.name}!"
# at compile time becomes ....
gettext("Hello, {$user_name}!", %{user_name: user.name})
The msgid that goes into .po is canonical MF2 — translators can use the full MF2 grammar per locale:
msgid "You have {$count} item(s)"
msgstr ".input {$count :number}\n.match $count\n0 {{Aucun}}\n1 {{Un}}\n* {{{$count} éléments}}"
<Localize.HTML.message> component — render MF2 markup as HEEx
MF2 messages can contain inline markup. The component walks the message and dispatches each markup tag to a registered renderer. Defaults cover bold/strong, italic/em/emphasis, code, link, br. The link default uses Phoenix’s <.link> so translators can write navigate=…, patch=…, or href=…:
<Localize.HTML.message msgid="Visit {#link navigate=|/dashboard|}your dashboard{/link}" />
Custom markup is registered globally or per-call:
config :localize_web, :mf2_markup,
components: %{"user" => &MyAppWeb.MF2.user_mention/1}
<Localize.HTML.message msgid="Posted by {#user id=42}Kip{/user}" />
Unknown MF2 tags raise a compile-time exception.
Localize.HTML.t/1 macro — the recommended HEEx approach
The sigil and the component combined into a single macro for use directly inside HEEx body interpolation - rendering any embedded MF2 markup on the way:
<h1>{t("Hello, #{@user.name}!")}</h1>
<p>{t("By signing up you accept our {#link navigate=|/terms|}terms{/link}.")}</p>
<p>{t("Read {#bold}#{@count} item(s){/bold}")}</p>
The assigns prefix that HEEx auto-injects for @foo is stripped during binding derivation, so #{@user.name} derives the binding user_name (not assigns_user_name).
Setup
# Gettext backend with MF2 interpolation
defmodule MyApp.Gettext do
use Gettext.Backend,
otp_app: :my_app,
interpolation: Localize.Gettext.Interpolation
end
# In MyAppWeb.html_helpers/0 or similar:
quote do
use Phoenix.Component
import Localize.HTML
use Localize.Message.Sigils,
backend: MyApp.Gettext,
sigils: [domain: "messages"]
end
Now ~t, t/1, and <.message> are all available in every LiveView, component, and HEEx-using module.
When to use what
- Inside HEEx →
t/1. Handles plain text and markup, extracts to .po.
- Outside HEEx (error messages, page titles assigned to vars, etc.) →
~t. Returns a String.t(). Markup-free.
- Dynamic msgid (for example, loaded from a database) →
<.message msgid={...} bindings={...} />. Bypasses Gettext extraction (the msgid isn’t a literal) but still walks markup.
Credit & feedback
Huge thanks to the gettext_sigils authors — the ~t sigil shape, the modifier-table idea, the compile-time interpolation walk, and even some of the binding-derivation rules are lifted near-verbatim from that package. If you’ve used gettext_sigils before, almost everything here should feel familiar.
If, after localize 1.0, its possible to be based directly on gettext_sigils, thats what I’ll do.
Docs:
Feedback welcome — particularly on the markup component registry shape (per-call vs. config vs. defaults), and on whether the t/1 macro’s binding-derivation rules match what you would actually write.
