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

Astro live editing

Live editing on Astro lets you click any text on your running site and edit it in a Dialecto sidebar. It works on a site that keeps flat JSON catalogs, one <locale>.json per language, in ICU message format. It runs under astro dev only. A React, Vue or Svelte app on Vite uses the Vite guide instead.

Install

npm install --save-dev @dialecto/astro

The add-on needs Node 22 or later. It is also a single dependency-free file, dialecto-in-context.mjs, that Dialecto offers as a download on the project’s settings page. Copy it into the site, for example into tooling/, and import it by path instead.

Setup

// astro.config.mjs
import { defineConfig } from 'astro/config';
import dialectoInContext from '@dialecto/astro';

export default defineConfig({ integrations: [dialectoInContext()] });

Run astro dev. An Edit text button appears at the bottom right of every page. The editor signs in with your Dialecto account, and the first time a Dialecto window asks you to allow it.

The add-on finds the project from the site’s git remote, so nothing else needs configuring.

Editable text

The catalogs are flat JSON files, read from src/i18n/messages/<locale>.json by default.

  • Placeholders. The add-on swaps your intl-messageformat for a recording one, so each formatted message carries the argument values it was formatted with. The editor previews your edit as you type, with the values the page used.
  • Every render path. Each catalog value is wrapped in an invisible marker, so text from a server render, the browser translator, an attribute or a <title> is traceable with no changes to your app.

Nested catalogs and browser-extension catalogs are edited in Dialecto’s web editor, not on the page. The page markers and previews cover flat catalogs only.

Settings

An option passed to dialectoInContext() wins over the environment variable, and the variable wins over the default.

Option Variable Default
url DIALECTO_URL https://app.dialecto.eu
project DIALECTO_PROJECT found from the git remote
catalogs DIALECTO_CATALOGS src/i18n/messages
sourceLocale DIALECTO_SOURCE_LOCALE en
enabled DIALECTO_IN_CONTEXT on
toggleKey DIALECTO_TOGGLE_KEY alt+shift+d
hidden DIALECTO_HIDDEN off
corner DIALECTO_CORNER bottom-right
saveToFiles DIALECTO_SAVE_TO_FILES off
  • project is the project’s owner/name slug or its number. Set it when the git remote does not identify the project, or when several projects share one repository.
  • toggleKey shows or hides Dialecto without a reload. It needs Alt (Option on a Mac) and one letter, digit or function key, written with +.
  • corner moves the Edit text button to bottom-left, top-right or top-left.
  • saveToFiles turns Open pull request into Save to files. Your drafts go into the catalog files in your working tree, changing only the bytes of the edited values, and you commit and push them yourself. It needs DIALECTO_SCAN_TOKEN and a numeric DIALECTO_PROJECT.

A site on localhost or 127.0.0.1 can always open the editor. Any other host, such as a staging site, is added in the project’s settings under Other sites.

Pull requests

Your edits are saved in Dialecto as drafts on your project, and a reload shows them through your app’s real code paths. The pull request is opened from the sidebar, and it changes only the edited values in your catalogs. Your team reviews and merges it the usual way. Dialecto reads the catalogs from GitHub when you push.

Safety

  • The integration runs only under astro dev. astro build, astro preview and test runs get no markers, no overlay and no network calls.
  • The add-on’s routes under /__dialecto/ answer only a loopback Host and a loopback connection. Another device on your network gets a 403, even when you start the dev server with --host.