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-locale bundles. Requirements: Node 20+ and Vite 7 or 8.

  1. 1

    Install

    Add the runtime and the Vite plugin. Pick your package manager.

     pnpm add verbaly @verbaly/vite
  2. 2

    Scaffold it in one command

    npx verbaly init writes the config, creates the locales/ catalogs and detects your bundler. It never overwrites anything. Prefer wiring by hand? The steps below do the same.

    terminal
    npx verbaly init      # config + locales/ + bundler detection
  3. 3

    Add the plugin

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

export default {
  plugins: [verbaly({ sourceLocale: 'es' })],
};

    sourceLocale is the language you write in. Every other locale comes from a JSON catalog in locales/: drop an en.json or pt.json there and Verbaly picks them up automatically.

  4. 4

    Write text, not keys

    src/app.ts
    import { t, setLocale } from 'virtual:verbaly';

const saludo = t`Hola ${name}, tienes ${count} mensajes`;

await setLocale('pt'); // lazy-loads pt chunk

    In dev, the plugin extracts messages live: your source catalog fills itself, other locales get "" placeholders, and verbaly.d.ts keeps keys and params typed.

  5. 5

    Translate and verify

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

What the virtual module exports

ExportDescription
tTranslate: t('key', params) or tagged t`...`
setLocale(locale)Async: lazy-loads that locale's chunk, then switches
getLocale()Current locale
subscribe(fn)Re-run UI on locale/message changes; returns unsubscribe
verbalyThe underlying instance (advanced use)
Copied to clipboard