Skip to content

Integrations

Vite plugin

The official Vite plugin. It extracts your texts while you write, gives each language its own download and lists what is missing in every build.

Installation

Add the runtime and this plugin, then the compiler, which is where the verbaly command lives. init writes your config and your source catalog.

 pnpm add verbaly @verbaly/vite
 pnpm add -D @verbaly/compiler
npx verbaly init

Then add the plugin to your Vite config:

vite.config.ts
import verbaly from '@verbaly/vite';

export default { plugins: [verbaly()] };

Options are the same as the CLI config: sourceLocale, locales, dir, include, exclude, root. Write them in your verbaly.config, where verbaly check and verbaly extract read them too. An option passed to the plugin wins over the file, and those two commands never read it, so the build warns.

How it compiles

Dev server

Build

The project module

verbaly/app is your project's own module: the plugin writes it from your config and your catalogs, so your languages, your URL mode and your source texts are already in it. It also answers to virtual:verbaly, the same module, except under webpack, which reads that prefix as a URL scheme: there, import verbaly/app.

import { t, verbaly, setLocale, getLocale, subscribe } from 'verbaly/app';

// SSR: request-scoped instances + locale metadata
import { createRequestInstance, createInstance, loadMessages, locales, sourceLocale } from 'verbaly/app';

// fresh instance, catalog awaited, no flash. One call per request:
const v = await createRequestInstance(locale);

// raw catalog for a locale (SSR integrations serialize it to the client):
const messages = await loadMessages(locale);

// client-side routing over pre-translated pages (render.inlineCatalog):
import { adoptPage } from 'verbaly/app';
adoptPage({ root: nextDocument, path: nextUrl.pathname });

The shared t and verbaly are for the browser. On the server, createRequestInstance(locale) builds a fresh instance per request and awaits its catalog before returning, so the page arrives translated. createInstance(options) remains for custom setups (see Server-side).

adoptPage exists when render.inlineCatalog is on. Each page carries only the messages it shows, so a router that swaps documents has to hand the next page's over: call it from the hook that fires before the swap. Astro's <ClientRouter /> is wired for you.

The generated types live in src/verbaly.d.ts (the root when there is no src/), the folder the Vite and SvelteKit templates' tsconfig already reads, and they type this module: keys autocomplete and every key's params are enforced. The dev server, every vite build and anything that loads your Vite config, like svelte-check or Vitest, write the same types. A script that runs tsc before the build writes them first with npx verbaly typegen on a fresh clone. Move them or turn them off with the dts config option.

The language a visitor chose

switchLocale and the useLocale of each framework package save the choice in the browser, and they and setLocale set <html lang> and <html dir>. A single-page app starts in its source language, so read the choice back before the first render:

main.ts
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';

// the saved choice, else the browser's, loaded before anything renders
setLocale(resolveLocale({ supported: locales, path: false })).then(render);

A server-rendered app switches with switchLocale or useSwitchLocale, which also write the cookie the server reads.

Not on Vite? Use @verbaly/unplugin

@verbaly/unplugin brings the same compiler to webpack 5, Rollup, esbuild and Rspack: the typed verbaly/app module, the tagged-template transform and the build report, which says each problem once even across the rebuilds of a watch (failOnMissing: true stops the build instead).

In the install, it takes the place of the Vite plugin:

 pnpm add verbaly @verbaly/unplugin
 pnpm add -D @verbaly/compiler
npx verbaly init
webpack.config.mjs
import { verbaly } from '@verbaly/unplugin';

export default { plugins: [verbaly.webpack()] };
// also: verbaly.rollup() · verbaly.esbuild() · verbaly.rspack()
// languages live in your verbaly.config, where verbaly check reads them too

It's build-focused: run npx verbaly extract in your dev loop or CI, since live extraction and reloading as you type come only with the Vite plugin. Each build writes the types too, so a fresh clone typechecks after its first build. ESM-only, like the compiler (use webpack.config.mjs).

The project module is the same here, so the startup line above reads back the language a visitor chose. A file that imports @verbaly/react, @verbaly/vue or @verbaly/svelte loads it too, so their hooks work with no provider in the browser.

↑↓to moveEnterto open
Copied to clipboard