# Verbaly > i18n that feels like no setup: you write natural text in your code and the compiler extracts it into stable keys, type-safe params and per-locale catalogs. The runtime is 3.35 KB gzip with zero dependencies, and the whole cycle (init, write, extract, translate, review, check, render) lives in one tool. Current version: 0.86.2 (npm: verbaly, MIT). Quick start: `npx verbaly init`, add the bundler plugin or framework integration (@verbaly/vite, @verbaly/react, @verbaly/vue, @verbaly/svelte, @verbaly/sveltekit, @verbaly/nuxt, @verbaly/next, @verbaly/astro, @verbaly/unplugin), write ``t`Hello ${name}` `` and run `npx verbaly extract`. Every build lists missing and broken translations (a dropped placeholder, a lost tag, a flattened plural block) and still finishes; `npx verbaly check` is the strict control, failing CI while any remain. Machine translations stay drafts until a human reviews them. For coding agents: the MCP server `@verbaly/mcp` exposes the cycle as tools, in the order an agent meets a project (verbaly_init, verbaly_doctor, verbaly_wrap, verbaly_extract, verbaly_status, verbaly_missing, verbaly_translate, verbaly_write_drafts, verbaly_drafts), each answering with structured output as well as text (`claude mcp add verbaly -- npx -y @verbaly/mcp`). It also serves verbaly://config and verbaly://catalog/{locale} as resources, which is the only way to read what a message says: every tool works in keys and counts. An installable Agent Skill lives in the repository under skills/verbaly, and an agent that looks for skills on this site finds it in https://verbaly.dev/.well-known/agent-skills/index.json. Both are documented at https://verbaly.dev/docs/guide/agents. Machine translations are always drafts and no agent tool can approve them. Every page below is plain Markdown, at the address of its HTML page plus .md, and https://verbaly.dev/llms-full.txt holds the whole documentation in one file. ## How it compares An honest look against the tools you'd otherwise reach for. It shows where Verbaly wins, and where the others are fine too. Checked against each tool's own documentation in November 2026 (i18next 27, Lingui 6, Paraglide 3). Sizes are min + gzip of what an app imports, with React left out. | Feature | Verbaly | i18next | Lingui | Paraglide | | --- | --- | --- | --- | --- | | Type-safe keys & params | Inferred from your text | Built in, from a declaration file | Text in code, no keys to mistype | A typed function per message | | Runtime size (gzip) | 3.35 KB, zero deps (6.17 with DOM + urls) | 15.5 KB (22.1 with React) | 2.3 KB (4.4 with React) | compiled, no shared runtime | | Key maintenance | None, auto-extracted | Written by hand, synced by its CLI | Extract → compile step | By hand | | Dynamic / CMS content | Real runtime path | Yes | Yes | Best with keys known at build time | | Plain HTML (no framework) | DOM interpreter | With a jQuery plugin | Not covered | Not covered | | Missing translations | Fails CI, every build lists it | A CLI command, for CI | CI step | inlang check, in CI | | Broken translations | Fails CI, every build lists it | CLI lint, a warning by default | Syntax errors only | inlang check, in CI | | Catalog format | Plain JSON | JSON | PO, JSON or CSV | inlang format, others by plugin | | Coding agents | MCP server + skill | Skill, hosted MCP (Locize) | Skills + plugin | Not covered | | Maturity & ecosystem | Pre-1.0: the API can still change | Proven at scale, modules for everything | Stable, standard PO for translators | Stable, with the inlang tools | --- This file holds every page of the documentation, in the order of https://verbaly.dev/llms.txt. Each page is also served alone as Markdown at its address plus .md. --- # What is Verbaly? Source: https://verbaly.dev/docs/init/what-is Verbaly is an open-source i18n toolkit that inverts the usual flow: you write natural text in your code and the compiler extracts the messages, generates stable keys, TypeScript types and per-language bundles. It ships the core `verbaly` runtime (~3 KB, zero dependencies) plus framework packages for `@verbaly/react`, `@verbaly/vue`, `@verbaly/svelte` and build plugins for Vite and every major bundler. The whole write→ship cycle lives in one tool: `init`, live extraction, machine and human translation, a CI gate that fails on missing or broken translations while every build lists them, and a static renderer that ships pages already translated. Catalogs are plain JSON: no proprietary format, portable to any TMS. ## What it looks like You write the sentence, in the language you think in. No key to invent and no catalog to keep by hand. ```ts title="src/app.ts" import { t } from 'verbaly/app'; t`Hello ${name}, you have ${count} messages`; ``` The compiler reads that and writes the rest: a key derived from the text itself, and your source catalog filled in. Every other language waits with an empty string that `verbaly check` will not let you ship. ```json title="locales/en.json + locales/es.json" // en.json, generated from your source { "usNGUet6": "Hello {name}, you have {count} messages" } // es.json, waiting: an empty string is a missing translation { "usNGUet6": "" } ``` ## Why Verbaly? Every i18n library translates text. The difference is how much work it leaves on your desk. Verbaly's answer: as little as possible. - **Type-safe for real**: The message itself declares its parameters. Forget one, or rename it, and TypeScript stops you before any user sees it. - **Nothing missing goes unseen**: Every build lists a missing translation with the exact key to fill, and the check in your CI stops it there. - **Too small to notice**: The runtime is 3.35 KB with zero dependencies, each language loads only when someone uses it, and a pre-rendered page can ship just the messages it shows. - **The whole cycle in one tool**: Extract, machine-translate, hand files to human translators, verify in CI and pre-render static pages: everything ships in the same box. - **No framework needed**: Plain HTML works too: mark elements with `data-verbaly` and the DOM interpreter fills them, re-renders on a language switch and picks up nodes added later. - **Your agent can run it**: An MCP server exposes the whole cycle as tools, so a coding agent sets up, extracts, translates and reads your messages without you relaying commands. Verbaly is pre-1.0, so the API can still change between minor versions (every change is called out in the changelog). And if what you need is a huge plugin ecosystem, i18next has years of it. What Verbaly offers is the same job with far less machinery, and an [honest comparison](https://verbaly.dev/#compare) to check it. --- # 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) | --- # Migrate to Verbaly Source: https://verbaly.dev/docs/guide/migrate Moving off another i18n library is mostly mechanical, and you do not have to do it all at once: the two runtimes coexist while you go file by file. The three sections after the first one apply whatever you are coming from; the first is for i18next, which is where most people arrive from. ## Coming from i18next: what maps to what The mental model carries over one-to-one, and syntax is the only thing that changes: | i18next | Verbaly | | --- | --- | | `i18next.init({ … })` | `npx verbaly init` + one build plugin | | `t('inbox.title')` | `t('inbox.title')`: same call, keys now typed | | `{{name}}` | `{name}` | | `messages_one / messages_other` | `{count \| one: … \| other: # …}`: optional, the suffixed keys keep working as they are | | `format: 'currency'` (interpolation) | `{price:currency/EUR}` (native Intl) | | `i18next-browser-languagedetector` | `resolveLocale()` + `persistLocale()` | | `i18next-http-backend` (lazy load) | per-locale code-splitting, built into the plugin | | `useTranslation()` (react-i18next) | `useT()` (@verbaly/react) | | Trans component | Trans component: `values` / `components` map over | | `i18next.changeLanguage('es')` | `await setLocale('es')` | | `saveMissing`, runtime fallbacks | `npx verbaly check`: CI fails instead | ## Keep your catalogs: they port as they are Your catalogs move without being reshaped. Nested groups keep their nesting, `_one` and `_other` keep working as the keys they are, and a namespace with a colon is still a key. **One thing has to change**, and `migrate` does it: `{{name}}` becomes `{name}`, and a lone brace i18next showed as text is doubled, because a doubled brace is how Verbaly writes a literal one. ```sh npx verbaly migrate # what it would port npx verbaly migrate --write # apply it ``` It reports first, rewrites only the braces, and lists what it will not guess so you decide those yourself. This is what it does to the file: **i18next** (`locales/en.json`): ```json { "inbox": { "title": "Inbox" }, "messages_one": "one message", "messages_other": "{{count}} messages" } ``` **Verbaly** (`locales/en.json`): ```json { "inbox": { "title": "Inbox" }, "messages_one": "one message", "messages_other": "{count} messages" } ``` Two upgrades you can take later, and neither is needed to run. Merging `_one` and `_other` into one message with variants (`{count | one: … | other: # …}`) is what buys automatic plural selection, and the `#` renders the count already localized, with no separate `formattedCount`. The second is smaller: dots are a naming convention, not a format. A key reads the same whether your file spells it `"inbox.title"` or as a `title` inside an `inbox` group. ## Swap the runtime Existing keys keep working through `t('key', params)`, so migrated components barely change. In React: **react-i18next**: ``` import { useTranslation } from 'react-i18next'; const { t } = useTranslation(); t('inbox.title'); t('messages', { count }); ``` **@verbaly/react**: ``` import { useT } from '@verbaly/react'; const t = useT(); t('inbox.title'); t('messages', { count }); // params now typed ``` If your components call a hook of your own, like a `useTranslate` around `useTranslation`, keep it and make it return `useT()`: nothing that calls it changes. A key type built from your JSON, like a `NestedKeyOf`, also lists the group paths, so make it `VerbalyKey` from `verbaly/app`. To wait for the visitor's language before the first paint, as a Suspense boundary did, render inside `setLocale(locale).then(…)`: a top-level `await` in your entry splits the bundle into many files. The bundle notices. A React app carrying i18next and react-i18next ships about 22 KB of runtime; the same app on Verbaly ships about 4. Without a framework it is 15.5 against 3.3. All four numbers are gzipped and measured, not estimated. Measured on Memos, an open source app in 46 languages: 20 files changed by hand, its build and its tests as before, and about 11 KB less for every visitor on first load. New copy skips the key ceremony entirely: write the text as a tagged template and let the compiler extract it, or keep readable ids with `t.id`. Vue and Svelte adapters follow the same pattern, and plain-HTML pages can bind with `data-verbaly` instead. ```tsx title="src/app.tsx" t`Hola ${name}`; // key + types generated t.id('inbox.title')`Inbox`; // readable id, i18next-style ``` ## Coming from no i18n at all? Let wrap do the boring part If your app has hardcoded text instead of an i18n library, `npx verbaly wrap` scans your JSX, finds the user-visible strings and wraps them in `` t`…` `` for you. It only reports until you pass `--write`, and anything ambiguous (like a sentence mixed with markup) is listed for you to wrap by hand instead of guessed. ```console $ npx verbaly wrap would wrap 37 texts in 12 files (report only, use --write to apply) src/App.tsx:12 "Welcome back" src/Nav.tsx:8 aria-label → "Open menu" ``` ```sh npx verbaly wrap --write # then: add t to scope and run npx verbaly extract ``` ## Language detection and lazy loading The detector plugin and the HTTP backend both disappear. `resolveLocale` reads the address → storage → `navigator.languages` → fallback, safe on a server and with `es-PE` finding `es`. `persistLocale` stores the choice and syncs ``, and `setLocale` downloads that language when it is needed: ```ts title="src/main.ts" import { resolveLocale, persistLocale } from 'verbaly'; import { setLocale, getLocale } from 'verbaly/app'; await setLocale(resolveLocale({ supported: ['en', 'es', 'pt'] })); persistLocale(getLocale()); ``` ## Migrate incrementally No big-bang rewrite needed: the Verbaly runtime is ~3 KB, so both libraries can coexist while you move one page or namespace at a time. A `t` or a `Trans` a component still takes from react-i18next, next-i18next, next-translate, ttag or Lingui is left exactly as written. Once the catalogs are converted, give i18next `interpolation: { prefix: '{', suffix: '}' }` so it reads them too. A pragmatic order: ### 1. Run both side by side `npx verbaly init` and the build plugin, so the toolchain runs alongside i18next from day one. It points the config at the catalogs you already have, wherever they live. ### 2. Port the catalogs `npx verbaly migrate --write`. It turns `{{name}}` into `{name}`, doubles a brace i18next showed as text so it stays text, and remembers which languages it converted, so running it again is safe. ### 3. Swap hooks page by page Replace `useTranslation` with `useT` and delete each i18next namespace as it empties. ### 4. Check it in CI `npx verbaly check` in CI, and `npx verbaly pseudo` to catch hardcoded strings the migration missed. > **Structural validation has your back** > > If a ported message loses a placeholder or a tag on the way, `verbaly check` and `verbaly translate` reject it before it ships, so you can migrate fast without migrating blind. --- # Packages Source: https://verbaly.dev/docs/init/packages Verbaly is a family of small packages so you install only what you use. Two of them cover most projects: the runtime and the plugin for your bundler. Everything else is there when you need it. 13 packages, one shared version · Only the runtime reaches the browser Starting from scratch? Install these three and follow [Getting started](https://verbaly.dev/docs/init/start.md). The runtime never changes; if you are not on Vite, swap the second one for the piece your setup needs. The third is the compiler, where the `verbaly` command lives. ```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 ``` ## Core - [**verbaly**](https://verbaly.dev/docs/reference/api.md): Translates, formats and switches language. This is the only part that ships to the browser. Install: `npm i verbaly`. [npm](https://www.npmjs.com/package/verbaly) - [**@verbaly/compiler**](https://verbaly.dev/docs/reference/cli.md): The verbaly command: it reads your code and keeps catalogs and types in sync. Runs on your machine and in CI, never in the browser. Install: `npm i @verbaly/compiler`. [npm](https://www.npmjs.com/package/@verbaly/compiler) ## Bundlers - [**@verbaly/vite**](https://verbaly.dev/docs/frameworks/vite.md): Extracts your text while you code, keeps types fresh and lists in every build what is missing or broken. Install: `npm i @verbaly/vite`. [npm](https://www.npmjs.com/package/@verbaly/vite) - [**@verbaly/unplugin**](https://verbaly.dev/docs/frameworks/vite.md#unplugin): The same build for webpack, Rollup, esbuild and Rspack. Install: `npm i @verbaly/unplugin`. [npm](https://www.npmjs.com/package/@verbaly/unplugin) ## Frameworks - [**@verbaly/react**](https://verbaly.dev/docs/frameworks/react.md): Hooks and a Trans component so your components re-render when the language changes. Install: `npm i @verbaly/react`. [npm](https://www.npmjs.com/package/@verbaly/react) - [**@verbaly/vue**](https://verbaly.dev/docs/frameworks/vue.md): A plugin, composables and a Trans component for Vue. Install: `npm i @verbaly/vue`. [npm](https://www.npmjs.com/package/@verbaly/vue) - [**@verbaly/svelte**](https://verbaly.dev/docs/frameworks/svelte.md): Stores and a Trans component for Svelte. Install: `npm i @verbaly/svelte`. [npm](https://www.npmjs.com/package/@verbaly/svelte) - [**@verbaly/astro**](https://verbaly.dev/docs/frameworks/astro.md): One integration line. It also writes your site pre-translated in every language when you build. Install: `npm i @verbaly/astro`. [npm](https://www.npmjs.com/package/@verbaly/astro) ## Full-stack - [**@verbaly/next**](https://verbaly.dev/docs/frameworks/react.md#next): App Router: the language is resolved on the server, so pages arrive translated. Install: `npm i @verbaly/next`. [npm](https://www.npmjs.com/package/@verbaly/next) - [**@verbaly/nuxt**](https://verbaly.dev/docs/frameworks/vue.md#nuxt): Add it to modules and it wires everything, including the language of each request. Install: `npm i @verbaly/nuxt`. [npm](https://www.npmjs.com/package/@verbaly/nuxt) - [**@verbaly/sveltekit**](https://verbaly.dev/docs/frameworks/svelte.md#sveltekit): One language per request, and no flash of the wrong text when the page loads. Install: `npm i @verbaly/sveltekit`. [npm](https://www.npmjs.com/package/@verbaly/sveltekit) ## Coding agents - [**@verbaly/mcp**](https://verbaly.dev/docs/guide/agents.md): Gives your coding agent the cycle as tools: read the coverage, list what is missing, extract new text and fill the gaps. Install: `npm i @verbaly/mcp`. [npm](https://www.npmjs.com/package/@verbaly/mcp) ## Tools - [**@verbaly/studio**](https://verbaly.dev/docs/guide/studio.md): Serves your whole project on your own machine: read every catalog, fix what is broken and approve what the machine wrote. Install: `npm i @verbaly/studio`. [npm](https://www.npmjs.com/package/@verbaly/studio) > **One version for all of them** > > Every package is released at the same time with the same version number, so you never have to match compatible ranges. Upgrade them together and they always agree. --- # Plain HTML Source: https://verbaly.dev/docs/frameworks/dom No framework? Plain HTML works just as well, something no other compiler-based i18n tool offers. Mark elements, call `bindDom`, done. ## Installation The runtime is all this page needs: no plugin and no compiler. ```sh npm install verbaly # or: pnpm add verbaly # or: yarn add verbaly # or: bun add verbaly ``` Add `@verbaly/compiler` as a dev dependency when you want the `verbaly` command, to check your catalogs or to write each page already translated. ## Usage ```html title="index.html"

``` ```ts title="main.ts" import { bindDom, createVerbaly } from 'verbaly'; const messages = { es: { 'home.title': 'Bienvenida', inbox: '{count | one: # mensaje | other: # mensajes}', 'search.hint': 'Buscar', }, en: { 'home.title': 'Welcome', inbox: '{count | one: # message | other: # messages}', 'search.hint': 'Search', }, }; const v = createVerbaly({ locale: 'es', messages }); bindDom(v); // render + observe v.setLocale('en'); // every bound node re-renders ``` ## Attributes | Attribute | Purpose | | --- | --- | | data-verbaly | Key whose translation becomes the element's text | | data-verbaly-args | JSON params shared by text and attribute translations | | data-verbaly-attr | JSON map of attribute → key, e.g. `placeholder`, `title`, `aria-label`. URL attributes (`href`, `src`…) are checked against unsafe schemes the way a browser reads a URL, so a tab or a line break inside the scheme cannot hide one. `on*`, `style` and `srcdoc` are blocked, so a catalog can't inject scripts | | data-verbaly-rich | Opt-in: render tags in the message as real elements (see Rich text) | | data-verbaly-links | JSON map of link name → href for named links (see Named links) | ## Rich text By default translations render via `textContent`, so tags stay literal. Mark the element with `data-verbaly-rich` and tagged messages become real elements: ```json title="locales/en.json" { "gate.title": "The build gate" } ``` ```html title="index.html"

``` One key per sentence, so translators see the whole message and each language keeps its own word order. The safety model: - Only a **short list of inline tags** renders: `em`, `strong`, `code`, `b`, `i`, `u`, `s`, `small`, `mark`, `sub`, `sup`, `span`, `kbd`, `abbr`, `br`, `wbr`. The last two take no content, so `
`, `
` and `
` are all a line break. - Elements are built programmatically, never `innerHTML`, and **attributes never come from the message**. - Any other tag is unwrapped to inert text: ` ``` - Subscriptions are per-component and cleaned up on unmount via `onScopeDispose`. - `useLocale()` returns a writable computed, so you can bind it directly to a select. - No plugin installed, in the browser? `useT()` and `useLocale()` read the instance `verbaly/app` creates, and the bundler plugin loads that module in every file that imports `@verbaly/vue`, so a single-page app or a component test needs no setup. On a server the plugin is required, since each request has its own instance. ### The language a visitor picks Writing `locale.value` switches every component, and the page follows: ``, `` and the choice, saved in the browser. A single-page app starts in its source language, so read that choice back before mounting: ```ts title="main.ts" // the saved choice, else the browser's, loaded before anything renders import { resolveLocale } from 'verbaly'; import { locales, setLocale } from 'verbaly/app'; setLocale(resolveLocale({ supported: locales, path: false })).then(() => app.mount('#app')); ``` Where a server renders the page, as in Nuxt, switch with `switchLocale` from `verbaly/app` instead: it also sets the cookie the server reads. ### Write the text in place The compiler reads your `.vue` files too: write the source text in an interpolation, in a directive binding or in `script setup`, and it is extracted, keyed and typed on save. Plain display text is never extracted, so a page can show `` t`…` `` as an example safely. No key to invent, no catalog to touch. ```vue title="Inbox.vue" ``` Prefer readable keys? `t.id('inbox.title')` before the template extracts under your id instead of a content hash. Prefer to keep the text in your catalog? Write only its key: it is checked and typed the same way. See [Keys and catalogs](https://verbaly.dev/docs/guide/keys.md). ### Rich text with \ Same idea; in Vue each named tag is a render function that wraps its children: ```vue title="Agree.vue" ``` For plain links skip the render function: the `links` prop maps tag names to hrefs (a string or an href/target/rel object). `components` wins on the same name; `javascript:` hrefs are blocked. Allowed tags (``, ``…) render as real elements, with no render function needed: the same safe list as plain HTML. `richTags` overrides it, and the `instance` prop renders without the plugin. ## Nuxt Server-rendered pages arrive already translated in the visitor's language, and the browser takes over with the same language and catalog: no flash of untranslated text, no mismatch between server and browser. - Every page renders in the visitor's language, taken from the address when it carries one, and otherwise from their saved choice or `Accept-Language` header - No flash of untranslated text: the HTML the server sends and the page after hydration are identical, catalog included - Each request gets its own instance, so simultaneous visitors never see each other's language - Zero wiring: one module entry replaces the Vite plugin setup, the negotiation and the `lang` and `dir` attribute sync Nuxt needs the module (`@verbaly/nuxt`) alongside the Vue package and the compiler: ```sh npm install verbaly @verbaly/nuxt @verbaly/vue # or: pnpm add verbaly @verbaly/nuxt @verbaly/vue # or: yarn add verbaly @verbaly/nuxt @verbaly/vue # or: bun add verbaly @verbaly/nuxt @verbaly/vue ``` ```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 ``` ## Wire it up One line in `nuxt.config`. The module wires the Vite plugin (live extraction and `verbaly/app`), picks the language per request and keeps the `lang` and `dir` attributes in sync. If your addresses carry the language, it reads them on its own and there is nothing extra to write: ```ts title="nuxt.config.ts" export default defineNuxtConfig({ modules: ['@verbaly/nuxt'], }); // locales live in your verbaly.config (npx verbaly init), where verbaly check reads them too ``` From here it's plain `@verbaly/vue`: `useT()` / `useLocale()` and `` work unchanged in every component. `useT()` is typed by your catalog: the types go to `.nuxt/verbaly.d.ts`, where Nuxt links them, and `npx verbaly extract` writes that same file. A key no catalog has fails `nuxi typecheck`. > **Why hydration never flashes** > > The module resolves the language on the server: the address first when it carries one, then the saved choice, then `Accept-Language`, then your fallback. The result rides the Nuxt payload, and the client builds its instance from that same value, with the catalog awaited before render. Both sides produce identical HTML, so nothing repaints and nothing mismatches. ## Switching languages `switchLocale` from `verbaly/app` already knows your languages and your URL mode. Hand it the instance this page renders with: with the language in the URL it goes to the same page in the other language, and without it it loads the catalog and switches the page in place. Either way it writes the cookie the server reads, so the next request already matches: ```vue title="LangPicker.vue" ``` - The cookie defaults to `verbaly-locale` (same identity as the core's storage key); `cookie: false` in the module options disables it, for pure `Accept-Language`. - `fallback` defaults to your source language; negotiation follows the order of preference of the browser, and `es-PE` matches `es`. - `ssr: false` is covered too: the module resolves the language in the browser, reading the address first when it carries the language, then the cookie, then `navigator.languages`, then your fallback. - No dependency on Nuxt itself: the module is typed structurally, without `@nuxt/kit`. The `verbaly` key in `nuxt.config.ts` is still fully typed (autocomplete and typo checking), and it stays compatible across Nuxt 4. - Fully static site (`nuxi generate`)? Prefer pre-translated output per language with [verbaly render](https://verbaly.dev/docs/reference/cli.md). --- # Svelte Source: https://verbaly.dev/docs/frameworks/svelte The official Svelte 5 package for Verbaly. Idiomatic stores over the same reactive core, store factories for app-level use, and a \ component for rich text. What you can accomplish: - Translate with stores: `$t` re-renders on every language switch, no wiring - Bind a language switcher in one line: `bind:value` on the language store just works - Use context or store factories, with or without a component tree - Map a tag in a message to your own component with the \ components prop ## Installation Add the runtime, this package and the Vite plugin, then the compiler, which is where the `verbaly` command lives. `init` writes your config and your source catalog. ```sh npm install verbaly @verbaly/svelte @verbaly/vite # or: pnpm add verbaly @verbaly/svelte @verbaly/vite # or: yarn add verbaly @verbaly/svelte @verbaly/vite # or: bun add verbaly @verbaly/svelte @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 `verbaly()` to the plugins in `vite.config`. It writes `verbaly/app`, the module your components read. ## Setup & stores ```svelte title="+layout.svelte · Inbox.svelte"

{$t`You have ${count} messages`}

``` - Idiomatic stores: `$t` re-renders on every language switch; `bind:value={$locale}` on a select just works. - No component tree? `tStore(instance)` / `localeStore(instance)` build the same stores without context, shared by the whole app. - No `provideVerbaly` above a component, in the browser? `useT()` reads the instance `verbaly/app` creates, and the bundler plugin loads that module in every component that imports `@verbaly/svelte`, so a single-page app or a component test needs no wrapper. On a server a parent has to provide it, since each request has its own instance. ### The language a visitor picks Setting `$locale` switches every component, and the page follows: ``, `` and the choice, saved in the browser. A single-page app starts in its source language, so read that choice back before mounting: ```ts title="main.ts" // the saved choice, else the browser's, loaded before anything renders import { mount } from 'svelte'; import { resolveLocale } from 'verbaly'; import { locales, setLocale } from 'verbaly/app'; import App from './App.svelte'; setLocale(resolveLocale({ supported: locales, path: false })).then(() => mount(App, { target: document.getElementById('app')! }), ); ``` Where a server renders the page, as in SvelteKit, switch with `switchLocale` from `verbaly/app` instead: it also sets the cookie the server reads. ### Write the text in place The compiler reads your `.svelte` files too: write the source text with the store tag, in a markup expression or in the script, and it is extracted, keyed and typed on save. Plain display text is never extracted, so a page can show `` t`…` `` as an example safely. No key to invent, no catalog to touch. ```svelte title="Inbox.svelte"

{$t`Hola ${name}, tienes ${count} mensajes`}

{$t('oHfbnDd4', { name, count })}

``` Prefer readable keys? `$t.id('inbox.title')` before the template extracts under your id instead of a content hash. Prefer to keep the text in your catalog? Write only its key: it is checked and typed the same way. See [Keys and catalogs](https://verbaly.dev/docs/guide/keys.md). ### Rich text with \ Svelte has its own component: import it from the `Trans.svelte` subpath (raw component, compiled by your bundler): ```svelte title="Title.svelte" ``` - Message tags (`The build gate`) render as real elements from the same list of allowed tags as `data-verbaly-rich`. Unknown tags unwrap to inert text, `richTags` overrides. - Uses the instance from `provideVerbaly`; pass `instance={verbaly}` explicitly when there's no context. Re-renders on every language switch. - Named links: the `links` prop renders named tags as real `` elements, with hrefs from your code, never from messages; `javascript:` blocked. - Your own components: the `components` prop maps a tag to a Svelte component that receives the tag content as children, and wins over links and the allowed tags. ## SvelteKit Server-rendered pages arrive already translated in the visitor's language, and the browser takes over with the same language and catalog: no flash of untranslated text, no mismatch between server and browser. - Every page renders in the visitor's language, taken from the address when it carries one, and otherwise from their saved choice or `Accept-Language` header - No flash of untranslated text: the HTML the server sends and the page after hydration are identical, catalog included - Each request gets its own instance, so simultaneous visitors never see each other's language - A one-call language switcher: `switchLocale` loads the catalog, then persists the choice for the next server render SvelteKit needs the server package (`@verbaly/sveltekit`) alongside the Svelte package, the Vite plugin and the compiler: ```sh npm install verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite # or: pnpm add verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite # or: yarn add verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite # or: bun add verbaly @verbaly/sveltekit @verbaly/svelte @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 ``` `init` writes `verbaly.config.ts` and your source catalog. List your languages there (`locales: ['en', 'es']`): the build, `verbaly extract` and `verbaly check` all read them. ## Wire it up Three wires on the server, one on the client. First the Vite plugin and the `lang` placeholder: ```html title="vite.config.ts · src/app.html" // vite.config.ts import { sveltekit } from '@sveltejs/kit/vite'; import verbaly from '@verbaly/vite'; export default { plugins: [verbaly(), sveltekit()] }; ``` The server hook resolves the language per request and fills the placeholder. Pass `routing` and the address decides when it carries the language, falling back to the saved choice, then `Accept-Language`, then your fallback: ```ts title="src/hooks.server.ts · src/app.d.ts" // src/hooks.server.ts import { verbalyHandle } from '@verbaly/sveltekit'; import { locales, routing } from 'verbaly/app'; export const handle = verbalyHandle({ locales, routing }); // src/app.d.ts declare namespace App { interface Locals { verbalyLocale: string } } ``` Hand the language to the client, then build **one instance per render** with the catalog awaited, the no-flash guarantee: ```svelte title="src/routes/+layout.server.ts · +layout.ts · +layout.svelte" // +layout.server.ts export const load = ({ locals }) => ({ locale: locals.verbalyLocale }); // +layout.ts import { createRequestInstance } from 'verbaly/app'; export const load = async ({ data }) => ({ ...data, verbaly: await createRequestInstance(data.locale), // catalog ready BEFORE render }); {@render children()} ``` From here it's plain `@verbaly/svelte`: `useT()` / `useLocale()` stores and `Trans.svelte` work unchanged in every component. `$t` is typed by your catalog: the types go to `src/verbaly.d.ts`, the folder SvelteKit's `tsconfig` reads, so `svelte-check` sees them with nothing to configure and fails on a key no catalog has. > **Why hydration never flashes** > > The universal load runs on the server and again during hydration: same language from the hook, same catalog awaited before render. Both sides produce identical HTML, so nothing repaints and nothing mismatches. ## One route tree for every language If your pages live at `/es/docs`, you do not need a route folder per language. One universal hook makes `/es/docs` render through your `/docs` route, so your routes stay exactly as they were: ```ts title="src/hooks.ts" import { verbalyReroute } from '@verbaly/sveltekit'; import { locales } from 'verbaly/app'; export const reroute = verbalyReroute({ locales }); ``` It goes in `hooks.ts` and not `hooks.server.ts`, because moving between pages in the browser has to resolve the same way the server did. ## Switching languages `switchLocale` from `verbaly/app` already knows your languages and your URL mode. Hand it the instance this page renders with: with the language in the URL it goes to the same page in the other language, and without it it loads the catalog and switches the page in place. Either way it writes the cookie the server hook reads, so the next request already matches: ```svelte title="LangPicker.svelte" ``` - The cookie defaults to `verbaly-locale` (same identity as the core's storage key); `cookie: false` on either side disables it, for pure `Accept-Language`. - `fallback` defaults to your first language; negotiation follows the order of preference of the browser, and `es-PE` matches `es`. - No dependency on SvelteKit itself: the hook is typed structurally and stays compatible with SvelteKit 2 and 3. --- # Astro Source: https://verbaly.dev/docs/frameworks/astro The official Astro integration. One line in astro.config wires live extraction, typed keys and the build report; if you use the pre-translated mirror flow, verbaly render runs by itself after every build. What you can accomplish: - Write your text directly in `.astro` files, frontmatter and markup: keys, types and catalogs stay in sync while you code - Ship every language as static pages, with two flows to choose from - In the mirror flow, `verbaly render` runs by itself after every build: pre-translated pages, hreflang and a per-language sitemap with zero extra steps - A build that lists missing translations, the same report as every other Verbaly setup ## Installation Add the runtime and this integration, then the compiler, which is where the `verbaly` command lives. `init` writes your config and your source catalog. ```sh npm install verbaly @verbaly/astro # or: pnpm add verbaly @verbaly/astro # or: yarn add verbaly @verbaly/astro # or: bun add verbaly @verbaly/astro ``` ```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 ``` ## Wire it up ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; import verbaly from '@verbaly/astro'; export default defineConfig({ integrations: [verbaly()], }); ``` That single line injects the Vite plugin with your project root pinned: live extraction while you code, the typed `verbaly/app` module and the build report. The generated types live inside Astro's own `.astro` folder, and `npx verbaly extract` writes that same file, so none is added to your project. Options are the same as the Vite plugin (`locales`, `sourceLocale`, `dir`, `failOnMissing`…), and they live in your `verbaly.config`, where `verbaly check` and `verbaly extract` read them too. ## Write the text in place ```astro title="src/pages/index.astro" --- import { createRequestInstance, sourceLocale } from 'verbaly/app'; const { t } = await createRequestInstance(Astro.currentLocale ?? sourceLocale); const name = 'Ada'; const count = 3; const title = t`Search and find`; ---

{title}

{t`Hello ${name}, you have ${count} messages`}

{t`Company ``` The compiler reads your `.astro` files like any other source. The frontmatter and the markup expressions both extract, every message becomes a stable key with typed params, and an untranslated entry is listed by every build and fails `verbaly check` before it ships. ## Two ways to ship the languages Astro sites are static by default, so the language has to be decided at build time. Pick the flow that matches your routing: ### Path-based pages If Astro's i18n routing owns your URLs (`/es/…`, `/pt/…`), build one instance per request and use `t` as usual. Astro owns the routes, Verbaly owns the catalogs and the type safety. `createRequestInstance` waits for the catalog before it returns, which is what makes the page arrive translated instead of flashing, and `Astro.currentLocale` is empty outside a localized route, so the fallback is not decoration. ```astro title="src/pages/[locale]/index.astro" --- import { createRequestInstance, sourceLocale } from 'verbaly/app'; const { t } = await createRequestInstance(Astro.currentLocale ?? sourceLocale); --- ``` The integration reads `i18n` in your `astro.config`, so `switchLocale` and `localePath` go to the page Astro serves in the other language: your source language at the root and the rest under their prefix, or every language under one with `prefixDefaultLocale: true`. A prefix mode your `verbaly.config` names stays as it is, and so does Astro's `routing: 'manual'`. `npx verbaly doctor` shows the mode in use. In two cases Verbaly keeps one address, and the dev server and the build say so: - Astro's `defaultLocale` is not your `sourceLocale` and `prefixDefaultLocale` is off: make them the same language, or turn it on. - A language has a path that is none of its codes: use the language code as its path. ### Mirror mode One page tree, pre-translated in every language. Bind your markup with `data-verbaly` attributes and add a `render` section to your config. After `astro build`, the integration mirrors the site into `dist/es/`, `dist/pt/`… with every message pre-filled, plus hreflang alternates and a per-language sitemap when you set `baseUrl`. No flash of untranslated content, and no client work. ```js title="verbaly.config.mjs" export default { locales: ['en', 'es', 'pt'], render: { baseUrl: 'https://example.com', sitemap: true }, }; ``` The sitemap holds the pages a search engine should index. Your redirects and your 404 stay out of it, because they say so themselves, and they are still mirrored into every language so a visitor who reaches one gets it there. Leave more out with `render.exclude`. Every address the mirror writes, in hreflang, the sitemap, the canonical and the links between pages, follows your `trailingSlash`. With `'never'` the Spanish home is `/es`, so each page has one address. With ``, `verbaly/app` takes the language of each page before it swaps in, so a live `bindDom` paints the new page in its own language. It binds the whole document, so it keeps working after the router replaces the page's body. A mirrored site can go further: text that only one page shows does not need to reach the browser at all, because the mirror already wrote it into the HTML. Name those groups under `bundle` and every other page stops downloading them. ```js title="verbaly.config.mjs" export default { locales: ['en', 'es', 'pt'], bundle: { exclude: ['changelog'] }, render: { baseUrl: 'https://example.com', sitemap: true }, }; ``` ### Each page brings only its own words A mirrored page arrives already translated, and yet the visitor still downloads every message of that language, most of which the page never shows. Turn on `inlineCatalog` and the mirror writes into each page exactly the messages it renders, so a translated page needs no catalog of its own. ```js title="verbaly.config.mjs" export default { locales: ['en', 'es', 'pt'], render: { baseUrl: 'https://example.com', inlineCatalog: true }, }; ``` On this site the Spanish messages weigh about 59 KB compressed. The home page uses 3 KB of them, so a first visit stops downloading about 56 KB, nine times what all of Verbaly’s runtime weighs here. The heaviest page is the changelog, and even that one saves 25 KB. If your page later asks for a message it did not show, Verbaly fetches the rest once and updates, rather than quietly showing your source language. Your source pages get nothing extra: their messages already travel with the app. With `` this keeps working as the visitor clicks around, and you write no code for it: `verbaly/app` hands the runtime each page's own messages as that page swaps in. > **The mirror is opt-in** > > It only runs when your config has a `render` section (or you pass `render: true` to the integration), so path-based sites are never mirrored on top. Server output skips it too, and there the page above is the answer: build the instance per request from `Astro.currentLocale`. --- # Keys and catalogs Source: https://verbaly.dev/docs/guide/keys A catalog is a JSON file per language and a key is the name a message answers to. The default is that you never write one: you write text, and the compiler names it for you. This page is about the times you want the key to be yours, which is most projects that already have one. ## Five ways, one catalog They mix freely in the same project and end up in the same file. Pick per message, not per app. | You write | The key is | Reach for it when | | --- | --- | --- | | `` t`Hola {name}` `` | A hash of the text | Always, unless you have a reason not to. You never name anything and nothing drifts | | `` t.id('inbox.title')`…` `` | The id you gave it | You want to read the catalog, or a translator asked you to | | `t('inbox.title')` | The key you wrote | The text lives in the catalog, and you only write its key where you use it | | `defineKeys({ … })` | The id you declared | The key comes from data, or is shared with something outside this app, and its text lives only in the catalog | | `data-verbaly="inbox.title"` | The attribute value | The text is in HTML you do not compile, so nothing extracts it | ## The default: no key at all Write the sentence. The compiler hashes the text into a short stable id, writes it to your source catalog and generates the types. Change the wording and you get a new key, which is the point: a translation of the old sentence never silently stands in for the new one. ``` t`Hola {name}`; // locales/es.json "eYJLZELq": "Hola {name}" ``` ## Readable ids When you want to open the catalog and recognise things, name the message where you write it with `t.id`. The text stays in your code and the id is what lands in the file: ``` t.id('inbox.title')`Hello {name}`; // extracted under "inbox.title" and rewritten to: t('inbox.title', { name }); ``` The dots are a naming convention, and your catalog can spell them either way: one flat `"inbox.title"` key, or a `title` inside an `inbox` group. Every command reads both and writes back the shape your file already has, so nothing reformats your catalog for you. Dynamic ids (`t.id(someVar)`) are left untouched. One id written with two texts is reported with every place that disagrees, because all of them show the one written first, by file path, whatever order your files load in. ## Text that lives in the catalog You can also keep the text in the catalog and write only the key in your code. A key written as a literal counts as used, so `extract --prune` keeps it and `check` verifies it exists. Pick this when the wording changes more often than the code, or when someone edits the texts without opening a component. ``` // locales/es.json "about.bio": "Escribo software en Lima." t('about.bio'); ``` When the key comes from data, a map by slug or by id, declare it with `defineKeys`, below, so the compiler sees it and your editor checks it. ## Every key is typed Every `t` in your project checks its keys against your catalog: the one from `verbaly/app`, `useT()` in React, Vue and Svelte, `getT()` in Next.js, and the `t` of any instance. A key you write that no catalog has does not compile, the error names it, and a message with a `{name}` asks for it. ``` t('about.bio'); // ✓ t('about.boi'); // ✗ '"about.boi"' is not assignable to … VerbalyKey t(item.key); // ✓ a key from data passes as it is ``` A key that comes from data, a `string` or a template with a part from data like `` t(`status.${s}`) ``, passes as it is, since no catalog can tell which key it will be. A variable typed as a union of keys, `VerbalyKey` itself included, is data too: each key it can be has to exist, and its params are left open. Declare such keys with `defineKeys`, below, when you want `check` to verify they exist and `extract --prune` to keep them. ## Keys you already own Sometimes the key is the point: it is shared with a mobile app or a translation memory, it outlives any one component, and its text lives only in the catalog. Declare those with `defineKeys` and Verbaly treats them as used, so `extract --prune` keeps them and `check` verifies every one exists: ```ts title="texts.ts" import { defineKeys } from 'verbaly/app'; export const BannerText = defineKeys({ title: 'alerts_banner_title', button: 'alerts_banner_button', }); ``` The types come from your own catalog, so a key that does not exist is an error right there, on the line that declares it, and your editor completes the ones that do. Read them anywhere with `t(BannerText.title)`. Groups nest as deep as you like, and an empty value is skipped because empty means untranslated. > **Arriving with a catalog you cannot rename** > > Point `defineKeys` at the ids you already ship and nothing else has to change. ## Who owns a text A message keeps its text in one place, and that place is where you change it. A text written in your code, with `` t`…` `` or `t.id`, belongs to the code: `extract`, the dev servers and the build all use it, so an edit of it in the source catalog is replaced, and Verbaly tells you which file holds the text. A text that lives only in the catalog is edited there. Every command that reads a source text reads the one that ships: `check`, `status`, `review`, `translate`, `export`, `import`, Studio and agents. A translation remembers which text it was written for. For readable keys, Verbaly keeps a short fingerprint of the source text and of each translation in `verbaly.lock`, next to your config, taken the moment the translation is written, whoever writes it. Change a source text and its translations show up as outdated in `status`, `check` and `doctor` until someone updates them, or keeps them with `verbaly review --approve`. Editing a translation clears it on its own. Hashed keys never need this: new wording is a new key. > **Call it t** > > The compiler reads calls named `t`. `const tr = useT()` works at runtime, but `` tr`…` `` is never extracted, so that text stays in your source language. `extract`, `doctor` and the dev servers point at every such call with its file and line, in `.vue`, `.svelte` and `.astro` files too. `--prune` keeps the translations it reads until you rename it. Only a `useT` or `getT` from Verbaly counts, so another library's `t` is left alone. ## Keys in plain HTML Text that lives in HTML nobody compiles has no call site to extract, so the key travels on the element. Write the catalog first and point at it. This site is built that way, and [Plain HTML](https://verbaly.dev/docs/frameworks/dom.md) covers the whole interpreter. ```

Inbox

``` ## Two shapes of catalog Flat is what `extract` writes. Nested is what a person writes. Both are read everywhere, and every command writes back the shape the file already had, so a project never ends up half one and half the other. ``` // flat { "inbox.title": "Bandeja" } // nested, the same key { "inbox": { "title": "Bandeja" } } ``` ## Which languages you have If you do not list `locales`, every JSON file in your catalogs directory is a language, except the pseudo-locale one: drop a `pt.json` in and it is picked up. List `locales` and that list is the whole list, so a file left behind by an earlier run is ignored. `npx verbaly doctor` tells you which of the two is happening. > **Empty means untranslated** > > An empty string means untranslated, everywhere in the tool. `check` reports it, `translate` fills it, and the runtime falls back to your source language. If you want a message to be genuinely blank, write a single space. --- # Message format Source: https://verbaly.dev/docs/guide/format One small syntax, powered by native `Intl` underneath: plurals, gender and formatting without learning full ICU. ## Interpolation ``` "Hola {name}" → t('saludo', { name: 'Aron' }) ``` Values format themselves by type: numbers via `Intl.NumberFormat`, dates via `Intl.DateTimeFormat`, strings as-is. A number reads the way the language writes it, so `2026` comes out as `2,026` in English: pass `String(year)` when the value is a label, like the year in a copyright line, and not a quantity. A missing param shows the placeholder literally and warns once naming the message, so it’s easy to spot and never a crash. ## Formatters Append `:formatter` (with optional `/arg`) to a param: | Syntax | Result | | --- | --- | | {n:number} | Number as the language writes it: `1,234.56` / `1234,56` | | {n:integer} | Rounded, no decimals | | {n:percent} | `0.5` → `50%` | | {n:currency/EUR} | Currency with ISO code | | {d:date/long} | `dateStyle`: short · medium · long · full | | {d:time/short} | `timeStyle` variants | Custom formatters plug in at instance creation. The full signature is `(value, locale, arg?) => string`, where `locale` is the active language and `arg` is whatever follows the `/` in the placeholder: ``` createVerbaly({ formatters: { upper: (v) => String(v).toUpperCase() }, }); // "{word:upper}" → HOLA ``` ## Relative time, lists & units The format surface covers the rest of modern `Intl`, still with zero dependencies: ``` "Updated {when:relative}" → Updated 2 hours ago · yesterday "Ready {n:relative/day}" → Ready in 3 days "Works in {langs:list}" → Works in English, Spanish, and Portuguese "Pick {opts:list/or}" → Pick red, green, or blue "{d:unit/kilometer}" → 3 km ``` - `relative`: pass a `Date` and the unit picks itself against now (`Intl.RelativeTimeFormat` with `numeric: 'auto'`, so you get *yesterday*, not *1 day ago*); pass a number with an explicit unit (`relative/hour`). - `list`: arrays localize via `Intl.ListFormat`, conjunction by default, `/or` for disjunction, `/unit` for unit lists. Each item formats itself for the language. - `unit`: any CLDR unit id (`kilometer`, `megabyte`, `liter`…) through `Intl.NumberFormat`. - Bad data never crashes a render, and never slips by either. An unknown format, an invalid unit, a placeholder missing its argument, a list that is not a list: each one **warns once**, naming the message, and falls back to `String(value)`. ## Plurals and selects: one syntax ``` "{count | =0: sin mensajes | one: un mensaje | other: # mensajes}" "{gender | male: él | female: ella | other: elle}" ``` - Numbers match `=N` exact values first, then `Intl.PluralRules` categories (`zero one two few many other`). - Strings match their variant key, falling back to `other`. - `#` renders the number, formatted for the language. Variants nest placeholders and blocks freely, and two blocks that end together close with `}}`. - **Always include `other` in a plural block.** It is the catch-all, so a block without it renders nothing for any count it does not list. `verbaly check` fails on that, and also warns when a language needs forms your message lacks: Polish reaches `few` and `many` where English only needs `one` and `other`. If a catalog reaches your app without passing through the build, from a lazy loader or a CMS, the runtime warns in the console naming the message instead of rendering an empty string quietly. A gender or role block is different: leaving `other` out there is your choice, and Verbaly leaves it alone. In the text you write in code, a block takes its value from `${…}`, right after its opening brace. The compiler turns it into the same message a catalog holds: ``` t`Tienes {${count} | one: # mensaje | other: # mensajes}`; t`{${role} | admin: Administra el equipo | other: Ve el equipo}`; t`Total: {${total}:currency/EUR}`; // locales/es.json "NASxvaOz": "Tienes {count | one: # mensaje | other: # mensajes}" ``` > **Writing a block in code** > > The format name goes right after the colon, with no space. Inside the block the syntax is the one above: `#` is the number and the escapes are the same. A block written around a bare name, like `{count | …}`, stays text, and `verbaly extract` shows the spelling that works. ## If you need ICU Have existing ICU MessageFormat strings, or need its exact syntax? Write ICU and Verbaly detects it automatically and parses it into the same engine, with **zero extra dependencies**. ``` "{count, plural, one {# item} other {# items}}" "{gender, select, male {he} female {she} other {they}}" "{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}" ``` - Auto-detected per message: no config, no marker. Native and ICU messages coexist in the same catalog. - Supports `plural`, `select`, `selectordinal` (real ordinal rules), `{n, number/date/time, style}`, `#`, `=N`, nesting and `'…'` quoting. - **Checked like any other message.** A translation that flattened an ICU plural into plain text, or dropped a parameter from it, fails `verbaly check` exactly like a native one does. The same guard runs on what a machine translation returns and on what you import. - Prefer the native syntax by default; reach for ICU only when you need it. - ICU is read from your catalogs. Written inside `t``…` it stays text, and `verbaly extract` names the native block to write there instead. - **You only pay for it if you use it.** Verbaly reads your catalogs at build time, and the ICU parser goes into your app only when one of your messages needs it. That is about 544 bytes, and there is nothing to switch on. Relative time works the same way: another 318 bytes that only travel when a message asks for them. > **Messages that arrive after the build** > > Your catalogs are what Verbaly reads, so a message that reaches the app later, from a CMS or a fetched catalog, is the one case it cannot see coming. If those messages may use ICU or relative time, set `icu: true` or `relative: true` in your config. Without that, such a message shows its own source text or the raw value and says what is missing in the console, rather than half-rendering into something that looks almost right. ## Escapes | Write | Get | | --- | --- | | {{ | Literal `{` | | }} | Literal `}`, unless it closes two blocks at once | | \|\| | Literal `\|` inside variants | | ## | Literal `#` inside variants | In a catalog, a literal `{` or `}` is always written doubled. Text written in your code gets that for free, because `extract` doubles them for you; a catalog written by hand has to do it itself, translations included. A literal brace can sit right after a value: `` t`Selected {${count}}` `` shows "Selected {5}", and so does a price followed by `}`. Right after a block with variants, put a space before it: inside a block `}}` is an escape. In rich messages (`data-verbaly-rich` or ``) the numeric entity `{` also shows a literal brace: it decodes after parsing, so it never touches the placeholder syntax. > **Params are typed from the message** > > `{count | one: … | other: …}` infers `count: number`; selects infer `string`; `currency` infers `number`. Both the editor and CI catch a missing or misnamed param. --- # URL strategy Source: https://verbaly.dev/docs/guide/urls Two ways to carry the language: in the address, or not at all. This page is about picking one on purpose, because the choice decides your SEO and it is hard to change later. ## The two strategies | Strategy | What the visitor sees | Switching language is | | --- | --- | --- | | In the address | `/docs` in English, `/es/docs` in Spanish | A navigation to that address | | Not in the address | `/docs` in every language | The text changing where it is | Verbaly supports both. This site puts the language in the address on every page, because people reach documentation through search. An app behind a login is the other case: it changes language with one call and no navigation, from a single address. **The strategy follows the surface, not your taste.** ## Give the mode a name **You usually write nothing.** Verbaly reads your setup: if you build a version of your site per language you get addresses per language, and if you do not, one address serves all of them. Say it out loud only to disagree. ```js title="verbaly.config.mjs" export default { sourceLocale: 'en', locales: ['en', 'es', 'pt'], routing: 'prefix-all', // only when you disagree with what it read }; ``` | Mode | The address | When | | --- | --- | --- | | `prefix-except-source` | `/docs` and `/es/docs` | Anything people reach through search, which is most public sites | | `prefix-all` | `/en/docs` and `/es/docs` | When no language is the house language and every one is a guest | | `no-prefix` | `/docs` in every language | Behind a login, where nobody arrives from a search result | Switching is one line, and it is the same line in every mode. Import it from `verbaly/app`, where it already knows your languages, your source and your mode. ``` import { switchLocale } from 'verbaly/app'; await switchLocale('es'); ``` With the language in the address it goes to that address, keeping the query and the anchor, and that page is already written in Spanish, so there is no waiting and nothing flashes. Without it, the text changes where it stands and the address never moves. Either way it remembers the choice and sets the page language. Give it your framework's router and your app survives the switch: ``` await switchLocale('es', { navigate: (path) => router.push(path) }); ``` In SvelteKit and Nuxt each request renders with an instance of its own, so hand that one over: read `const verbaly = useVerbaly()` while the component sets up, then call `switchLocale('es', { instance: verbaly })`. Next.js has `useSwitchLocale()` for the same job. `npx verbaly doctor` says which mode you are in **and whether it read that from your config or worked it out**, so a mode nobody wrote down never looks like a decision somebody made. It also tells you when your settings ask for two things that cannot both be true. ## The head is half of what a search result shows A page can be translated everywhere you look and still tell a search engine it is in English. The title and the description live in the ``, where nobody sees them on the page, so they are easy to forget. Bind them like any other text: they are most of what a search result shows. ```html title="head.html" URL strategy ``` `verbaly render` fills them per language like the rest of the page, and counts the pages whose title never varies so you hear about it once instead of finding out from a search result. It never fails a build: a product name is allowed not to translate. > **At runtime the head translates too** > > `bindDom` binds the whole document, so a language switch that happens without a navigation translates the title and the description with the rest of the page. A root you pass yourself, like the body, leaves them out, and it says so the first time it finds a bound element it cannot reach. ## When the address carries the language, it wins Once the language is in the address, that is the answer, and nothing overrides it. Someone opens `/es/pricing` and gets Spanish, even if they picked English here yesterday. An address gets shared, linked and cached; a saved choice belongs to one person. The other half matters just as much: a page *without* a prefix is your source language, so someone who once picked Spanish will never find your English pages quietly translated. The saved choice and the browser language still decide one thing, and only one: where to send someone who arrives without a language in the address. See [Server-side](https://verbaly.dev/docs/guide/server.md) for the wiring per framework. ## The one difference that cannot be worked around Search engines index addresses, not languages. If your Spanish and your English share one address, only one of them can get indexed, and nothing you do at runtime changes that. `hreflang` is how you tell a search engine that two addresses are the same page in *different* languages, so with a single address there is nothing to connect. Google says the same: one URL per language, not a cookie and not a browser setting. > **Public content needs the address** > > If people find the page through search, put the language in the address. If they are already signed in, or the surface is a tool rather than a document, it does not matter. A dashboard, an editor and a playground lose nothing by keeping one address; a marketing site or a docs tree loses every language but one. ## What Verbaly gives you, by how you render Keeping the language stable across a click and across a refresh is a different problem depending on who builds the HTML. These are the three cases and what each one needs. | You render | In the address | Not in the address | | --- | --- | --- | | **In the browser**, a SPA with client routing | `localeFromPath` reads the language from the address on every route change | `resolveLocale` + `persistLocale`. Clicking never reloads, and a refresh reads the saved choice back | | **On a server**, SvelteKit, Nuxt or Next.js | Your framework's router owns the segment, Verbaly owns the catalogs | `resolveRequestLocale` reads the cookie per request, so the document arrives already translated. Wired for you in all three integrations | | **At build time**, Astro, Eleventy or any SSG | `verbaly render` writes your site in every language, with `hreflang` and a sitemap | **Nothing can do this well.** One document is served to everyone, so the language can only change after it arrives | ## Why the last cell is empty everywhere, not just here A static host sends the same file to every visitor. To show another language without changing the address, something has to run *before* the HTML is sent, and on a static site nothing does. The libraries that offer this mode all solve it with a server reading a cookie: next-intl rewrites in middleware, and says plainly that with Next.js static export the middleware does not run at all. Verbaly does not pretend otherwise. Your options, in the order we would try them: - **Put it in the address.** `verbaly render`, and `render.redirect` so a visitor lands in their language without ever seeing the choice happen. This is what this site does. - **Use a subdomain per language.** `es.example.com` has no segment in the path and still has its own address, so search keeps working. This is the option people forget. - **Rewrite at the edge.** Your host can serve the pre-rendered `/es/` file at the plain address based on a cookie. It works, and it costs you: one language indexed, and a cache entry per cookie value on your CDN. - **Accept the swap.** Ship the source language and let `bindDom` replace the text once the catalog loads. Fine behind a login screen, visible on a cold page load. The address buys you one more thing. With `render.inlineCatalog`, each page carries only the messages it shows, so someone reading one page in a translated language no longer downloads that whole language. One thing to know if you route on the client: each page carries its own messages, so your router has to hand them over as it swaps documents, with `adoptPage` from `verbaly/app`. Astro's `` is wired for you. The prefix reaches every link, including the ones written inside a sentence. A message that names a link (`the guide`) is treated exactly like an `
` you wrote yourself. So a reader who clicks mid-paragraph stays in their language instead of landing on your source one. ## Keeping one address, in practice In the browser it is two calls. `resolveLocale` picks the language for a visitor who arrives with no address to read it from, and `persistLocale` remembers the switch so the next refresh agrees. ```ts title="src/i18n.ts" import { createVerbaly, persistLocale, resolveLocale } from 'verbaly'; const supported = ['en', 'es', 'pt']; export const i18n = createVerbaly({ locale: resolveLocale({ supported, path: false }), // no language in the address fallback: 'en', loaders: { es: () => import('./locales/es.json') }, }); export async function switchTo(locale) { await i18n.loadLocale(locale); // catalog first, so the text never flashes i18n.setLocale(locale); persistLocale(locale); // storage + + } ``` `path: false` is the part worth knowing. By default `resolveLocale` reads the first segment of the address before anything else, because on a site that does put the language there, the address is the only source that cannot contradict the page. Turn it off when your addresses are not languages, and a route called `/es` can never be mistaken for Spanish. On a server the same idea happens one step earlier. `resolveRequestLocale` reads the cookie, falls back to `Accept-Language`, and hands the language to the instance that renders the response, so nobody ever receives a page in the wrong one. `@verbaly/sveltekit`, `@verbaly/nuxt` and `@verbaly/next` already do this for you. `switchLocale` is the other half, in the browser: it writes the cookie the server will read. ``` // the same decision, made before the html exists const locale = resolveRequestLocale({ supported, cookie, header }); ``` ## Changing your mind later Going from one address to many is cheap: turn on `render`, and every language gets its own address plus `hreflang`. Going the other way costs you the addresses you already published, and search engines will keep them for a long time, so redirect rather than delete. Neither direction touches your messages, your keys or your catalogs: **this is a routing decision, not a translation one.** --- # Server-side Source: https://verbaly.dev/docs/guide/server The core runs anywhere JavaScript does, including Node. Create an instance, pass the language, call `t()`. No DOM required. ## One instance per request Build a fresh instance per request and hand it the visitor's language. `negotiateLocale` reads the `Accept-Language` header and picks the best match among your languages (it understands quality values, and `es-PE` matches `es`). `resolveRequestLocale` makes the whole decision in one call: the address first when it carries the language, then the saved choice, then the browser, then your fallback. Instances don't share state, so two requests never mix their languages. ```ts title="server.ts" import { createVerbaly, negotiateLocale } from 'verbaly'; import es from './locales/es.json'; import en from './locales/en.json'; function handle(req) { const locale = negotiateLocale(req.headers['accept-language'], ['en', 'es']); const v = createVerbaly({ locale, fallback: 'en', messages: { en, es } }); return v.t('home.title'); } ``` > **Always pass a language** > > Auto-detection is browser-only: on the server there's no user to detect. Without an explicit `locale` the instance defaults to `en`, never the machine's language. ## When your addresses carry the language If your pages live at `/es/dashboard`, that address is the answer. Anyone who opens the link gets Spanish, whether or not they ever picked a language here, because an address is public and shared while a saved choice belongs to one person. A page without a prefix then means your source language, so a visitor who once chose Spanish never sees your English pages translated by accident. You switch this on by telling your integration the `routing` you already set. Here is the whole of it, per stack: | Stack | What you write | | --- | --- | | SvelteKit | Pass `routing` to `verbalyHandle`, and add `verbalyReroute` in `hooks.ts` so one route tree serves every language | | Nuxt | Nothing: the module reads the address for you | | Next.js | `routing: 'prefix-all'` in your config and the `[locale]` segment in your root layout. Before Next 16.3, also `setRequestLocale(locale)` in every layout and page | | Astro | `createRequestInstance(Astro.currentLocale ?? sourceLocale)` in the page | > **On Next.js this is also what keeps your pages fast** > > Without the language in hand, Verbaly has to read the request headers to find it, and reading them is what makes Next build the page on every visit instead of once. Pass the segment and no header is read, so the page can be built ahead of time again. A route with no request at all, like an OG image or a sitemap, calls `getT({ locale })` with the language it wants and reads nothing either. Your pages can also point search engines at each other. `alternateLinks` gives you the list of addresses for one page in every language, the same list a statically rendered site gets, so a server-rendered page is not a second-class citizen. See [URL strategy](https://verbaly.dev/docs/guide/urls.md). ## Render HTML ahead of time For static sites, `verbaly render` pre-fills your built HTML per language so pages ship already translated. See [CLI → Static rendering](https://verbaly.dev/docs/reference/cli.md). ## Meta-frameworks On SvelteKit, Nuxt and Next.js you do not wire any of this by hand. [The SvelteKit integration](https://verbaly.dev/docs/frameworks/svelte.md#sveltekit), [the Nuxt module](https://verbaly.dev/docs/frameworks/vue.md#nuxt) and [the Next.js integration](https://verbaly.dev/docs/frameworks/react.md#next) pick the language per request and load in the browser without a flash, all with these same functions. --- # Testing Source: https://verbaly.dev/docs/guide/testing A test does not need the plugin, the project module or your catalogs on disk. Build an instance with the messages that test cares about and hand it to the provider. That is how the adapters themselves are tested. ## An instance is all you need `createVerbaly` takes the messages inline, so a test names the two or three it asserts on and nothing else. No mocking, because there is nothing to mock. ```tsx title="hello.test.tsx" import { createVerbaly } from 'verbaly'; import { VerbalyProvider } from '@verbaly/react'; const verbaly = createVerbaly({ locale: 'es', messages: { es: { hello: 'Hola {name}' } }, }); render( ); expect(screen.getByText('Hola Aron')).toBeVisible(); ``` ## Assert on the text, not the key Give the instance your source language and your assertions read like the screen does. A test that matches a key is a test that passes while the interface is empty, because a key that resolves to nothing renders as itself. ## Changing language in a test `setLocale` on an instance does not wait. It swaps the language and asks for the catalog behind you, so with a real lazy catalog an assertion on the next line reads the old text. Await `loadLocale` first and then switch. With messages passed inline there is nothing to fetch, so both lines are instant. The `setLocale` of `verbaly/app` does wait: it returns a promise. ```ts title="switch.test.ts" await verbaly.loadLocale('en'); verbaly.setLocale('en'); expect(verbaly.t('hello', { name: 'Aron' })).toBe('Hello Aron'); ``` ## Testing against your real catalogs Import the JSON and pass it in. It is the same shape either way, flat or nested, because the runtime flattens what it is given. Useful for a snapshot of one screen in every language, and unnecessary for everything else. ```ts title="screen.test.ts" import es from '../locales/es.json'; const verbaly = createVerbaly({ locale: 'es', messages: { es } }); ``` > **You are already testing the translations** > > `npx verbaly check` in CI is what verifies every message exists in every language and that each translation can render what its source renders. Your unit tests do not have to repeat that, and a test per language is usually a test of Verbaly rather than of your code. ## If a test imports the project module Code that imports from `verbaly/app` needs the plugin present when that file is loaded. In Vitest that means adding the same plugin your app uses to the test config, and then a component under test needs no wrapper: with no provider above it, `useT()` reads the instance the plugin creates, as in the browser. The simpler path is still to keep `verbaly/app` out of the units you test and pass the instance in, which is what the adapters do. --- # Work with translators Source: https://verbaly.dev/docs/guide/translators Your catalogs are plain JSON, with nothing proprietary to convert. That gives you three ways to get translations done: hand the files to a TMS, round-trip translator files with `export`/`import`, or machine-translate with `translate`. ## Plain JSON, no lock-in Most TMS platforms (Crowdin, Lokalise, Phrase and friends) ingest JSON catalogs natively. Point the platform at `locales/` and you're done: no export step, no custom format. Translations come back as the same files, and every change reviews like a normal diff. ## Export for humans When there's no TMS (a freelance translator, an agency, a coworker with a spreadsheet), `verbaly export` writes one translator-ready file per language, with the source text next to each translation. If you keep your catalog in groups, it exports one row per message, named by its full path, so a translator sees text and never a group. ```sh npx verbaly export # verbaly-export/es.xlf, pt.xlf (XLIFF 2.0) npx verbaly export --format csv # key,source,target,location (any spreadsheet) npx verbaly export --format po # es.po, pt.po (gettext, any PO editor) npx verbaly export --missing # only what's untranslated ``` XLIFF 2.0 is the industry interchange format, so TMS and CAT tools open it directly. Your placeholders and tags travel in it as protected chips with meaningful names, so a translator cannot break them by accident; plural and select words stay editable, because those do need translating. Gettext PO works with Poedit and any PO tool, and CSV is for everyone else, editable anywhere. Every format says where each text lives in your source, so the translator sees the context instead of guessing it. Before exporting, `verbaly status` shows how much is left per language: `es: 45/48 translated (94%)`. ## Import back, validated `verbaly import` reads the translated files (XLIFF 2.0 or 1.2, CSV or gettext PO) and fills your catalogs. A CSV your spreadsheet saved with semicolons or tabs is read like one with commas. Every entry passes the same structural validation as machine translation: placeholders, plural variants and tags must survive verbatim. Anything else is rejected and reported, never written. ```sh npx verbaly import verbaly-export/es.xlf # es: +42 imported # es: 1 rejected (params/tags not preserved): home.greeting npx verbaly import es.csv --dry-run # preview without writing npx verbaly import es.xlf --overwrite # replace existing translations npx verbaly import es.xlf --draft # keep it as drafts until someone reads it ``` Existing translations are kept unless you pass `--overwrite`; unknown keys are ignored and reported. Entries a PO tool marks as fuzzy count as untranslated. The target language comes from the file itself (or the filename), and `--locale` overrides both. It is read as one of your languages, so gettext's `pt_BR` fills your `pt-BR`. A new language starts its catalog under its proper code, unless your config lists its `locales`: then a language outside that list is skipped with a warning and exit code `1`, since your app would never load it. Pass `--draft` when nobody has read the file yet: what it brings stays marked as drafts until someone approves it. > **A typo can't reach your UI** > > A translation that drops a placeholder or unwraps a tag stays out of the catalog and shows up in the import report, so `check` keeps failing until it's fixed. It's the same gate `translate` and `pseudo` use. ## The safety net, in plain words Editing `locales/es.json` by hand is a perfectly good way to translate, and it gets the same protection as an imported file. `verbaly check` reads every translation next to its source and fails when the translation cannot say the same thing, and every build lists it. You do not have to remember these rules: if you break one, the error tells you which and where. - **Keep every `{placeholder}`, spelled the same.** It is the slot where a name, a count or a date goes. Translate the words around it, never the word inside it. - **Keep the tags as pairs.** `…` and friends mark emphasis or a link. Move them to wherever the phrase needs them, but do not drop one half. Words that only look like a tag are yours to translate: in `Press to continue` nothing closes that bracket, so nothing is checking it. - **Keep the plural block a plural block,** and always keep its `other` case. That case is the catch-all: without it, any count you did not list shows nothing at all. - **Add the forms your language needs.** English gets by with two, Polish and Arabic need more. Verbaly warns you which ones are missing, and that one is advice, not a failure. When someone changes a source text, its translations are not kept as if nothing had happened. Verbaly records which source text a translation was written for the moment it is written, by a provider, an agent, Studio or an imported file. Once that text changes, it flags the translation as outdated until it is updated, or kept with `verbaly review --approve` when it still says the right thing. A translator's file brings the source text it was made from, so a file translated from an older version reads as outdated as soon as it lands. Editing a translation clears the flag on its own. `npx verbaly status` is the quick look: how much is translated per language, how much is waiting for review, how much is outdated and how much is broken. ## Export for mobile apps The same catalogs can ship to a companion mobile app as native resources: `android-xml` writes `strings.xml` folders you can drop into `res/`, and `ios-strings` writes `.lproj` folders for Xcode. ```sh npx verbaly export --format android-xml # verbaly-export/values-es/strings.xml, values-pt-rBR/… npx verbaly export --format ios-strings # verbaly-export/es.lproj/Localizable.strings, … ``` Your source language becomes the platform default (`values/strings.xml`, `en.lproj`), and untranslated keys are left out so the app falls back to it instead of showing empty text. Keys are adapted to valid Android resource names, values keep their parameter syntax untouched, and the flow is one-way: translations go from your catalogs to the app. ## No humans available yet? [Machine translation](https://verbaly.dev/docs/reference/cli.md) fills the gaps with the same structural guarantees, and everything a provider or a person gets wrong is caught by `verbaly check` in CI. Machine output arrives marked as drafts: `translate` records what it wrote in `verbaly.lock`, next to your config. Like a package lockfile, Verbaly writes it and you commit it with your catalogs, and nobody edits it by hand, so nobody confuses machine output with reviewed work. If a merge leaves it with a conflict, Verbaly keeps the drafts of both sides and the next `extract` writes it whole: commit it with the merge. Deleting it would mark every draft as reviewed. ```sh npx verbaly translate # es: +12 translated (draft) npx verbaly review # list what's waiting for a human npx verbaly review --approve # accept after reading npx verbaly check --drafts # CI gate: fail while drafts remain ``` Before the first run, write down what must not be translated. Product names, feature names and any wording you have already settled on go in `translate.glossary`, and how you address the reader goes in `translate.instructions`. That is cheaper than fixing the same word by hand after every run. A long run survives a bad connection, and being cut halfway. Requests that fail for a passing reason are tried again. Each language is saved as soon as all of its messages are back, so closing the terminal halfway keeps the languages that finished. When a request still does not come back, or the file of a language cannot be saved, the report names those messages and the rest is saved. Running `translate` again asks only for what is left, so an interrupted run never costs you the whole thing twice. It never costs a person their work either: a message someone saved while the run was out keeps its text, and the report says how many it left alone. `verbaly review` lists what is waiting, machine drafts and translations written for an older source text, each with the text that ships next to its translation. `verbaly review --approve` accepts it after reading, followed by keys when you want to accept only those, and a translator file brought in with `import` counts as review on its own. In CI, `verbaly check --drafts` keeps failing while unreviewed drafts remain, and `--outdated` while an outdated translation does. A coding agent can run this same loop through the [MCP server](https://verbaly.dev/docs/guide/agents.md): whatever it translates still arrives as a draft behind the same review gate, the translations it writes itself included. --- # Coding agents Source: https://verbaly.dev/docs/guide/agents An agent writing your app also writes the text in it. There are three ways to hand it the cycle, and they answer different questions: run the commands, learn the rules, or read the docs. ## Three channels, three questions | Channel | What it answers | What it needs | | --- | --- | --- | | MCP server | Run the cycle: diagnose, wrap the text you already wrote, extract, translate | One line in your MCP client | | Agent Skill | Write the code right the first time: the rules that keep the cycle safe | One command in your project | | llms.txt | Find the right page: an index of these docs, each page also in Markdown | Nothing, it is already served | They stack. The skill teaches the rules, the server does the work, and the index is what an agent reads when it needs more than either. **None of them can approve a machine translation**, and the end of this page says why. ### The server and the skill in one install In Claude Code a plugin brings the two together. Add the repository as a marketplace, then install the plugin from it: ```sh claude plugin marketplace add verbaly-i18n/verbaly claude plugin install verbaly@verbaly ``` Gemini CLI takes the same pair as an extension: ```sh gemini extensions install https://github.com/verbaly-i18n/verbaly ``` ## The MCP server `@verbaly/mcp` exposes the cycle as tools over the Model Context Protocol, so an agent runs it without touching a shell. Every MCP client starts it with the same command, `npx -y @verbaly/mcp`, and each one has its own place to write it. | Client | How to add it | | --- | --- | | Claude Code | `claude mcp add verbaly -- npx -y @verbaly/mcp` | | Codex | `codex mcp add verbaly -- npx -y @verbaly/mcp` | | VS Code | Run **MCP: Add Server** from the Command Palette, choose **Command (stdio)** and enter `npx -y @verbaly/mcp` | | Cursor | [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=verbaly&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZXJiYWx5L21jcCJdfQ%3D%3D), or the entry below in `.cursor/mcp.json` | | Gemini CLI | The entry below, in `.gemini/settings.json` | ``` { "mcpServers": { "verbaly": { "command": "npx", "args": ["-y", "@verbaly/mcp"] } } } ``` Any other client takes the same entry wherever it keeps its servers. The server reads your `verbaly.config` from the directory it starts in. Pass `--root` when that is not your project, and every tool also takes a `root` of its own for a monorepo with more than one app. ### The tools They are listed in the order an agent meets a project: set it up, find out what is wrong, wrap the text that is already there, then run the cycle over it. That is the order the server hands them over in, not just the order of this page. | Tool | What it does | Writes? | | --- | --- | --- | | verbaly_init | Creates your settings file and your language files, and works out which bundler or framework you use so it can name the one line you still have to add. A language given as pt_BR is written pt-BR, and it says so | Yes | | verbaly_doctor | Checks the whole setup at once: config, catalogs, the plugin for your framework, the generated types, files it could not read and every translation the gate would reject | No | | verbaly_wrap | Finds text written straight into your JSX and wraps it so the compiler can pick it up. It reports by default, and text it cannot handle safely is listed rather than rewritten | Yes | | verbaly_extract | Scans your source, adds new messages to the catalogs and refreshes the generated types. A key it prunes takes its draft along. The answer names, with file and line, any file it could not read, any key written with two texts, any `t` it cannot read because it goes by another name, any source text your code wrote over and any value a translator would see without a name. When it creates `verbaly.lock`, moves an older state file into it or rewrites it whole after a merge conflict, the answer says so, and the agent can tell you to commit it | Yes | | verbaly_status | Coverage per language, plus how many machine translations are waiting for a human and how many translations were written for an older text. A state file it cannot read is reported in the answer, never as a failure | No | | verbaly_missing | Everything the CI gate would fail on: missing translations, unknown keys, keys written with two texts and translations that exist but cannot render what the source renders. It also lists what never fails it: keys only a translation has, a catalog that says something your code does not, and translations written for an older text. Every path in it is relative to your project | No | | verbaly_translate | Fills the gaps through your configured provider, and saves each language as a draft as soon as it is complete. A message someone wrote while it worked is left as written, and the answer names it. When it creates `verbaly.lock`, the answer says so, and the agent can tell you to commit it | Yes | | verbaly_write_drafts | Saves the translations the agent wrote itself. Each one is checked like a machine translation against the text your code ships, and written only for keys your source language has. It is marked as a draft for you to review, with a note of the text it was written for. It keeps what is already translated unless told to rewrite it. When it creates `verbaly.lock`, the answer says so, and the agent can tell you to commit it | Yes | | verbaly_drafts | Every machine translation still waiting for you, each next to the sentence it came from, so you can read both before deciding | No | The ones that only read say so to the client, so an agent can look at the state of your project without permission to change anything. The ones that write tell you first: extract and translate take a `dryRun` that reports what would happen, and wrap reports unless you ask it to apply. Every tool answers twice: a sentence for a person reading the transcript, and the same answer as data. An agent asking for coverage gets the numbers themselves, not a line to pick apart, so it keeps working when we word something differently. A tool that fails comes back as a message the agent can act on, never as a crashed server. A missing config file says so, and so does a catalog that is not valid JSON. A language the project does not have is an error too, with the list of the ones it has, so a typo never reads as nothing left to translate. A state file a merge left broken only adds a line to the answers that read it, and the tools that would write drafts stop before writing anything. Translating is the one step that can be interrupted halfway, because it goes out over the network. Each language is saved as soon as it is complete, so a run that is cut keeps what it finished. When a piece does not come back, or a language cannot be saved, the answer names exactly which messages are left, so asking again costs only what is missing. ### What it can read Every tool above works in keys and counts, which is enough to tell you that fourteen translations are missing and not enough to show you one of them. Two **resources** close that: an agent reads them by address, so looking at your project does not use up one of its actions. | Address | What it holds | | --- | --- | | verbaly://config | Which language you write in, which ones you translate to, where your language files live and whether the language shows in your addresses | | verbaly://catalog/{locale} | Every message of one language, exactly as your app ships them: a text your code owns reads as your code has it. An empty value means nobody has translated it yet | This is what makes reviewing a machine translation possible through an agent. Before, you were handed a key and asked to approve it, which is not a review. Now you see the sentence it came from next to what the machine wrote, and the decision stays yours. ## The Agent Skill A server tells an agent what it can run. A skill tells it what to write. The [Verbaly Agent Skill](https://github.com/verbaly-i18n/verbaly/tree/develop/skills/verbaly) lives in the repository and carries the cycle plus the rules that keep it safe, so an agent stops inventing catalog keys by hand. ```sh npx skills add verbaly-i18n/verbaly ``` The command asks which agents you use and copies the skill into the folder each one reads. The rules it carries are the ones that are easy to get wrong from the outside. - Keys are generated, or come from the catalog the project already has. The agent never invents one. - `""` in a catalog means untranslated, not empty on purpose. - Placeholders and tags have to survive a translation word for word. - A link goes through a named tag plus a links map, never a literal `` inside a message. - A translation it writes itself is saved with `verbaly_write_drafts`, never typed into a catalog. ## llms.txt This site serves [/llms.txt](https://verbaly.dev/llms.txt), a markdown index of every documentation page with a line on what each one covers. It is generated from the same sidebar you are looking at, so it cannot drift from the real docs. It is for the agent that reads before it writes. Each page it lists is plain Markdown at its own address plus `.md`, and [/llms-full.txt](https://verbaly.dev/llms-full.txt) holds all of them in one file. Point yours at the index when it needs the map, at one page when it needs one answer, and at the full file when it needs everything. ## Why an agent cannot approve its own translation Everything `verbaly_translate` produces is a draft, and so is everything an agent saves with `verbaly_write_drafts`, and drafts do not ship: with `verbaly check --drafts` in CI, the build keeps failing while any remain. Accepting one is `verbaly review --approve` or the local review server, and neither is exposed to agents: an agent approving its own translation is the safeguard approving itself. > **A machine can translate, a person decides** > > An agent that could both translate and approve would give you a fully green project nobody has read. The draft flag is the whole point of the loop, so the one step that needs a human stays with the human. --- # Studio Source: https://verbaly.dev/docs/guide/studio Your JSON catalogs are the database and git is the history. Studio is a window onto them, which is why it cannot drift from your code: it does not own anything. ## What you get **It opens on what needs you.** The first screen lists what is waiting, one line each: translations that break your site, messages with nothing in them, machine drafts nobody has read, keys your code calls that no catalog defines, and keys only a translation has. The first three open the table on exactly those messages; the last two have no row to open, so they name their keys instead. Beside that it shows how many of `doctor`’s checks pass, and the last commits that touched your catalog folder. The commits card needs a git repository; without one it is simply not there. **The search box reads your text, never the key.** It looks in every language you have, not only the ones you ticked, and each result says where it matched. `Command K` opens it, the arrows move, enter takes you to that message in the table. **The first part of a key is its group:** `nav.home` belongs to `nav`. The rail lists every group with how many messages it holds and how many still need you, and picking one narrows the table. A key with no dot has no group, and Verbaly does not invent one. The table holds every message in your project, in as many languages as you tick. Each one shows its state: ready, missing, written by a machine and unread, or broken. You fix it in the row itself, and the check runs while you type. Two commands run from the page. **Find new text** reads your code and adds what your catalogs do not have. **Translate what is missing** calls your provider: it shows the count and the languages before anything is spent, what comes back stays a draft until you read it, and a message you save while it runs keeps your text. **Every row has a menu.** Copy the key, copy the source text, start editing without leaving the table, see the files that use that message, and see the commit that last changed it. **The commit is read from your catalogs’ history, by comparing what each message said and not the line it sat on.** Adding a key rewrites the comma on the line above it, so asking git who touched a line names the wrong commit often enough to matter. When there is no answer the menu says which kind: a message you have not committed yet, one older than the history it read, or a project with no git in it. ## Run it ```sh npm install -D @verbaly/studio # or: pnpm add -D @verbaly/studio # or: yarn add -D @verbaly/studio # or: bun add -D @verbaly/studio ``` ```sh npx verbaly-studio ``` It prints the address it is serving, the project it read and what is in it. The address carries a key, minted fresh on every start, so nothing else on your machine can reach it by guessing the port. ## The command | Flag | What it does | | --- | --- | | `--root ` | Point at another project instead of the folder you are in | | `--port ` | Start somewhere other than 4747; a busy port climbs to the next free one | | `--json` | Print the whole state and exit, no server. This is the panel without the panel: the same object the screen will read, so you can pipe it, diff it and script it | ## It never edits your source text Your source text lives in your code, and the key comes from that text. Writing over it here would be undone by your next extract, so Studio refuses it. It also refuses a key your source catalog does not have: accepting one would invent a message no line of your code asks for. A translation you save runs the same two checks your build runs. A lost `{name}`, a lost tag or a plural missing its catch-all case is refused, with the reason. Saving is also accepting: once a person writes it, it stops counting as a machine draft. **Your file keeps the order you gave it.** A save rewrites the one line it changed, never the whole catalog. A group you ordered by hand stays in that order and a new key lands at its end; a group that was already alphabetical keeps sorting. The diff you review is the edit you made. ## The addresses Every one of them calls the same function the CLI calls, so there is no second implementation to keep in step. Every answer is JSON, errors included. | Address | What it gives you | | --- | --- | | `GET /api/state` | The whole project in one answer: your settings, every catalog, where each message is used, the coverage, what verbaly check says, the machine drafts, the triage and anything it could not read | | `GET /api/health` | The same diagnosis `verbaly doctor` prints | | `GET /api/commit/:key` | The commit that last changed that message, or which of the three reasons there is none | | `PUT /api/message/:locale/:key` | Write one translation and stop counting it as a draft | | `POST /api/approve` | Accept machine drafts: a list of keys, or the whole language at once | | `POST /api/extract` | Read your code and add what your catalogs do not have. It answers inside the request, because it is local and costs nothing | | `GET /api/translate` | The bill: how many messages and in which languages, without calling your provider. Looking at the cost cannot start the spending, which is why it is its own address | | `POST /api/translate` | Start the run and get back a job. One at a time, because two runs over the same catalogs is a race over the same files | | `GET /api/job/:id` | How that run is going, to ask once a second | | `GET /api/job` | The run in progress, or nothing. A reloaded page has lost the id, and a job you cannot ask about again is a stream with extra steps | The state comes in one piece, not in pages. Even a catalog of a few thousand messages across three languages answers in a fraction of a second on your own machine. ## Nothing it reads can take it down A catalog it cannot read, a drafts file it cannot read, a source file that will not compile, a folder with no catalogs in it: each one is reported by name, and everything else still loads. Studio is what you open to fix those files, so it has to open. ## Which machine translations to read first Adding a language writes hundreds of drafts at once. Reading them one by one is how people end up skipping the review altogether, so Studio ranks them instead of queuing them. Your build already caught the structure; what is left is meaning. These signals do not score a translation, they point at the few worth your eyes. Tick a single language and the table becomes that language. A bar above it says how many messages it holds, that they are already on your site, and that your build check passes. Three chips split them into everything, worth a look, and nothing odd. Every flagged row carries its reason beside it: which link changed, which number moved. Tick a second language and the comparison table is back, because a reason belongs to a language, not to a row. | Signal | What it means | | --- | --- | | `divergent` | A language you already reviewed wrote this same source text two different ways, so the source itself is ambiguous | | `collision` | The same doubt seen in the result, when no reviewed language can settle it | | `echo` | Still word for word the source, while every language with an opinion did translate it | | `digits` | A number the source has came back changed, ignoring the comma or dot a language writes differently | | `url` | A link changed | | `code` | What is inside a code span changed | The signals were tuned against real translations, not invented at a desk. Two of them are gone, because everything they flagged turned out to be correct text. What is left is a short list, not a queue. > **Why Studio may approve and your agent may not** > > No tool in the MCP server can accept a machine draft. An agent approving its own translation is the safeguard approving itself. Studio is the other side of that line: the place where a person reads the source and the translation next to each other. The key it prints is what says a person is here, so keep it out of an agent’s prompt. ## It writes files, so it defends itself Any page open in your browser can talk to a server running on your machine, so three defences are on and cannot be turned off. - It listens only on your own machine, never on the network. - It refuses a request that claims to come from anywhere else, which is what stops another site from pointing its own name at your machine. - The key it mints at startup is compared whole, so it cannot be guessed one character at a time. Requests are capped, and the full path of your project is stripped out of every error before the browser sees it. --- # When something breaks Source: https://verbaly.dev/docs/guide/troubleshooting Start with `npx verbaly doctor`. It inspects the whole setup and prints the exact fix next to each finding, so most of this page is what it would have told you. ## The verbaly command is not found The command lives in `@verbaly/compiler`. The plugins depend on it, but a package manager only links a command for a package you installed yourself, so a plugin bringing it along is not enough. Add it to your dev dependencies: ```sh pnpm add -D @verbaly/compiler ``` ## A language appeared that I never asked for If you do not list `locales`, every JSON file in your catalogs directory counts as a language, the pseudo-locale one aside. So a file left behind by an earlier run becomes one too, and the build starts asking for its translations. List your languages and the list is complete: ``` locales: ['es', 'en'] // now a stray pt.json is ignored ``` ## A warning says a language is not a locale tag `pt-BR` is how a language code is written, with a hyphen between its parts. `pt_BR`, the way gettext and many backends write it, is not a code a browser can read. Verbaly reads it as `pt-BR` to keep numbers, dates and plurals formatting, and warns once that it did. A code with no sure fix formats in the browser's default language, with the same warning. `doctor` names each one in your config with its rename: change the catalog's file name and your config together. ``` [verbaly] "pt_BR" is not a locale tag, so Intl reads it as pt-BR ``` ## wrap reported files it did not write A file where `t` is not available is listed and left untouched, because wrapping text there would stop your project compiling. The report says how many texts wait in each file and whether it is a client component, so you know which line to add. Add it and run it again. ## The build says a translation is broken Not missing, broken: the translation is there and cannot render what the source renders. It lost a `{value}`, dropped a plural case or changed a tag. Every build lists these first, because they render wrong, and `npx verbaly check` gives the exact reason per message and fails on them in CI. ## The build compiled, then listed translations That is where the check runs. In Next.js, `next build` compiles your app first and then lists missing, broken and unknown keys, so commands that only load your config, like `next typegen`, never run it. Fill what it lists, or run `npx verbaly check` before you build to see the same list sooner. With `failOnMissing: true` the build stops there instead. ## The build says an option is set in the plugin `verbaly check` and `verbaly extract` read your `verbaly.config`, never the options you pass to the plugin. When the two disagree, the command line checks something other than what the build ships. Move the option to the file and the warning goes away. ``` [verbaly] sourceLocale is set in the plugin options, which `verbaly check` and `verbaly extract` never read: move it to verbaly.config so the command line checks what the build ships ``` ## switchLocale stays on the same address in Astro Your Astro `i18n` and your Verbaly config do not match, so `switchLocale` and `localePath` keep one address instead of sending the visitor to a page that does not exist. The dev server and the build say which of the two cases it is: Astro's `defaultLocale` is not your `sourceLocale`, or a language has a path that is none of its codes. For the first, make them the same language or set `prefixDefaultLocale: true`. For the second, use the language code as its path. ``` [verbaly] Astro's i18n serves its defaultLocale "es" at the root, but Verbaly's sourceLocale "en" is the language without a prefix, so switchLocale and localePath keep one address: make them the same language, or set prefixDefaultLocale: true ``` ## A key is showing on screen instead of the text A message that resolves nowhere renders as its own key. Usually the catalog for that language has not arrived yet, or the group is one you excluded from the browser with `bundle.exclude` and something asks for it at runtime. The build warns about the second case by name. If it only happens in your source language, the key is probably in a translation and not in your source catalog: `npx verbaly check` lists it as a key only a translation has. ## My edit in the source catalog disappeared That text is written in your code, with `` t`…` `` or `t.id`, so the code owns it: the dev server, `extract` and the build all put the code's text back. The message says which file holds it, and that is where to change it. If you want to edit a text in the catalog, keep only its key in the code, as `t('key')`. Run from the terminal, `extract` prints one line for each text it put back, with the text it had, so you can see exactly what it undid. ``` [verbaly] es.json: your edit of "footer.copyright" was replaced, its text lives in src/components/Footer.tsx:12: change it there ``` ## A translation shows as outdated Its source text changed after it was written, and nobody has touched it since. It can also show up right after an `import`: a translator's file carries the source text it was made from, so a file made for an older version is outdated as soon as it lands. Update the translation and the warning goes away on its own. If it still says the right thing, keep it with `npx verbaly review --approve`. It never fails a build unless your CI runs `check --outdated`. ## verbaly.lock has a merge conflict `verbaly.lock` records which translations are machine drafts and which source text each one was written for. When two branches translated in parallel, a merge can leave it with a conflict, and there is no side to pick: Verbaly reads both and keeps every draft either one had. The next `extract` writes the file whole and says so. Add it to the commit that resolves the merge. ``` verbaly.lock had a merge conflict and now holds both sides, drafts and stamps included: add it to the commit that resolves the merge ``` If the file still cannot be read (a conflict edited halfway, for example), commands that only read it warn and go on, and the ones that would write drafts stop before writing anything. Fix it by hand and keep the entries of both sides: deleting it, or keeping only one side, would approve drafts nobody has read. ## A text stays in my source language The compiler only reads calls named `t`, so a translation function under another name, like `const tr = useT()`, never has its text extracted. `extract` and `doctor` name each one with its file and line, in `.vue`, `.svelte` and `.astro` files too: rename it to `t`. If the file is outside your `include`, nothing in it is read either, and your build and dev server name it when they start, with the pattern to add: ``` [verbaly] components/save-button.tsx uses t`…` outside the include of your verbaly config, so its texts are never extracted and show in en in every language: add "components/**/*.{js,jsx,ts,tsx,mjs,mts,cjs,cts,svelte,vue,astro}" to include (or the file to exclude, if it is not app code) ``` ## The page switched language right after it loaded The page arrived in one language and the instance in the browser started in another, so `bindDom` translated the page into its own. It warns once, naming both. When the address carries the language, create the instance with the language `localeFromPath` reads from it; when it does not, call `persistLocale` first, so the page and the browser start from the same choice. ``` [verbaly] the page is and this instance is in "en": read the url with localeFromPath, or call persistLocale first ``` ## A message shows its ICU source instead of its text ICU syntax needs its parser, and the compiler only ships it when one of your catalogs uses that syntax at build time. A message that arrives later, from a CMS or through `addMessages`, finds no parser, so it shows its own source and warns once. Set `icu: true` in your verbaly config to always ship the parser, or pass `icu: parseIcu` to `createVerbaly` if you create the instance yourself. ``` [verbaly] a message uses ICU syntax and no ICU parser is loaded: set icu: true in your verbaly config, or pass icu to createVerbaly ``` ## My keys are not typed, or the types are stale The types are written by `extract`, the dev servers and every build, and `svelte-check` and Vitest write the same ones, so a fresh clone has none until one of them runs. A script that checks types before it builds (`tsc -b && vite build`, as the React template does) runs before all of them: `npx verbaly typegen` writes them alone, and it is the fix for `Cannot find module 'verbaly/app'`. They go where your framework already reads them, and a `Cannot redeclare` means an older `verbaly.d.ts` left at the root, which the next run removes. A typo in a key fails with the key in the error. ## Prune left keys you no longer use While any source file does not parse, `extract --prune` removes nothing and names the file. A file it cannot read may be the one that uses those keys, and pruning then would delete their translations. Fix the syntax error and run it again. ## t cannot be imported from verbaly No package exports `t`. It comes from your project's own module, `verbaly/app`, or from your framework's hook. `doctor` reports this one as an error because no bundler can resolve it. ## An alias of verbaly breaks verbaly/app In Vite an alias runs before every plugin, and a plain string key also matches its subpaths, so `{ verbaly: './path' }` catches `verbaly/app` too. Write the alias exact: `{ find: /^verbaly$/, replacement: './path' }`. ## ESLint says verbaly/app is unresolved `verbaly/app` is written by the plugin, so the `import/no-unresolved` rule of ESLint cannot find it on disk. Allow it the way a Vite project allows its virtual modules: `ignore: ['^verbaly/app$']`. > **Still stuck** > > `npx verbaly doctor` prints everything it can see about your setup, and pasting that output into an [issue](https://github.com/verbaly-i18n/verbaly/issues) is the fastest way to be understood. --- # Runtime API Source: https://verbaly.dev/docs/reference/api The `verbaly` core is ~3 KB gzipped with zero dependencies, and everything builds on native `Intl`. ## createVerbaly(options) ``` import { createVerbaly } from 'verbaly'; const v = createVerbaly({ locale: 'es', fallback: ['en'], messages: { es: { home: { title: 'Inicio' } } }, }); ``` | Option | Type | Description | | --- | --- | --- | | locale | string | Initial language; defaults to `navigator.language` in the browser | | fallback | string \| string[] | Fallback chain, after the closest match (`es-MX` → `es`) | | messages | object | Language → tree; nested keys flatten to dots (`home.title`). An empty string counts as untranslated and keeps falling back, the same rule as `check` | | loaders | object | Lazy catalogs: language → `() => import('./es.json')`, loaded on demand. The one for your starting `locale` is fetched right away, and the UI updates when it lands | | formatters | object | Custom `{v:name}` formatters | | icu | function | The ICU parser, for messages that arrive after the build: pass `parseIcu` from `verbaly`. With the plugin, `icu: true` in your config does this | | partial | string[] | Languages whose messages came with the page: nothing is fetched for them, and a message the page never showed loads the rest once instead of falling back in silence | | onMissing | function | `(key, locale)`: return a string to substitute; silences the default warn-once | | onResolve | function | `(info)` on every `t()`: `key`, `locale`, `value` and `status` (hit / fallback / miss). Powers devtools | ## Instance | Member | Description | | --- | --- | | t(key, params?) | Translate. Keys and params are type-checked from your messages. Bad data never crashes a render, and never slips through unnoticed: a missing param, a plural block with no catch-all case, a placeholder with no argument, a value that is not text, a language code the browser cannot read. Each one warns once in the console, naming the message, the path or the code it came from | | t`...` | Tagged template: interpolates source text; the compiler upgrades it | | t.id(key)`...` | Readable-key opt-in: formats the inline source; the compiler rewrites it to a keyed call | | setLocale(locale) | Switch language, notify subscribers, auto-loads a pending lazy catalog. It returns at once: `setLocale` from `verbaly/app` is the one that waits for the catalog | | loadLocale(locale) | Load a lazy catalog, once, with the closest match: `await` it before `setLocale` for a flash-free switch | | addMessages(locale, tree, options?) | Merge messages at runtime: what lazy loading is built on. Pass `{ partial: true }` when the messages are one page's worth, so the language stays incomplete and the next missing message still fetches the rest | | subscribe(fn) | Change listener; returns unsubscribe | | has(key) | Key exists in the current chain | | inspect(key) | Origin language (`from`) + source text for a key (devtools/tooling) | | locale | Current language (readonly) | | locales | Loaded + loadable languages (readonly): feed a language switcher from one source of truth | | version | Change counter that powers framework adapters | ## Language helpers ``` import { alternateLinks, inlineMessages, localeDirection, localeFromPath, localeName, localePath, negotiateLocale, persistLocale, resolveLocale, resolveRequestLocale, stripLocalePath, switchLocale } from 'verbaly'; // which language is this page? a fact of the url, undefined when it carries no prefix localeFromPath({ supported: ['en', 'es', 'pt'] }) ?? 'en'; // which language does this visitor want? url prefix → storage → navigator → fallback resolveLocale({ supported: ['en', 'es', 'pt'] }); persistLocale('es'); // localStorage + + // server-side: match an Accept-Language header negotiateLocale('es-PE,en;q=0.8', ['en', 'es']); // → 'es' // per-request: url (when it carries the language) → cookie → header → fallback resolveRequestLocale({ supported: ['en', 'es'], path, routing, cookie, header }); // client switch for SSR setups: catalog → locale → cookie + + await switchLocale(instance, 'es'); // language switchers: names and direction from Intl, no tables localeName('es'); // → 'español' localeName('de', 'en'); // → 'German' localeDirection('ar'); // → 'rtl' // pre-rendered sites: the same page in another language, for a switcher that navigates localePath('pt', { supported: ['en', 'es', 'pt'], sourceLocale: 'en' }); // /es/docs?q=1#faq → /pt/docs?q=1#faq // the route behind a localized url, for a router that keeps one tree stripLocalePath({ supported: ['en', 'es'], path: '/es/docs' }); // → '/docs' // this page's address in every language, for the head of a server-rendered page alternateLinks({ supported, sourceLocale: 'en', path: '/docs', baseUrl }); // the messages `verbaly render` wrote into this page, when you asked it to inlineMessages(); // → { 'home.title': 'El gate del build' } or undefined ``` `localeFromPath` and `resolveLocale` answer two different questions, and picking the wrong one is the classic bug. `localeFromPath(options)` asks **which language this page is in**. It reads the `/{locale}/` prefix and returns `undefined` when the url carries none, so on a site with a tree per language you write `localeFromPath(...) ?? sourceLocale` and nothing can contradict the url. `resolveLocale(options)` asks **which language this visitor wants**: the url prefix first, then the stored choice, then `navigator.languages` with its closest match, then your `fallback` (`path: false` switches the url off). Use it to decide where to send someone, never to decide what a page already says. `persistLocale` remembers a switch. All of them are safe on a server. The first two take a `base` for a site served from a subfolder, and the storage ones accept a custom `storageKey` (`false` turns storage off). See [Plain HTML → Picking the language at startup](https://verbaly.dev/docs/frameworks/dom.md#locale-bootstrap) for the full pattern. `negotiateLocale(header, supported, fallback?)` is the server-side counterpart: give it an `Accept-Language` header and your languages and it returns the best match. It respects quality values and ignores case. Each language finds the closest one you support: `es-PE` matches `es`, `zh-HK` matches `zh-Hant`, and `pt` or `pt-PT` matches `pt-BR`, but never one in another script (`zh-HK` never gets `zh-Hans`). It works with any server; the SvelteKit, Nuxt and Next.js integrations use it under the hood. `resolveRequestLocale(options)` makes the whole per-request decision in one call. Give it the `path` and your `routing`, and the address decides: a prefixed page is that language for everyone, and a page with no prefix is your source language, so a saved choice can never translate it by accident. Leave `routing` out and the order is the stored cookie first, then the `Accept-Language` header, then your `fallback`. `LOCALE_STORAGE_KEY` exports the shared name (`verbaly-locale`) that the browser storage and the server's cookie both use. `inlineMessages(root?)` reads the messages `verbaly render` wrote into the page when `render.inlineCatalog` is on, so a pre-translated page needs no catalog over the network. You rarely call it: the generated module already does, and passes the result as `partial` so a message the page never showed still loads on demand instead of falling back in silence. `stripLocalePath(options)` is the inverse of `localePath`: it gives the route behind a localized address, so a router can match one tree instead of one per language. `alternateLinks(options)` returns this page's address in every language plus an `x-default`, ready for `link rel="alternate"` tags in a server-rendered head. It is the same set `verbaly render` writes into a static site, and it is empty when your addresses carry no language, because one address cannot honestly claim to be every language at once. `localePath`, `alternateLinks` and `switchLocale` also take `trailingSlash` (`'always'`, `'never'` or `'ignore'`), so every address they build ends the way your site's do. You rarely pass it: `verbaly/app` binds the one Astro or Next is set to, and without one each address keeps the form it had. `switchLocale(instance, locale, options?)` is the client-side switch the server integrations share: it loads the catalog first, then switches the language, writes the `verbaly-locale` cookie and updates the `lang` and `dir` attributes. Safe to call on the server (it does nothing there); `@verbaly/sveltekit` re-exports it. `localeName(locale, displayIn?)` and `localeDirection(locale)` feed a language switcher without hardcoded tables: real language names via `Intl.DisplayNames` (the name in its own language by default) and the writing direction of any language. Right-to-left languages need no extra work: `switchLocale`, `persistLocale`, the server integrations and `verbaly render` already keep `dir` right on their own. ## Type-level safety ```title="editor" v.t('home.title'); ✓ v.t('home.title', { x: 1 }); ✗ no params declared v.t('nope'); ✗ unknown key ``` TypeScript parses your messages: `FlatKeys` flattens nested trees, `ParamNames` reads `{param}` occurrences, and `TArgs` makes params required exactly when the message declares them. With the compiler, the generated types fill in `Register`, so `Translate` is your project's `t` and `Locale` the union of your languages: every `t` an adapter hands out (`useT()`, `getT()`) and every instance of the generated module checks keys and params against your catalog. An instance you build from a dictionary keeps that dictionary's types. All three are types only, so they cost nothing at runtime. > **Dynamic content** > > Runtime keys work too: `addMessages` + `t(dynamicKey)` cover CMS-driven content that compiler-only tools can't handle. A key held in a string compiles as it is; only a key you write by hand is checked against your messages. ## Low-level exports Building tooling on top of Verbaly? The package exports the same pieces the compiler uses. `parse(message)` gives you the message AST, and `parseTags(text)` with `RICH_TAGS` is the rich-text tokenizer and its list of allowed tags, which is what a custom renderer needs. `flatten(tree)` turns a nested tree into dot-keys. `safeHref(href)` and `safeAttribute(name, value)` are the URL and attribute guards, and `normalizeLink(link)` is the one link normalizer every adapter shares, along with the `RichLink` type. --- # Configuration Source: https://verbaly.dev/docs/reference/config One file at the root of your project, read by your build and by the command line, so a setting means the same thing to both. Flags win over the file. ```js title="verbaly.config.mjs" export default { sourceLocale: 'es', locales: ['es', 'en', 'pt'], }; ``` Accepted names are `verbaly.config.js`, `.mjs`, `.ts`, `.mts` and `.json`, read in that order. A TypeScript config needs nothing else installed, and its imports can leave out the extension, as in `./src/i18n`. ## Every option | Option | Default | What it does | | --- | --- | --- | | `sourceLocale` | `'en'` | The language you write in | | `locales` | The catalog files it finds | Your languages. List them and the list is complete; leave it out and every JSON file in `dir` counts as one | | `dir` | `'locales'` | Where the catalogs live | | `root` | Where you ran the command | The project root every other path is resolved against | | `include` | `src/**`, `app/**` | Which files are scanned for messages and compiled. A file outside it that writes `` t`…` `` is named, with the pattern to add, when your build or dev server starts. `[]` turns scanning off, for a project whose catalogs are written by hand | | `exclude` | `node_modules`, `dist` | Which files are skipped inside that | | `routing` | Follows your setup | Where the language lives in your addresses. See [URL strategy](https://verbaly.dev/docs/guide/urls.md) | | `trailingSlash` | Your framework's, if it has one | How your addresses end: `'always'`, `'never'` or `'ignore'`. Astro and Next.js hand over their own, so you rarely write it | | `dts` | Where your framework reads them | Where the generated types are written, or `false` to write none. Left out, they go to `src/verbaly.d.ts` (the root without a `src/`), to `.verbaly/types.d.ts` in Next.js, which Verbaly adds to your `tsconfig.json`, and to the types folder Astro and Nuxt keep for this | | `bundle` | Nothing excluded | `exclude`: groups of messages that stay in the build and never reach the browser | | `render` | Off | The pre-translated mirror for static sites. Its own options are below | | `translate` | Claude | Everything machine translation needs beyond the provider: model, batch size, glossary, instructions | | `icu` | Your catalogs decide | Forces the ICU parser to ship. Only for messages that reach your app after the build | | `relative` | Your catalogs decide | The same, for relative time formatting | > **Two you almost never write** > > `icu` and `relative` travel only when one of your messages needs them, and Verbaly works that out by reading your catalogs. You set them when a message can arrive later, from a CMS or a fetched catalog, because then there is nothing to read at build time. ## Inside render Only for static sites that publish one address tree per language. Adding this section is what switches the mirror on. | Option | What it does | | --- | --- | | `baseUrl` | Your public address. Alternates and the sitemap need it | | `site` | The built directory to mirror. Defaults to `dist` | | `sitemap` | Writes a per-language sitemap. A string names the file | | `exclude` | Pages to leave out of that sitemap, by path inside the build directory | | `hreflang` | Reciprocal alternates on every page. On by default | | `redirect` | Sends a first-time visitor to their language before the page paints | | `links` | The real addresses behind named links inside your messages | | `base` | The path prefix, if your site is not served from the root | | `attribute` | The attribute to look for, if you renamed `data-verbaly` | | `inlineCatalog` | Writes into each page the messages it renders, so a translated page downloads no catalog of its own | | `clean` | Drops language pages left over from an earlier build | ## Inside translate Everything machine translation needs beyond the provider, so a run behaves the same for everyone on the project instead of depending on who typed the command. | Option | What it does | | --- | --- | | `provider` | Who does the translating. `'claude'` is the one that ships; give it a function instead and it is yours, with no lock-in | | `model` | Which model the built-in provider uses. `--model` overrides it for one run | | `batchSize` | How many messages go in one request, 20 by default. Lower it if long messages get cut off, raise it for short ones | | `concurrency` | How many requests are in flight at once, 4 by default. Lower it if your provider rate limits you | | `retries` | How many times a request that fails for a passing reason is tried again, 2 by default | | `instructions` | Anything you would tell a human translator about your product: how formal to be, how short a button label has to stay, what your app is | | `glossary` | How a term has to come out. Give one wording for every language, which is how you say leave this alone, or one per language. Only the terms a batch actually contains are sent | A run survives a bad connection. Requests that fail for a passing reason are tried again, and if one still does not come back, everything else is written and the report names the messages it could not fill. Running `translate` again asks only for those, so a dropped connection never costs you the whole run twice. The command exits `1` when that happens, so a script notices. ## Only in the plugin `failOnMissing: true` stops a build on whatever fails `verbaly check`, for a project that deploys without CI. Without it, a build lists missing, broken and unknown keys and finishes: a missing translation falls back to your source language, and `check` in CI is the gate. `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. Every other option belongs in the file. The plugin accepts them too and wins over the file, but `verbaly check` and `verbaly extract` never read what you pass there, so the build warns. --- # CLI Source: https://verbaly.dev/docs/reference/cli The `verbaly` command lives in `@verbaly/compiler`. Add it to your dev dependencies so `npx verbaly` resolves: package managers link a command only for a package you installed yourself, and the plugins depend on the compiler without installing it for you. ## Commands 14 commands, in the order the cycle uses them. Each one links to its section. **1. Set up** - [`init`](#init): Scaffolds the config and your catalogs, and names the plugin to wire. - [`doctor`](#doctor): Checks the whole setup and prints the fix for each finding. - [`wrap`](#wrap): Finds hardcoded text in your JSX and wraps it for you. - [`migrate`](#migrate): Ports catalogs from another i18n library, and flags what it will not guess. **2. Write** - [`extract`](#extract): Syncs your catalogs and types with your source. - [`typegen`](#typegen): Writes the TypeScript types alone, for CI before tsc. - [`status`](#status): Coverage per language at a glance. It never fails. - [`pseudo`](#pseudo): A fake language that exposes hardcoded text and clipped layouts. **3. Translate** - [`translate`](#translate): Fills missing translations with a provider, marked as drafts. - [`review`](#review): Lists drafts and outdated translations, each with its source text, for a person to approve. - [`export`](#translators): Files for translators: XLIFF, CSV, PO, Android or iOS. - [`import`](#translators): Brings translated files back, validated before they land. **4. Ship** - [`check`](#gate): The CI gate: fails on missing keys, unknown keys and broken translations. - [`render`](#render): Writes your static site in every language. ## Scaffolding `verbaly init` sets a project up in one command. You get a typed config (`.ts` if you have a `tsconfig`, `.mjs` otherwise) and your catalogs: the source one, plus one for every language you pass in `--locales`. Then it tells you what to wire next. Astro, Nuxt, Next.js, SvelteKit and Vite each have their own integration; any other bundler uses `@verbaly/unplugin`. On Vite and every other bundler, the install line also names the package for the UI library you use: `@verbaly/react`, `@verbaly/vue` or `@verbaly/svelte`. ```console $ npx verbaly init --locales es,pt created: verbaly.config.ts, locales/en.json, locales/es.json, locales/pt.json detected: vite next steps: 1. pnpm add verbaly @verbaly/react @verbaly/vite 2. add verbaly() to the plugins in vite.config ``` Re-running is safe: an existing config or catalog is reported as “kept” and left byte-identical. ## Health check `verbaly doctor` is `init`'s sibling for projects already running: it inspects the whole setup and reports every finding with the exact command that fixes it. Green means healthy; problems exit `1`. ```console $ npx verbaly doctor Passed config: verbaly.config.ts found Passed catalogs: 3 locales (en, es, pt) in locales/ Passed plugin: @verbaly/vite installed for vite Warning types: src/verbaly.d.ts is stale fix: run npx verbaly typegen Warning orphans: 2 catalog keys are no longer referenced (old.title, hero.cta) fix: run npx verbaly extract --prune to drop them Warning outdated: 1 translation written for an older source text (es: hero.title) fix: update them, or keep them with npx verbaly review --approve Error imports: 1 file imports t from a verbaly package, which never exports it (src/app.ts) fix: t comes from your instance (React: const t = useT()) or from verbaly/app Error translations: 1 broken translation (es): present but not rendering what the source renders fix: run npx verbaly check to read what each one lost ``` One command to answer “why isn’t this translating?” It looks at four things. - **Your setup:** the config, the catalogs and whether every language code is one a browser can read. Also whether the URL mode matches the URLs `render` writes, whether the right integration for your framework is installed, and whether the generated types are up to date where your framework reads them, `tsconfig.json` included in Next.js. - **Your translations:** the missing ones, the broken ones, the outdated ones, the warnings, keys only a translation has, keys written with two texts, and keys no line of your code asks for any more. - **What your build cannot see:** `t` imported from a verbaly package, which no bundler can resolve, and a `t` under another name, whose text is never extracted. Also a file outside `include` that writes `` t`…` ``, which no build translates, and a message that kept a plural or format block as plain text, with the spelling that works. - **Any file it could not read**, as a warning. A source file's text is not extracted, but the file may still build fine in your project. A merge conflict in `verbaly.lock` is a warning too: both sides are read, and `extract` writes them into the file for you to commit with the merge. A clean report means `check` passes too. `doctor` fails on everything `check` fails on, plus setup faults like that import, and never on something that builds and renders fine. ## Wrapping hardcoded text `verbaly wrap` finds hardcoded text in your JSX and wraps it in `` t`…` `` for you. It reports first, and `--write` applies. Anything ambiguous is listed for a human instead of guessed, and a file where `t` is not available is left untouched and reported, so the project always still compiles. ```sh npx verbaly wrap # report what it would wrap npx verbaly wrap --write # apply it ``` ## Porting from another library `verbaly migrate` ports the catalogs you already have. Your file keeps its shape, nested or flat, and the only thing it must rewrite is the interpolation: `{{name}}` becomes `{name}`, because a doubled brace is how Verbaly writes a literal one. It reports first, and `--write` applies. ```sh npx verbaly migrate # report what it would port npx verbaly migrate --write # apply it npx verbaly migrate --plurals --write # and merge _one/_other ``` `--plurals` is the optional half: it merges `_one` and `_other` into one message with variants, which is what buys automatic plural selection, and inside it the count prints itself already localized. It knows the older `key` + `key_plural` spelling too. Without the flag those keys keep working exactly as they are. What it will not guess is listed instead: an i18next format inside the braces, a `{{- unescaped}}` value, a `$t()` nesting, and a merge that would overwrite a key you already use. Those messages are left exactly as they were, and every run lists the ones still waiting. ## Extraction `verbaly extract` scans your sources (every JavaScript and TypeScript file, `.jsx`, `.tsx`, `.mjs`, `.cjs`, `.mts` and `.cts` included, plus `.svelte`, `.vue` and `.astro`), writes new messages to the source catalog, adds `""` placeholders to the rest and regenerates the types. It names any file it could not parse instead of stopping on it. Every source text that followed your code gets one line with the text it had before, so an edit you made in the code reads as a change and one made in the catalog shows what it undid. Then it warns, with file and line, about what would otherwise go unnoticed: a key written with two texts, a `t` under another name, a message that kept a plural or format block as literal text, and a value a translator would see as `{_0}`. With `--watch`, each warning is said once, and again only if it comes back. ```sh npx verbaly extract # sync catalogs + types npx verbaly extract --prune # and drop keys nothing references npx verbaly extract --dry-run # say what it would change, write nothing ``` ## Type generation `verbaly typegen` writes the TypeScript types of your messages and nothing else, from the text your build ships, where your framework reads them: `src/verbaly.d.ts` in a Vite or SvelteKit app, `.verbaly/types.d.ts` in Next.js, and Astro's and Nuxt's own types folder. `extract`, the dev servers and the build write the same file, so you only need it where none of them ran: a fresh clone, or a CI job about to run `tsc`. ```sh npx verbaly typegen && tsc --noEmit # a fresh clone, or CI ``` ## Coverage `verbaly status` shows translation coverage per language at a glance (`es: 45/48 translated`), how many machine translations still wait for review, how many are broken and how many were written for an older source text. It is informational only and never fails; `--json` gives the same numbers to badges and tooling. ```sh npx verbaly status # es: 45/48 translated npx verbaly status --json # the same numbers, for badges and tooling ``` ## Pseudo-localization `verbaly pseudo` fills a QA catalog (`en-XA` by default) from the text your build ships in the source language: accented letters, `⟦…⟧` markers and ~33% padding. Text that stays clean in the pseudo build is hardcoded; layouts that clip reveal themselves before a real translation does. ```sh npx verbaly pseudo # locales/en-XA.json # "Hello {name}" → "⟦Ĥéĺĺó {name} ~⟧" ``` Params, variant blocks and named tags survive verbatim, guaranteed by the same structural validation as `translate`. Re-running regenerates the whole catalog. ## Machine translation `verbaly translate` closes the loop: write → `extract` → `translate` → `check` green. The default provider uses Claude (`@anthropic-ai/sdk` as an optional peer + `ANTHROPIC_API_KEY`). It sends batches of 20 per request, and each one tells the model which source files the text lives in, so it translates with context. Any current Claude model works through `translate.model` or `--model`, and a batch the model declines goes to a fallback model instead of coming back untranslated. ```sh npx verbaly translate --dry-run # list what's missing, write nothing npx verbaly translate --locales es,pt # fill only these locales npx verbaly translate --model claude-opus-4-8 # override the default (claude-sonnet-5-5) ``` Every translation is checked: placeholders and tags must survive verbatim. If one doesn't, the translation is rejected and the entry stays `""`, so `check` keeps flagging it until it's fixed. No lock-in: plug your own provider in `verbaly.config.ts`. In TypeScript, `TranslateProvider` types it for you, and `origins` tells you which source files each text appears in, so you can translate it for where it is used: ```ts title="verbaly.config.ts" import type { TranslateProvider } from '@verbaly/compiler'; const provider: TranslateProvider = async ({ sourceLocale, targetLocale, messages, origins }) => ({ /* key → translation */ }); export default { translate: { provider } }; ``` ## Review what is waiting Machine output is a draft, not reviewed work. `translate` records everything it writes in `verbaly.lock`, next to your config (committed with your catalogs, never edited by hand), and `verbaly review` closes the loop: read the drafts, then approve them. The same file remembers which source text each translation was written for, from the moment it is written, so when you change a text, its translations wait in `review` too, as outdated: update them, or approve them if they still hold. Each one is listed with the text that ships next to its translation, so you can judge it right there, and `--approve` followed by keys accepts only those. ```sh npx verbaly review # each one with its source text and its translation npx verbaly review hero.title --approve # accept only the keys you name npx verbaly review --approve # accept everything after reading npx verbaly check --drafts # CI gate: fail while drafts remain npx verbaly check --outdated # and while a translation is older than its text ``` Want merges blocked until a human signs off? Add `--drafts` to the `check` in your CI: it keeps failing while unreviewed machine translations remain, and `--outdated` does the same for translations written for an older source text. A translator file brought in with `import` counts as review on its own. ## Translators & TMS Humans in the loop? `verbaly export` writes translator-ready XLIFF 2.0, CSV or gettext PO files per language and `verbaly import` brings them back, structure-validated with the same gate as `translate`. The full flow, TMS options included, lives in [Work with translators](https://verbaly.dev/docs/guide/translators.md). `verbaly import` validates every entry and rejects and reports the broken ones. PO entries marked fuzzy count as untranslated, and imported keys stop counting as unreviewed drafts, unless you pass `--draft` for a file nobody has read yet. A file's language is read as one of yours, so gettext's `pt_BR` fills your `pt-BR`. A file for a new language starts its catalog under its proper code, unless your config lists its `locales`: then a language outside the list is skipped with a warning and exit code `1`, because your app would never load it. Export also writes native mobile resources: `--format android-xml` for Android's `res/` layout and `--format ios-strings` for Xcode. Untranslated keys are left out so the app falls back to your source language (`--missing` applies only to the translator formats). Every format writes to `verbaly-export/` unless you point `--out` elsewhere. ## What the gate checks `check` asks four questions. Is every message translated? Does every key the code writes exist? Does each key have one text, so no place shows words written for another? And can each translation render what the source renders? A filled-in translation is not automatically a working one, so these fail `check` too, wherever they came from: a translator, a machine or a hand edit. Every build lists the same problems and finishes, so run `check` in CI. | The translation | Why it fails | | --- | --- | | lost a `{param}`, or renamed it | the value never reaches the text | | lost an ``, or gained one | the emphasis or the link marker is gone | | turned a plural block into plain text | one wording for every count | | has a plural block with no `other` case | every count it does not list renders *empty* | Some findings are warnings instead: they print and the exit code stays `0`, because the text still renders. - A plural set missing forms the language needs: Polish and Arabic ask for more than English. - A case like `=0` that the source had and the translation dropped, so that count falls back to `other`. - A key only a translation has. Where your code reads it, the source language shows the key itself; where nothing does, it only adds weight, which `extract --prune` removes. - A text in your source catalog that differs from the one in your code: the code's text is the one that ships. - A translation written for an older source text, read against the text in your code. Add `--outdated` to `check` to make it fail, and it is listed with the failures. A build runs the same gate, and when it finds warnings it prints one line that says how many, then passes. Whatever fails, the report ends by telling you how to fix it: fill a message that has no translation yet, correct a key no catalog has, give each text its own key where one key has two, or repair a broken message. ## CI example ```yaml title=".github/workflows/ci.yml" - run: pnpm install - run: npx verbaly check --reporter github # each finding becomes a PR annotation - run: pnpm build ``` With `--reporter github`, every finding shows up as an annotation on the pull request, on the file and line where the text lives. Errors arrive as errors and warnings as warnings, so a warning never turns the job red. Without it you get the plain list, with the same exit code. ## Static rendering (SSG) `verbaly render` is what removes the flash of untranslated text on a static site. It walks your built HTML and fills in every `data-verbaly` element, once *per language*, using the real runtime: plurals, `Intl` formatting, `data-verbaly-args`, attributes and allowed rich text. Inside a language, links to pages that language also has keep its prefix, so whoever arrives stays there. Getting them there is `--redirect`, below. ```sh npx vite build # or astro build, eleventy, … npx verbaly render # dist/index.html filled in the source locale # dist/es/index.html, dist/pt/… for the rest npx verbaly render --site out --locales es # custom dir / locale filter ``` - Each language gets `` and `` set (right-to-left languages mirror correctly); the source language is filled in place, the rest mirror to `dist//…`. A folder named like the source language, such as `dist/en/` when you write in English, is never mirrored, and the run says so. - The `data-verbaly` attributes stay in the output, so client-side language switching keeps working on top of the pre-rendered page. - Messages are HTML-escaped (never injected), missing keys are reported and left untouched, running it again changes nothing, and translated attributes pass the same guards as the runtime: unsafe URLs blocked, `style`/`srcdoc` never written. - Named links: set `render.links` in `verbaly.config.*` (or `data-verbaly-links` per element) and rich messages pre-render real `` elements, attribute-escaped, with `javascript:` blocked. - Multi-language SEO: set `render.baseUrl` (or pass `--base-url`) and every page gets reciprocal `hreflang` alternates; `--sitemap` writes an i18n sitemap, `--clean` drops stale language pages. - The sitemap lists only pages a search engine should index: one that redirects, or carries `noindex`, is left out. Every page is still translated and published, so a visitor who lands on one gets it in their language. Leave more out by name with `render.exclude`, a list of globs against the path inside your build directory. - Using a different data attribute? `--attribute` points the renderer at it, the same way the runtime takes one, so both sides stay in step. - Self-canonical mirrors: `rel="canonical"` and `og:url` are rewritten to each language's own URL, because a cross-language canonical would make search engines ignore the hreflang set. - Send a visitor to their language. `--redirect` (or `render.redirect`) puts a small script at the top of your home page that moves them before anything is drawn. It only fires there: a search engine asking for a deep page has to get that page, not a detour. A saved choice always wins, the query and the hash come along, and it can never loop, because it does nothing once you are already in that language. Add `{ on: 'all' }` if you want every page of your source language to route too, and `storageKey` to point it at the key you save the choice under. - Site served from a subfolder? `--base /app` (or `render.base`) tells the renderer where the site starts, so links inside each language read `/app/es/docs` instead of pointing nowhere. The same option exists on `localeFromPath` and `localePath` so the runtime agrees with the build. ## Flags | Flag | Default | Description | | --- | --- | --- | | --root | cwd | Project root | | --dir | locales | Catalogs directory | | --source | en | Source language | | --locales | from files | Run on these languages only, the source always included. One the project does not have is an error (init: the ones to create) | | --prune | off | Drop keys no longer referenced (extract only) | | --watch | off | Re-extracts as source files change: live extraction for webpack, Rspack and Rollup setups (extract only) | | --locale | en-XA | Pseudo-language id (pseudo only) | | --site | dist | Built site directory (render only) | | --base | site root | Subpath the site is served under (render only) | | --redirect | off | Send a visitor on the home page to their language (render only) | > **Prune and dynamic keys** > > `--prune` only sees statically analyzable usage. If you build keys at runtime (`t(someVar)`), keep prune off or those keys will be removed. `extract --prune --dry-run` previews the removals without writing anything. While any source file does not parse, prune removes nothing and names the file, because that file may be the one reading the keys. Flags are validated per command: a flag that belongs to another command exits with an actionable error instead of being silently ignored: `translate --locale es` tells you it means `--locales`. A language is checked the same way: `review --locale ess` exits with an error that lists the languages your project has and says how to start a new one. ## Config file Flags win over `verbaly.config.{js,mjs,ts,mts,json}` at the project root. Every option, with its default, lives in [Configuration](https://verbaly.dev/docs/reference/config.md). ## Coding agents Your coding agent can run this same cycle without touching the shell, through the `@verbaly/mcp` server. That channel has a page of its own. [Coding agents](https://verbaly.dev/docs/guide/agents.md) covers the server, its tools and resources, the installable Agent Skill and the `llms.txt` index this site serves. --- # Devtools Source: https://verbaly.dev/docs/reference/devtools When something shows the wrong text, you want one answer: *what key is this, and where did it come from?* The `verbaly/devtools` overlay answers it in the browser. ## Attach the inspector Import it only in development: it's a separate file, and production builds leave it out. ```ts title="main.ts" if (import.meta.env.DEV) { const { attachDevtools } = await import('verbaly/devtools'); attachDevtools(verbaly); } ``` - A panel shows how many keys are **ok**, falling back, or missing, and names the catalog file to fix each missing one. - Hold `Alt` and hover any element to see its key, the language it resolved from, and the source text. The panel prints the key it is listening for, so you never have to guess it. ## What you can change The defaults suit a normal app, and every one of them takes an argument when yours is not. | Option | Default | What it does | | --- | --- | --- | | `hotkey` | `'alt'` | The key you hold to inspect: `'alt'`, `'ctrl'`, `'shift'` or `'meta'`. Change it when Alt already belongs to something on your page | | `root` | `document.body` | The part of the page it looks at, for an app mounted inside a bigger one | | `attribute` | `'data-verbaly'` | The attribute it reads, if you renamed the one your markup uses | | `catalogDir` | `'locales'` | The folder it names when it tells you where to add a missing message | ## The onResolve hook Prefer your own logging? `onResolve` fires on every `t()` call with the key, language, value and whether it was a hit, a fallback or a miss. ```ts title="i18n.ts" createVerbaly({ onResolve: (info) => { if (info.status === 'miss') console.warn('missing', info.key); }, }); ``` For a one-off lookup, `verbaly.inspect(key)` returns the resolved language and source text.