Phoenix live editing
Live editing on Phoenix lets you click a translated text on your running dev app and edit it in a Dialecto
sidebar. The edit keeps your gettext rules intact: contexts (pgettext), one field per plural form, and
%{name} placeholders. It ends as Dialecto’s usual minimal-diff pull request against your translation files.
The add-on is dialecto_in_context. It runs in your dev server. To let editors work on a deployed Phoenix
site, see Live-site editing.
Install
You need Elixir 1.18 or later, gettext ~> 1.0, expo ~> 1.0 and plug ~> 1.15.
# mix.exs
{:dialecto_in_context, "~> 0.1", only: :dev}
Setup
Two guarded lines opt your app in. Code.ensure_loaded?/1 compiles them away wherever the dependency is
absent, so production carries no trace of the add-on.
-
Mark the gettext backend, right after
use Gettext.Backend.# lib/my_app_web/gettext.ex defmodule MyAppWeb.Gettext do use Gettext.Backend, otp_app: :my_app if Code.ensure_loaded?(DialectoInContext.Gettext), do: @before_compile(DialectoInContext.Gettext) end -
Add the plug to the endpoint, before the router and before
Plug.Parsers.# lib/my_app_web/endpoint.ex if Code.ensure_loaded?(DialectoInContext.Plug), do: plug(DialectoInContext.Plug) -
Recompile the backend with
mix compile --force, then runmix phx.server.
An Edit text button appears at the bottom right of every page. Sign in to your Dialecto account in the sidebar. The first time, a Dialecto window asks you to allow the editor.
The add-on finds the project from your app’s git remote, and Dialecto matches it to your project, so nothing else needs configuring.
Editable text
- Plurals. A plural text has one field per plural form, chosen by the catalog’s
Plural-Formsheader. - Placeholders.
%{name}placeholders stay intact, and the preview fills them with the values the page used. - Contexts. A text with a
msgctxtis edited as its own entry, separate from the samemsgidwithout one.
Only translated text that goes through your gettext backend is marked. Markers are on only while the editor is open, and they lapse 90 seconds after the last heartbeat.
Settings
Each setting is also an environment variable, and the variable wins over config :dialecto_in_context.
| Option | Variable | Default |
|---|---|---|
url |
DIALECTO_URL |
https://app.dialecto.eu |
project |
DIALECTO_PROJECT |
found from the git remote |
catalogs |
DIALECTO_CATALOGS |
priv/gettext |
enabled |
DIALECTO_IN_CONTEXT |
on |
paths |
DIALECTO_PATHS |
every page |
exclude_paths |
DIALECTO_EXCLUDE_PATHS |
none |
Set project when the git remote does not identify the project, or when several projects share one repository.
enabled: false or DIALECTO_IN_CONTEXT=off turns the add-on off. paths limits the editor to path prefixes,
and exclude_paths keeps it off others, such as admin screens.
# config/dev.exs
config :dialecto_in_context, paths: ["/app"]
Pull requests
Your edits are saved in Dialecto as drafts on your project. After a reload, the page shows the draft through
your app’s real gettext path, until you discard it or open the pull request. The pull request is opened from the
sidebar. It changes only the edited entries in your .po files, and your team reviews and merges it the usual
way.
The sidebar warns about uncommitted changes under your catalogs folder.
Safety
- The dependency is
only: :dev, so nothing ships to production. - The add-on answers only a loopback
Host(localhost,127.0.0.1or[::1]), and a POST must carry your site’s ownOrigin. - The overlay never loads into an iframe, such as Dialecto’s own sidebar.
- The add-on makes no outbound request. It never reads, scans or uploads your source code or your catalogs. The Dialecto GitHub App reads your translation files when you push.