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/compilerThen add the plugin to your Vite config:
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
t`Hola ${name}`becomest("x7Ka9q2f", { "name": name }), where the key is the content hash, stable across files.- The source language ships with your app. Every other language is its own file, downloaded the first time
setLocale()asks for it. - Catalogs stay plain JSON: no proprietary format, portable to any TMS.
- This covers
.svelte,.vueand.astrofiles too: script blocks and markup, including Svelte's$tstore form and Astro frontmatter. - A file that imports
@verbaly/react,@verbaly/vueor@verbaly/sveltealso loadsverbaly/app, souseT()finds its instance in a single-page app with no provider above it.
Dev server
- New texts are extracted as you type. Catalogs and types update a moment after you stop, and the page reloads.
- The first write takes the texts of every file in your
include, opened or not, asextractdoes. liveExtraction: falsekeeps the dev server from writing your translation files: new texts still render from memory, as in a build, andnpx verbaly extractwrites them when you choose.- Editing a catalog by hand reloads it. A text your code owns is put back, and the terminal names the file and line where it lives. Every write starts from the files on disk, so a checkout is never undone with an older text, and a catalog saved half-typed is reported in one line while the server keeps running.
- The terminal names each of these once: a key written with two texts, a
tunder another name, a translation older than its source. - When the dev server or the build starts, it names once every file outside your
includethat writest`…`, with the pattern to add: that text is never extracted, so it would show in your source language everywhere.
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.
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:
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/compilerimport { 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 tooIt'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.