rosetta-connect

Live-reload translations from Rosetta into your running app. Edit a translation in Rosetta, see it in your app instantly — no restart needed.

Rosetta App

This package is the client-side connector for Rosetta. It works with both the desktop app and the VS Code extension.

• Desktop app — download from the releases page
• VS Code extension — install Rosetta i18n from the Marketplace

Install

npm install @terraquant/rosetta-connect

Peer dependency: i18next >= 21

Usage

import i18next from "i18next";
import { connectRosetta } from "rosetta-connect";

if (process.env.NODE_ENV === "development") {
    const disconnect = connectRosetta(i18next);
}

Returns a cleanup function. In React:

useEffect(() => {
    if (process.env.NODE_ENV !== "development") return;
    return connectRosetta(i18next);
}, []);

Options

connectRosetta(i18next, {
    port: 4871, // WebSocket port (default: 4871)
    reconnectInterval: 3000, // Retry delay in ms (default: 3000)
    verbose: true, // Log to console (default: true)
    appName: "My App", // Shown in Rosetta status bar
    updateStrategy: "bundle", // "bundle" (default) or "resource"
    inspect: true, // Enable inspect mode (default: false)
});

Inspect Mode

Inspect mode highlights every translated string in your running app with a rainbow border. Right-click any highlighted text to copy its key path or jump straight to it in Rosetta.

Toggle inspect mode at any time with Cmd+I (Mac) / Ctrl+I (Windows/Linux).

connectRosetta(i18next, {
    inspect: true, // enable with defaults
});

// or configure it:
connectRosetta(i18next, {
    inspect: {
        toggleKey: "i", // keyboard shortcut key (default: "i")
        startActive: false, // start with inspect active (default: false)
    },
});

How it works

• Hooks into i18next via a post-processor plugin to track which rendered strings map to which namespace/key
• Uses a MutationObserver to annotate matching DOM text nodes with <rosetta-i18n> wrapper elements
• Handles both exact matches and substring matches (e.g. translated units concatenated with dynamic values like "42.5 MHz")
• Right-click context menu sends a key:focus message over the WebSocket connection, causing Rosetta to navigate to that key

How it works

Rosetta runs a WebSocket server (default port 4871). This library connects and listens for:

• translation:update — single key changed. Applied via addResourceBundle() with deep merge, then triggers a React re-render via languageChanged event.
• translation:reload — namespace restructured (key added/deleted/renamed). Triggers reloadResources() to re-fetch from your backend.

Works in any environment with WebSocket support: browsers, Electron (main and renderer), Node.js 22+.

Troubleshooting

Check that Rosetta is running with the connector enabled (Settings > Live Preview Connector) and the port matches.

Make sure you're using react-i18next with useTranslation() or <Trans>. Static i18next.t() calls outside React won't auto-update.

Your i18next backend needs to support reloading (e.g. i18next-http-backend). If translations are bundled at build time, only single-key updates will work live.

FAQ

Most of them are full-blown platforms — cloud-hosted, team-based, with pricing tiers and onboarding flows. Great if you need that, but overkill if you just want to edit some JSON files.

Rosetta is a local desktop app that opens a folder and lets you work. It's meant to be trivially easy to set up and operate, even for non-technical people like translators who just need to fill in strings.

For developers: open your project's locales folder in Rosetta and edit directly. Hook up the live preview connector and see changes in your running app as you type.

For translators: get a copy of the locales folder from your dev team, download Rosetta, and start editing. If the dev provides a running build of the app with the connector enabled, translators can see their changes reflected live — no dev environment needed.

If you're a large team with multiple translators working simultaneously and need collaboration features, access control, or translation memory — look at dedicated platforms like Crowdin or Lokalise.

If you're a small dev team that either does translations in-house or sends out one-off tasks to freelance translators, Rosetta is built for you.