# Getting started

Source: https://verbaly.dev/docs/init/start

Verbaly inverts the usual i18n flow: you write natural text in your code and the compiler extracts messages, generates stable keys, types and per-language bundles. Requirements: Node 22.12+ and Vite 7 or 8.

**Requirements:** Node 22.12+ · Vite 7/8 · TypeScript-first · ~3 KB · 0 dependencies

These steps are a Vite project in plain TypeScript, the shortest way to see it work. On another setup the idea is the same, and its page has the exact lines: [React and Next.js](https://verbaly.dev/docs/frameworks/react.md), [Vue and Nuxt](https://verbaly.dev/docs/frameworks/vue.md), [Svelte and SvelteKit](https://verbaly.dev/docs/frameworks/svelte.md), [Astro](https://verbaly.dev/docs/frameworks/astro.md) or [plain HTML](https://verbaly.dev/docs/frameworks/dom.md).

## 1. Install

Add the runtime and the Vite plugin, then the compiler, which is where the `verbaly` command lives. Pick your package manager.

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

The runtime is always the same; the plugin depends on your setup. On webpack, Rollup, esbuild or Rspack you install `@verbaly/unplugin` instead, and Next.js, Nuxt and Astro have their own. See [Packages](https://verbaly.dev/docs/init/packages.md).

## 2. Scaffold it in one command

`npx verbaly init` writes the config and one catalog per language, and names the packages your project needs: the plugin and, with Vite or another bundler, the one for React, Vue or Svelte if your app uses one. Tell it the language you write in with `--source` and the ones you translate to with `--locales`. It never overwrites anything. Wiring the plugin is yours to do, and it is the next step.

```sh
npx verbaly init --source es --locales pt   # config + locales/es.json + locales/pt.json
```

## 3. Add the plugin

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

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

Your options live in the `verbaly.config` that `init` wrote, where the build and `verbaly check` both read them:

```ts title="verbaly.config.ts"
import type { VerbalyConfig } from '@verbaly/compiler';

export default {
  sourceLocale: 'es',
  locales: ['pt'],
} satisfies VerbalyConfig;
```

`sourceLocale` is the language you write in and `locales` the ones you translate to. That list is the whole list, so a file you left behind is ignored. To add a language later, add it there and run `npx verbaly extract`. Leave `locales` out and every JSON catalog in `locales/` counts as a language, even an empty file you just created.

## 4. Write text, not keys

```ts title="src/main.ts"
import { t, setLocale } from 'verbaly/app';

const name = 'Ana';
const count = 3;
const app = document.querySelector('#app')!;

const paint = () => {
  app.textContent = t`Hola ${name}, tienes ${count} mensajes`;
};

paint();
setLocale('pt').then(paint); // loads its catalog, then paints again
```

In dev, the plugin extracts messages live: your source catalog fills itself, the other languages get `""` placeholders, and the generated types keep keys and params typed.

## 5. Translate and verify

`extract` fills your catalogs: your source language is done, and every other one waits with an empty text. That is why `check` fails here, and it tells you what is missing.

```sh
npx verbaly extract   # sync catalogs + types
npx verbaly check     # exit 1 if anything is missing
```

Write the translation in `locales/pt.json`. The key is the one `extract` wrote, and placeholders like `{name}` stay as they are:

```json title="locales/pt.json"
{
  "oHfbnDd4": "Olá {name}, você tem {count} mensagens"
}
```

`npx verbaly check` passes now. Run `npx vite` and the page reads *Olá Ana, você tem 3 mensagens*. `npx verbaly translate` can fill a catalog for you, as drafts a person reviews.

> **Every build lists what is missing**
>
> `vite build` runs the same check, lists what it found and finishes, so `npx verbaly check` in CI is what keeps untranslated text out of production. Fill the reported keys in `locales/*.json` and check again.

## What the project module exports

| Export | Description |
| --- | --- |
| t | Translate: `t('key', params)` or tagged `` t`...` `` |
| setLocale(locale) | Loads that language, then switches. It returns a promise, so you can wait for it |
| getLocale() | Current language |
| subscribe(fn) | Re-run UI on language/message changes; returns unsubscribe |
| verbaly | The underlying instance (advanced use) |
