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

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.

  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
  2. 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)
  3. Recompile the backend with mix compile --force, then run mix 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-Forms header.
  • Placeholders. %{name} placeholders stay intact, and the preview fills them with the values the page used.
  • Contexts. A text with a msgctxt is edited as its own entry, separate from the same msgid without 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.1 or [::1]), and a POST must carry your site’s own Origin.
  • 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.