Verbaly

[Verbaly]

Write your text in the code. Ship it in every language.

An i18n compiler and a tiny runtime for React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro and plain HTML.
No key files to keep in sync, params typed from the text, and a CI gate that stops broken translations.

[npm version] [CI] [coverage] [Socket supply chain security] [OpenSSF Scorecard] [published with npm provenance] [3.35KB gzip runtime] [zero runtime dependencies] [TypeScript] [MIT]

[On the left, a component that writes t`Welcome back, ${name}`, t`You have ${count} new messages` and t`Open inbox`. On the right, the same page in a browser switching from English to Spanish to Portuguese. Below, the four steps: write, extract, translate, check.]

[React] [Next.js] [Vue] [Nuxt] [Svelte and SvelteKit] [Astro] [Vite] [webpack, Rollup, esbuild and Rspack] [Plain HTML, no framework]

The idea

Most i18n tools ask you to invent a key for every sentence, write it in a file per language and keep the files in step with the code by hand. Verbaly turns that around:

// with key files: name it, write it in en.json, es.json, pt.json, keep them in synct('dashboard.welcome_back', { name });
// with Verbaly: write the sentence where it is usedt`Welcome back, ${name}`;
// and the compiler writes a stable key and a typed call for yout('ESsQIvlA', { name });

The runtime that ships is 3.35 KB gzip with zero dependencies, measured on every release by a gate in this repo (pnpm --filter verbaly size).

Quick start

pnpm add verbaly @verbaly/vitepnpm add -D @verbaly/compiler   # the verbaly command: init, extract, checknpx verbaly init

// vite.config.tsimport verbaly from '@verbaly/vite';
export default { plugins: [verbaly()] };

// anywhere in your app: extracted and typed on saveimport { t, setLocale } from 'verbaly/app';
t`Hello ${name}`;await setLocale('es'); // loads only the Spanish module

verbaly/app is your project's own module: the plugin writes it from your config, with your languages and catalogs already in it. Next.js, Nuxt, SvelteKit and Astro have their own one-line setup: pick yours in the row above, or read the full docs at https://verbaly-web.vercel.app/docs.

Why Verbaly

Review translations in a panel

npx verbaly-studio

[Verbaly Studio: an overview that says five things are waiting, one translation that breaks the site, two missing messages and two machine translations nobody has read, with the languages and the last commits to the catalogs]

Studio serves your project over localhost: what is missing, what is broken, what a machine wrote and where each text lives in your code. Your JSON files are the database and git is the history, a save runs the same validations as verbaly check, and it never edits your source text.

How it compares

Sizes are min+gzip of each library's main entry with React external, measured with the same method on 2026-10-15.

Coding agents

claude mcp add verbaly -- npx -y @verbaly/mcp

The MCP server gives your agent the whole cycle as tools, with structured output and resources to read your config and catalogs. Machine translations stay drafts until a person approves them (verbaly review --approve, or Studio): approving is deliberately not a tool. The Agent Skill teaches the write, extract, check and translate cycle (npx degit AronSoto/verbaly/skills/verbaly .claude/skills/verbaly), and the docs publish llms.txt.

Packages

All of them share one version number, and every release is published from CI with npm provenance.

{  "i18n-ally.localesPaths": ["locales"],  "i18n-ally.keystyle": "flat",  "i18n-ally.sourceLanguage": "en",  "i18n-ally.displayLanguage": "en"}

languageIds:  - javascript  - typescript  - javascriptreact  - typescriptreact  - vue  - svelte  - astrousageMatchRegex:  - "[^\\w\\d]t\\(\\s*['\"`]({key})['\"`]"monopoly: true

Development

pnpm installpnpm build      # tsdown: ESM + CJS + .d.tspnpm test       # each package's suitepnpm typecheckpnpm --filter verbaly bench   # the hot path against i18next

Verbaly is 0.x: the API can still change between minor versions, and every change is in the changelog. Contributions are welcome: see CONTRIBUTING.md.

Feedback

• Something broke or surprised you: open a bug. A minimal snippet is enough.
• Something felt like friction: tell us what. The roadmap follows real use.
• It just works: a star or a mention helps others find it.

Sponsor

Verbaly is MIT-licensed, dependency-free and built independently. If it saves you time, sponsoring it funds the road to 1.0: more integrations, faster releases and long-term maintenance.

[Sponsor Verbaly on GitHub]

License

MIT © Aron Soto · @AronSoto