Soft launchDialecto is still in testing, and details on this site may change as we finish it.

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-store and Vary: 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

  1. Open Settings on the project and find the Live-site editing card.
  2. Switch on Live-site editing.
  3. Under Sites, enter the sites your team runs, one per line, without a path, for example https://shop.example.com. Choose Save sites.
  4. 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.

  1. Add the dependency, compiled in production.

    # mix.exs
    {:dialecto_in_context, "~> 0.1"}
  2. 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
  3. Add the plug to the endpoint after Plug.Session and before the router.

    # lib/my_app_web/endpoint.ex
    plug Plug.Session, @session_options
    if Code.ensure_loaded?(DialectoInContext.Plug), do: plug(DialectoInContext.Plug)
  4. Add the hook to each live_session that renders translated text.

    live_session :default, on_mount: [DialectoInContext.LiveView] do
      live "/", HomeLive
    end
  5. 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 before handle_event, handle_info and handle_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::Deflater before 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 origin to exactly what the browser shows, with www or 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.

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 GET with ?dialecto_edit=<token> is verified inside your app. A good token becomes the dialecto_edit cookie (HttpOnly; Secure; SameSite=Lax; Path=/, ending at the token’s expiry) and the answer is 303 to the same URL without the parameter. A bad token is ignored and the parameter is still removed. The reason is logged at info.
  • With the cookie, GET and HEAD navigations (a document, an iframe, or a same-origin fetch for HTML such as a Turbo visit) are marked, carry the overlay loader, and send Cache-Control: private, no-store, Vary: Cookie and X-Robots-Tag: noindex. The overlay is served from your own origin at /__dialecto/overlay.js.
  • POST requests, fetches and JSON responses are never marked.
  • POST /__dialecto/stop clears the cookie.
  • In :live, /__dialecto/context, /overrides and /marking answer 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/locales are 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-Dest header.
  • 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.