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-messageformatfor 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 |
projectis the project’sowner/nameslug or its number. Set it when the git remote does not identify the project, or when several projects share one repository.toggleKeyshows or hides Dialecto without a reload. It needs Alt (Option on a Mac) and one letter, digit or function key, written with+.cornermoves the Edit text button tobottom-left,top-rightortop-left.saveToFilesturns 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 needsDIALECTO_SCAN_TOKENand a numericDIALECTO_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 previewand test runs get no markers, no overlay and no network calls. - The add-on’s routes under
/__dialecto/answer only a loopbackHostand a loopback connection. Another device on your network gets a 403, even when you start the dev server with--host.