Start
Getting started
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.
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, Vue and Nuxt, Svelte and SvelteKit, Astro or plain HTML.
Install
Add the runtime and the Vite plugin, then the compiler, which is where the
verbalycommand lives. Pick your package manager.pnpm add verbaly @verbaly/vitepnpm add -D @verbaly/compilerThe runtime is always the same; the plugin depends on your setup. On webpack, Rollup, esbuild or Rspack you install
@verbaly/unplugininstead, and Next.js, Nuxt and Astro have their own. See Packages.Scaffold it in one command
npx verbaly initwrites 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--sourceand the ones you translate to with--locales. It never overwrites anything. Wiring the plugin is yours to do, and it is the next step.Add the plugin
vite.config.tsimport verbaly from '@verbaly/vite'; export default { plugins: [verbaly()], };Your options live in the
verbaly.configthatinitwrote, where the build andverbaly checkboth read them:verbaly.config.tsimport type { VerbalyConfig } from '@verbaly/compiler'; export default { sourceLocale: 'es', locales: ['pt'], } satisfies VerbalyConfig;sourceLocaleis the language you write in andlocalesthe 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 runnpx verbaly extract. Leavelocalesout and every JSON catalog inlocales/counts as a language, even an empty file you just created.Write text, not keys
src/main.tsimport { 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 againIn 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.Translate and verify
extractfills your catalogs: your source language is done, and every other one waits with an empty text. That is whycheckfails here, and it tells you what is missing.Write the translation in
locales/pt.json. The key is the oneextractwrote, and placeholders like{name}stay as they are:locales/pt.json{ "oHfbnDd4": "Olá {name}, você tem {count} mensagens" }npx verbaly checkpasses now. Runnpx viteand the page reads Olá Ana, você tem 3 mensagens.npx verbaly translatecan fill a catalog for you, as drafts a person reviews.
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) |