Elixir / Phoenix
Phoenix is the runtime Dialecto was built against first. Your gettext
domains map straight onto the editor, and validation agrees with what
Elixir’s Gettext actually does at runtime — %{} placeholder parity
and plural forms included.
Setup
- Register the repo in Dialecto (Projects → Connect a project, catalog format: Gettext).
- Choose the access mode. In Convenience mode you install the Dialecto
GitHub App, or connect a fine-scoped personal access token where your
server has no app. In Security mode you add the
DIALECTO_SCAN_TOKENsecret and the workflow Dialecto generates. See GitHub App.
Scanning
Extract and merge your catalogs the way Phoenix already does it:
mix gettext.extract --merge
In Convenience mode the GitHub App reads priv/gettext/** from the
pushed commit, and in Security mode your workflow sends those files. To
send code snippets as well, your CI posts the scan. That scan is one HTTP
call carrying your .po/.pot files, the git SHA and branch, and
(recommended) the code snippets around your
gettext calls — those power in-place context and the rename rewrite.
The payload contract and a CI recipe are in
Scanning & CI; wire it to run on pushes to the
branches you care about.
Branch scanning: by default Dialecto tracks the branches you select; switch the repo to scan-all with a branch regex if you want every feature branch localized as it develops.
Editing
The catalog mirrors your priv/gettext structure: locales × domains.
Work a domain at a time; each entry shows its translations side by
side and the code that uses it. Validation runs as you edit:
%{name}placeholders must survive translation — missing or invented ones are flagged.- Plural entries expect the locale’s plural-form count (read from the
catalog’s own
Plural-Forms:header). - Glossary terms are checked against your organization’s glossary.
Everything you save stages into a minimal diff — preview it any time, then submit for review and batch the approved set into a PR targeting the branch you choose.
In-context editing
The dialecto_in_context add-on lets you open your running Phoenix app,
click any text and edit it in the Dialecto sidebar, in the language of
your .po files, with plural forms and placeholders handled for you.
It is open source under the MIT licence, at
github.com/dialecto-eu/dialecto-phoenix,
and it is an opt-in, dev-only dependency. You add it from Hex:
# mix.exs
{:dialecto_in_context, "~> 0.1", only: :dev}
Then you add two guarded lines, one in the gettext backend and one in the
endpoint, that compile away in test and production. The
Phoenix live editing guide
has them, together with the settings. By default the add-on loads
Dialecto’s overlay from https://app.dialecto.eu, the address the app will
have when it opens, so until then it needs an early-access account. It
marks text only while the editor is open. Edits land as drafts that ship as
the same minimal-diff pull request as any other change.
Merge gate
Enable the completeness check in the repo’s settings (pick required
locales), then make Dialecto/translations a required status check
in your GitHub branch protection. From then on, a PR that introduces
untranslated strings in a required locale fails the check, and its
details link lands the author directly on the strings to fix.
incremental scope (the default) means pre-existing gaps don’t block
anyone — see The merge gate.
Renames with call sites
Renaming a msgid in Dialecto computes rewrites for every recorded
gettext("...") call-site and ships them with the PR; ambiguous sites
are listed for manual follow-up instead of guessed at. Details in
Source call-site rewrite.
Grounded suggestions
Machine-translation suggestions are grounded in your domains, usage, and
brand voice. They come from a local model, or
from DeepL or Gemini if your organization’s owner chooses one. For
hands-off catalogs, translation_mode can autofill through the review
flow — see Translation aids.