@intl-tms/core

Framework-agnostic core for in-context translation editing: wrap your i18n library's translator once, and every string it renders carries an invisible marker identifying the translation key it came from. A browser extension can then decode those markers to highlight and edit translations directly on the running page.

The package has zero runtime dependencies and ships as ESM.

Status: 0.x. The public API may change in minor releases until the adapter conformance set (next-intl, react-i18next, react-intl) passes without further core changes.

Install

npm install @intl-tms/core

How it works

Host App  ──wraps translator──▶  markers in rendered text
                                          │
                                          ▼
                              Extension decodes, highlights, edits
                                          │
                                          ▼
                              Your HTTP endpoints store the change

@intl-tms/core sits on both sides of that seam. It encodes markers in the host app, and decodes them in the extension. It never talks to your database — you own the HTTP endpoints it reads and writes through.

Quick start

1. Wrap your translator

createTms adapts the core to whatever i18n library you use. The returned hook is type-identical to the one you pass in, so call sites don't change.

import { createTms, COOKIE_NAME } from '@intl-tms/core';
import { useTranslations } from 'next-intl'; // or any other library

const tms = createTms({
  useClient: (ns) => useTranslations(ns),
  isEnabled: {
    client: () =>
      typeof document !== 'undefined' &&
      document.cookie.includes(`${COOKIE_NAME}=1`),
  },
});

export const useTms = tms.useTms as typeof useTranslations;

Then swap the import in your components — useTms for useTranslations:

export function Nav() {
  const t = useTms('namespace');
  return <nav>{t('nav.home')}</nav>;
}

Markers are only emitted when isEnabled returns true, so production renders are untouched unless in-context editing is switched on.

2. Describe your setup

The extension fetches a TMSConfig from your app at runtime:

import type { TMSConfig } from '@intl-tms/core';

export const tmsConfig: TMSConfig = {
  languages: ['en', 'da', 'es', 'fr'],
  endpoints: {
    update: 'https://app.example.com/api/tms/{key}', // required
    usageReport: 'https://app.example.com/api/tms/usage', // optional
    usageRead: 'https://app.example.com/api/tms/usage/{key}', // optional
  },
};

Endpoints are full absolute URLs, fetched verbatim with {key} replaced by the URL-encoded translation key. The two usage endpoints are optional and act as a feature toggle — omit them to turn usage tracking off.

3. Implement the endpoints

You own these routes and their storage. The wire shapes are exported as types:

| Route | Returns / accepts | | --- | --- | | GET /api/tms/config | TMSConfig | | GET /api/tms/{key} | TranslationValues — { locale: value } | | PUT /api/tms/{key} | TranslationWrite — { locale, value } | | POST /api/tms/usage | UsageReport | | GET /api/tms/usage/{key} | Usage[] |

See the integration guide for worked examples of each.

What's exported

| Area | Exports | | --- | --- | | Marker codec | wrap, unwrap, isWrapped, stripMarkers | | Adapter | createTms, wrapTranslator, COOKIE_NAME | | Config & wire types | TMSConfig, Schema, TranslationValues, LocaleWrite, Usage, UsageReport, … | | Usage / dedupe | aggregateUsage, usageSignature, normalizeUrl | | HTTP client | createTmsClient, resolveEndpoint | | Editing internals | scanForTranslations, createHighlighter, createPicker, createPanelStore |

usageSignature and normalizeUrl are deliberately public so a host app's server can deduplicate the usage index without pulling in the browser-side code.

Security

The endpoints in the integration guide are shown unauthenticated, which is fine for local development and not fine in production. Put the PUT and POST routes behind an authentication and authorization check before deploying. The toggle cookie is a UI switch only — it does not protect routes.

License

MIT © Tobias Havmøller Secher