Live-site editing
Live-site editing on a deployed site is available for Phoenix and Rails only. The other frameworks with a live editing add-on (Astro, Next.js, Vite, Vue and Nuxt, Svelte, Angular and Django) edit text in development only, against your local dev server. Their guides are Astro, Next.js, Vite, Vue and Nuxt, Svelte, Angular and Django. Phoenix and Rails also have a development-only mode, covered in the Phoenix and Rails guides.
Live-site editing opens your real site in the Dialecto editor for the people who own the words. An editor starts from Dialecto, the site marks its translated text for that editor only, and a sidebar lets them click a string, edit it and send it for review. Every edit is an ordinary staged edit in Dialecto and ends as a pull request. The site never writes anything itself. Visitors get the same bytes as without the add-on, with no Dialecto script, no markers and no request to Dialecto.
The Live-site editing card in Dialecto lists
the sites. The add-on in your app, dialecto_in_context for Phoenix or
dialecto-rails for Rails, verifies the editor’s launch link and marks pages.
Use cases
Good fits
- Marketing and translators fixing copy and reviewing translations on the real site with real data, without hunting keys in files.
- A Phoenix or Rails site, server-rendered, where the text comes from gettext
or
config/locales.
Poor fits
- A site your team does not run.
- A repo nobody edits.
- A fully static site with text baked in at build time. There is nothing to mark at request time.
- A site on another framework, such as Astro, Next.js or Django. Their live editing works in development only, as the guides linked above describe.
- A site behind a CDN or cache that stores HTML and ignores cookies. Marked
pages send
Cache-Control: private, no-storeandVary: Cookie, and a cache that disregards them defeats the feature.
Edits reach visitors after the pull request merges and the site deploys. On an app with Live updates, they reach it after the merge and the release.
Setup
Turn on Live-site editing
- Open Settings on the project and find the Live-site editing card.
- Switch on Live-site editing.
- Under Sites, enter the sites your team runs, one per line, without a
path, for example
https://shop.example.com. Choose Save sites. - Open the Public key section and copy the key for the add-on.
Only a team admin or owner can switch the card on or change the sites, and the organization needs the Live-site editing entitlement. Everyone else sees the card read-only, with the people who can change it. The sites list holds up to 10 sites. A project that uses the Astro add-on shows its sites here read-only and changes them under In-context editing.
If the public key changes, paste the new one into your app. Editing links stop working until you do.
Install the add-on for Phoenix
The add-on needs Elixir 1.18 or later, gettext ~> 1.0, expo ~> 1.0 and
plug ~> 1.15.
-
Add the dependency, compiled in production.
# mix.exs {:dialecto_in_context, "~> 0.1"} -
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 after
Plug.Sessionand before the router.# lib/my_app_web/endpoint.ex plug Plug.Session, @session_options if Code.ensure_loaded?(DialectoInContext.Plug), do: plug(DialectoInContext.Plug) -
Add the hook to each
live_sessionthat renders translated text.live_session :default, on_mount: [DialectoInContext.LiveView] do live "/", HomeLive end -
Turn on live mode with the values from the card. They are public and safe to commit.
# config/runtime.exs (or config/prod.exs) config :dialecto_in_context, mode: :live, repo: "owner/name", origin: "https://www.example.com", public_key: "ed25519:…"
Unset, mode is :dev in a development or test build and :off in any other,
so a production release stays inert until its config sets mode: :live. In
:live, the plug does nothing without a repo and a valid public_key. A
production build refuses mode: :dev and logs a warning.
origin is the site’s own origin. It is never read from Host or
X-Forwarded-*. When left out, the plug uses the endpoint’s configured URL. If
the app sends a CSP header, the plug adds Dialecto to frame-src on an
editor’s pages only.
Install the add-on for Rails
Move the gem out of group :development so it is installed in production.
# Gemfile
gem "dialecto-rails"
Turn it on in config/environments/production.rb or an initializer.
config.dialecto.mode = :live
config.dialecto.repo = "owner/name"
config.dialecto.origin = "https://www.example.com"
config.dialecto.public_key = "ed25519:…"
Unset, mode is :dev in development and :off in every other environment.
In :live the Railtie also needs repo, origin and public_key. Without
all three it stays off, and one warning at boot says what is missing. The
middleware goes in after the session middleware.
Ed25519 verification uses the openssl gem 3.2 or later on OpenSSL 1.1.1 or
later. Ruby 3.3 and newer ship it. On Ruby 3.2, add gem "openssl", ">= 3.2".
ruby -ropenssl -e 'p OpenSSL::VERSION' shows the version.
Wrap outgoing text
Markers are invisible characters. Anything that leaves the page during a marked render would store or send them to everyone, so wrap it.
| Wrap | Phoenix | Rails |
|---|---|---|
| Call | DialectoInContext.unmarked/1 |
DialectoRails.unmarked { … } |
Wrap a mail sent while an editor’s request runs, text you memoise or cache
(Cachex, ETS, :persistent_term or Rails.cache), translated text written to
the database, broadcasts and job arguments.
- Phoenix: only the render of a mount or a navigation (
handle_params) is marked. The flag is off beforehandle_event,handle_infoandhandle_async, so text re-rendered after an interaction loses its marker until the next navigation. - Rails: a marked request neither reads nor writes fragment caches, so an
editor’s pages render fresh and a visitor’s cache stays untouched. Compress
responses outside the app, or put
Rack::Deflaterbefore the Dialecto middleware, because the loader cannot be added to a compressed body.
Check the site
- Serve the site over HTTPS only. The launch cookie is
Secure. - Set
originto exactly what the browser shows, withwwwor the apex and the port. - Keep the server clock right (NTP). A launch link must arrive within 2 minutes of being minted.
Dialecto screens
Edit on live site
An Edit on live site button appears for people who qualify. It sits on the identity line above the project tabs and in the catalog toolbar.
- With one listed site, the button opens that site in a new tab.
- With several, it opens a menu of the sites. Hovering a site shows Copy a link to bookmark.
A bookmark link has the form
https://app.dialecto.eu/live/<owner>/<repo>?to=<page url>. The page address
must be on a listed site. Opening it signs the editor in and sends them to that
page.
Who may edit on the live site:
- A person with edit rights on the repo for the locale, which is every team role except viewer.
- Live-site editing is on for the repo.
- The page’s origin is in the Sites list.
- The organization has the Live-site editing entitlement.
Sidebar
On the live site, an editor sees the Dialecto sidebar over the page. The first time, Log in to Dialecto opens a small window. Allow the editor there and the panel logs in. The login is scoped to one repo and one site, and it ends when the session ends or after 8 hours.
- Click a string to edit it. The overlay shows the edit in place while the editor types.
- Edits stay as drafts in Dialecto. After a reload, the page shows the committed text again, and the sidebar still lists the drafts.
- Send for review sends the drafts. A person with the right to open pull requests and review gets Open pull request instead.
- The review rules of the repo apply as everywhere else in Dialecto.
One line above the footer counts sent edits by stage and opens them grouped.
| Stage | Meaning |
|---|---|
| In review | Sent for review. Approved edits wait here until they join a pull request. |
| In pull request #n | Linked to the pull request. The edit is locked until it merges. |
| Merged | The pull request merged. |
| Live in apps | A live release on the pull request’s base branch is at or after the merge. |
On a repo with Live updates, the Live in apps group appears once a release includes the merge. The site itself shows the edit after its next deploy. Without Live updates, the Merged group reads “On the site after the next deploy”.
Session
The launch link must reach the site within 2 minutes of being minted. The session lasts 8 hours from then. To stop earlier, choose Stop editing in the sidebar. It clears the launch cookie. An expired session shows “Your live editing session has ended”. Open the site again from Edit on live site.
An admin cannot end one editor’s session from Dialecto. Rotating the repo’s key ends every session.
Site behavior
- A
GETwith?dialecto_edit=<token>is verified inside your app. A good token becomes thedialecto_editcookie (HttpOnly; Secure; SameSite=Lax; Path=/, ending at the token’s expiry) and the answer is303to the same URL without the parameter. A bad token is ignored and the parameter is still removed. The reason is logged atinfo. - With the cookie,
GETandHEADnavigations (a document, an iframe, or a same-origin fetch for HTML such as a Turbo visit) are marked, carry the overlay loader, and sendCache-Control: private, no-store,Vary: CookieandX-Robots-Tag: noindex. The overlay is served from your own origin at/__dialecto/overlay.js. POSTrequests, fetches and JSON responses are never marked.POST /__dialecto/stopclears the cookie.- In
:live,/__dialecto/context,/overridesand/markinganswer 404. - A visitor’s request gets exactly the response the app gives without the add-on. Rails filters the token from its request log.
A leaked launch token is worth at most 8 hours of seeing marked pages. It does not let anyone change text, because editing needs the Dialecto login scoped to the repo and the site.
Refusal pages
Opening Edit on live site checks the rules above. A failed check shows one of these pages.
| Page | Meaning | Way forward |
|---|---|---|
| Login required | No Dialecto login. | Log in and continue. |
| Read-only access | The role cannot edit translations. | Ask a project admin for the translator role, or Open the project. |
| Live-site editing off | The card is off. | An admin chooses Turn on live-site editing. Others choose Edit in Dialecto, or ask an admin. |
| Unlisted site | The requested site is not in the Sites list. | An admin chooses Add the site, and only for a site the team runs. |
The sidebar shows its own pages when the launch worked but editing cannot continue.
| Sidebar page | Meaning |
|---|---|
| No project access | The login has no access to the project. Ask a project owner to add you to its team. |
| Live-site editing off | The card was switched off. Ask a project admin to turn it on in Settings. |
| Unlisted site | The site is not one of the project’s sites. |
| Login for another site | The login was made for another project or site. Log in again from this page. |
Limits
- Only Phoenix with gettext and Rails with
config/localesare supported on a deployed site. - The sidebar shows drafts in a list. After a reload the page does not show a colleague’s pending edits, and reviewing happens in Dialecto.
- Safari needs version 16.4 or newer, because the editor uses the
Sec-Fetch-Destheader. - The launch URL, token included, appears in reverse-proxy access logs.
- A link to a static file path keeps its token in the URL, because the static file handler answers before the add-on.
- Pages served from a cache without reaching Rails, such as page caching or a static export, have nothing to mark.
Troubleshooting
| Symptom | Cause |
|---|---|
| No Edit on live site button | The card is off, the person is a viewer, or the organization lacks the entitlement. With no site listed, the button does not appear. |
| The page opens without the editor | mode is not :live, repo or public_key is missing, or a proxy rewrote origin. Check the boot warning in the log. |
| “Editing on the live site isn’t switched on for this organization.” | The entitlement is missing. |
| “That page address isn’t one Dialecto can send you to.” | The to address is not a full https:// address of a listed site. |
| The launch link does nothing | The link is older than 2 minutes, the server clock is off, or origin differs from what the browser shows. The reason is logged at info. |
| Markers appear in a mail or a cache | The call that produced it is not wrapped in unmarked. |
| Editors get a marked page without the editor (Rails) | The app compresses the response below the Dialecto middleware. |
| Editing links stopped working | The repo’s public key changed. Paste the new key into the app. |