In-Context Editor

The In-Context Editor lets translators click translated text in the running app and edit it in the browser. It works by adding hidden markers to translation output so the editor can map DOM text back to translation keys.

Note

The package has a no-op production export for bundlers that resolve the production condition. Still gate the editor explicitly when you want full control over where it runs.

Install

npm install @comvi/plugin-in-context-editor

Basic Setup

import { createI18n } from "@comvi/core";
import { FetchLoader } from "@comvi/plugin-fetch-loader";
import { InContextEditorPlugin } from "@comvi/plugin-in-context-editor";

const enableEditor = import.meta.env.DEV || import.meta.env.VITE_COMVI_EDITOR === "true";

const i18n = createI18n({
  locale: "en",
  fallbackLocale: "en",
  apiKey: enableEditor ? import.meta.env.VITE_COMVI_EDITOR_API_KEY : undefined,
})
  .use(FetchLoader({
    cdnUrl: import.meta.env.VITE_COMVI_CDN_URL,
  }));

if (enableEditor) {
  i18n.use(InContextEditorPlugin());
}

await i18n.init();

Without an API key, the browser editor runs in demo mode: you can inspect translations, but changes cannot be saved. The API key needs project:read, translations:read, and translations:write.

The app-bundle production export is a no-op, so normal production builds do not ship the editor runtime. Production editing is handled by the browser extension: a translator opens the live site, enters their API key, and the extension injects the standalone editor.

Options

interface EditorOptions {
  targetElement?: Node;
  apiKeyOverride?: string;
}

targetElement

Limits scanning to a specific DOM subtree. Defaults to document.body.

InContextEditorPlugin({
  targetElement: document.getElementById("app"),
})

apiKeyOverride

Overrides the API key from createI18n(). This is mainly useful for browser-extension or preview tooling.

SSR

The editor runtime is browser-only. On the server, the plugin only registers the marker post-processor and mapping bridge so SSR HTML can hydrate consistently. The MutationObserver and editor UI start in the browser.

Use raw for Unmarked Text

The editor marker injector respects raw: true:

t("meta.title", { raw: true });

Use this for places where hidden editor markers must not be included, such as document titles or meta tags.