Comvi i18n

---

Comvi i18n puts translated text on screen, from a catalog in your source or from the Comvi platform over a CDN. It is a framework-agnostic core with bindings for React, Next.js, Vue, Nuxt, Svelte and Solid, and plugins you add only when you need them.

Install

One package per framework; each binding brings @comvi/core with it.

npm install @comvi/react
npm install @comvi/next
npm install @comvi/vue
npm install @comvi/nuxt
npm install @comvi/svelte
npm install @comvi/solid
npm install @comvi/core

Framework	Package	Peer dependencies	Guide	Try it
React	@comvi/react	react	React	StackBlitz
Next.js	@comvi/next	next, react	Next.js	StackBlitz
Vue	@comvi/vue	vue	Vue	StackBlitz
Nuxt	@comvi/nuxt	nuxt	Nuxt	StackBlitz
Svelte	@comvi/svelte	svelte	Svelte	StackBlitz
Solid	@comvi/solid	solid-js	Solid	StackBlitz
Vanilla JavaScript	@comvi/core	none	Vanilla	StackBlitz

The packages are ESM-only and released together, so install the same version of every @comvi/* package. The runtime packages need Node 20 or newer; @comvi/cli and @comvi/vite-plugin need Node 22.

Quick start

Create the i18n instance and hand it to React, in src/main.tsx:

import { createRoot } from "react-dom/client";
import { createI18n, I18nProvider, useI18n } from "@comvi/react";

const i18n = createI18n({
  locale: "en",
  fallbackLocale: "en",
  messages: {
    en: { greeting: "Hello, {name}!" },
    uk: { greeting: "Привіт, {name}!" },
  },
});

function App() {
  const { t } = useI18n();
  return <h1>{t("greeting", { name: "Alice" })}</h1>;
}

createRoot(document.getElementById("root")!).render(
  <I18nProvider i18n={i18n}>
    <App />
  </I18nProvider>,
);

<I18nProvider> initializes the i18n instance, and useI18n() gives your components t(), the current locale and setLocale(). Every binding has the same shape: create the instance, hand it to the framework, call useI18n() in components. The other frameworks are on Quick start.

How it works

createI18n() returns the i18n instance: it holds the catalog, the current locale and t(). A binding hands the instance to your framework and re-renders what reads it when the locale or the catalog changes. The base instance does text and {param} interpolation. Async loading, locale detection and the in-context editor are capabilities you compose with .use(installer), and ICU plurals are a constructor option, compiler: icuCompiler; what you never name never enters your bundle.

Connect to Comvi

npm install @comvi/plugin-fetch-loader

Compose the loader on the instance, in src/main.tsx:

import { createRoot } from "react-dom/client";
import { createI18n, I18nProvider } from "@comvi/react";
import { cdnLoader } from "@comvi/plugin-fetch-loader";
import App from "./App";

const i18n = createI18n({
  locale: "en",
  fallbackLocale: "en",
}).use(cdnLoader({ cdnUrl: "https://cdn.comvi.io/<project-token>" }));

createRoot(document.getElementById("root")!).render(
  <I18nProvider i18n={i18n} fallback={<div className="spinner" />}>
    <App />
  </I18nProvider>,
);

.use(cdnLoader({ cdnUrl })) fetches each locale from the CDN, so a wording change ships when a translator saves it, without a redeploy. The CDN URL comes from Settings → Content Deploy in the Comvi project; the walkthrough is Connect to Comvi. If your keys use ICU ({count, plural, …}), add compiler: icuCompiler as on Plurals and ICU; the platform and the compiler are independent.

Plugins and tooling

Package	What it does	Docs
@comvi/plugin-fetch-loader	Load translations from the Comvi CDN or API	Fetch loader
@comvi/plugin-locale-detector	Detect the locale from query, cookie, storage, browser	Locale detector
@comvi/plugin-in-context-editor	Edit translations inside the running app	In-context editor
@comvi/vite-plugin	Generate TranslationKeys from local JSON at dev/build	Vite plugin
@comvi/cli	Pull, push, check and generate types from the terminal	Comvi CLI

Contributing

Bug reports, docs fixes and pull requests are welcome. CONTRIBUTING.md explains the repository layout, the setup and what CI checks.

License

MIT © Comvi