Skip to content

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.

  • Node 22.12+ · Vite 7/8
  • TypeScript-first
  • ~3 KB0 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, Vue and Nuxt, Svelte and SvelteKit, Astro or plain HTML.

  1. Install

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

     pnpm add verbaly @verbaly/vite
     pnpm 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.

  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.

    npx verbaly init --source es --locales pt   # config + locales/es.json + locales/pt.json
  3. Add the plugin

    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:

    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

    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.

    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:

    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.

What the project module exports

ExportDescription
tTranslate: 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
verbalyThe underlying instance (advanced use)
↑↓to moveEnterto open
Copied to clipboard