# Vite plugin

Source: https://verbaly.dev/docs/frameworks/vite

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.

```sh
npm install verbaly @verbaly/vite
# or: pnpm add verbaly @verbaly/vite
# or: yarn add verbaly @verbaly/vite
# or: bun add verbaly @verbaly/vite
```

```sh
npm install -D @verbaly/compiler
# or: pnpm add -D @verbaly/compiler
# or: yarn add -D @verbaly/compiler
# or: bun add -D @verbaly/compiler
```

```sh
npx verbaly init
```

Then add the plugin to your Vite config:

```ts title="vite.config.ts"
import verbaly from '@verbaly/vite';

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

Options are the same as the [CLI config](https://verbaly.dev/docs/reference/cli.md): `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}` `` becomes `t("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`, `.vue` and `.astro` files too: script blocks and markup, including Svelte's `$t` store form and Astro frontmatter.
- A file that imports `@verbaly/react`, `@verbaly/vue` or `@verbaly/svelte` also loads `verbaly/app`, so `useT()` 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, as `extract` does.
- `liveExtraction: false` keeps the dev server from writing your translation files: new texts still render from memory, as in a build, and `npx verbaly extract` writes 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 `t` under another name, a translation older than its source.
- When the dev server or the build starts, it names once every file outside your `include` that writes `` t`…` ``, with the pattern to add: that text is never extracted, so it would show in your source language everywhere.

## Build

> **The build report**
>
> `vite build` never writes catalogs, only verifies them. A missing or empty translation, a broken one or a key not in any catalog is listed at the end of the build, broken ones first, and the build finishes: `npx verbaly check` in CI is what stops a release. Run `npx verbaly extract`, translate, check again. `failOnMissing: true` stops the build instead.

## 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](https://verbaly.dev/docs/guide/server.md)).

`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:

```ts title="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:

```sh
npm install verbaly @verbaly/unplugin
# or: pnpm add verbaly @verbaly/unplugin
# or: yarn add verbaly @verbaly/unplugin
# or: bun add verbaly @verbaly/unplugin
```

```sh
npm install -D @verbaly/compiler
# or: pnpm add -D @verbaly/compiler
# or: yarn add -D @verbaly/compiler
# or: bun add -D @verbaly/compiler
```

```sh
npx verbaly init
```

```js title="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.
