Skip to main content
Glama

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 sync
t('dashboard.welcome_back', { name });

// with Verbaly: write the sentence where it is used
t`Welcome back, ${name}`;

// and the compiler writes a stable key and a typed call for you
t('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).

Related MCP server: Weblate MCP Server

Quick start

pnpm add verbaly @verbaly/vite
pnpm add -D @verbaly/compiler   # the verbaly command: init, extract, check
npx verbaly init
// vite.config.ts
import verbaly from '@verbaly/vite';

export default { plugins: [verbaly()] };
// anywhere in your app: extracted and typed on save
import { 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.dev/docs.

Why Verbaly

Review translations in a panel

npx verbaly-studio

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

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

❌

❌

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

❌

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

Every cell about another tool is the best true thing its own documentation says, read on 2026-11-15 (i18next 27.1.2, Lingui 6.12.0, Paraglide 3.2.2). Sizes are min+gzip of what an app imports, with React external, measured the same day with the same method. The same table is on verbaly.dev.

Coding agents

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

In Claude Code, one plugin brings the server and the skill together:

claude plugin marketplace add verbaly-i18n/verbaly
claude plugin install verbaly@verbaly

Gemini CLI takes the same pair as an extension: gemini extensions install https://github.com/verbaly-i18n/verbaly.

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 skills add verbaly-i18n/verbaly, which copies it into the folder of each agent you use), and the docs publish llms.txt.

Packages

Package

What it is

verbaly

The runtime: t, Intl formats, locale helpers and the DOM interpreter

@verbaly/compiler

Extraction, typed codegen, the gate and the verbaly command

@verbaly/vite · @verbaly/unplugin

Bundler plugins: Vite, and webpack, Rollup, esbuild and Rspack

@verbaly/react · @verbaly/vue · @verbaly/svelte

Framework adapters: hooks or composables plus <Trans>

@verbaly/next · @verbaly/nuxt · @verbaly/sveltekit

Server rendering: the language per request, hydration with no flash

@verbaly/astro

Astro integration: .astro extraction and a static build per language

@verbaly/mcp

MCP server: the translation cycle as tools for an agent

@verbaly/studio

The local review panel above

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

Generated keys are hashes, so t('a1B2c3D4') in a diff tells you nothing. The i18n-ally extension shows the real text inline once you point it at your catalogs. Two files, no Verbaly config changes:

.vscode/settings.json

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

.vscode/i18n-ally-custom-framework.yml

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

keystyle has to match your catalogs: flat for dotted keys, nested for groups. Use the extension for reading, not writing: its extract and rename actions assume you own the keys, and here the compiler does.

Development

pnpm install
pnpm build      # tsdown: ESM + CJS + .d.ts
pnpm test       # each package's suite
pnpm typecheck
pnpm --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.

License

MIT © Aron Soto · @AronSoto

Available Tools

9 tools
verbaly_doctorDiagnose the setupA
Read-only

Diagnose a Verbaly project end to end (what verbaly doctor does). It checks the config file, the catalogs and their JSON, the bundler plugin for the detected framework, the generated types, files the parser could not read, a t imported from a package that never exports it, orphan keys, and every failure verbaly check would report, and it reports them all at once instead of stopping at the first. Run it first when something does not work. Read-only. For the missing or broken translations themselves, use verbaly_missing.

Inputs: root. Returns: ok, entries

verbaly_draftsMachine translations awaiting reviewA
Read-only

Every machine translation still waiting for a human, each with the source text and what the provider wrote, so a person can read both and decide. Read-only. Approving is deliberately not a tool here and never will be: a machine translation is unreviewed by definition, so accepting one is verbaly review --approve, run by a human. For how many drafts each locale has, verbaly_status is enough; verbaly_missing lists them next to the gate.

Inputs: root, locales. Returns: total, entries

verbaly_extractExtract messagesA
DestructiveIdempotent

Scan the source files, add new messages to the locale catalogs and refresh the generated types (what verbaly extract does). It writes the catalogs unless dryRun is set, and with the same code a second run changes nothing. prune also drops keys the code no longer references, translations included, and waits while any source file fails to parse. In a project without Verbaly, run verbaly_init first; for text still hardcoded in JSX, verbaly_wrap.

Inputs: root, prune, dryRun. Returns: lock, added, dryRun, inCode, +10 more

verbaly_initSet up Verbaly in a projectA
Idempotent

Create the config file and the locale catalogs, and detect the bundler or meta-framework so the answer names the package to add and the line to wire (what verbaly init does). A file already there is kept, never overwritten, so running it again is safe. Use it when verbaly_doctor finds no config; once the project is set up, verbaly_doctor is the one to run.

Inputs: dir, root, locales, sourceLocale. Returns: host, next, found, created, +4 more

verbaly_missingMissing and broken translationsA
Read-only

The gate verbaly check runs in CI, as lists: missing translations, unknown keys, keys written with two texts (collisions: every place shows the first text) and translations that cannot render what the source renders. A dropped {param}, a lost rich tag or a flattened plural block is that last kind. Warnings never fail the gate and are listed too: an incomplete plural set for the locale, keys only a translation has (extra), texts the code and the source catalog disagree on (divergent: the text in the code ships) and translations written for an older source text (outdated). With drafts set, it also lists the machine translations awaiting review. Read-only. For counts use verbaly_status, to review drafts with their source text verbaly_drafts, and for setup problems verbaly_doctor.

Inputs: root, drafts. Returns: ok, extra, broken, missing, +6 more

verbaly_statusTranslation coverageA
Read-only

Translation coverage of the Verbaly project as numbers per locale: total messages, translated, machine translations awaiting review (drafts), broken, and translations written for an older source text (outdated). It scans the source like verbaly_extract but writes nothing. Read-only. For the entries behind the numbers, use verbaly_missing (what is missing or broken) or verbaly_drafts (each draft with its source text).

Inputs: root. Returns: source, locales, messages, stateProblem

verbaly_translateMachine-translate missing entriesA
Idempotent

Fill missing translations with the configured provider (what verbaly translate does). The default provider is Claude, which needs @anthropic-ai/sdk and ANTHROPIC_API_KEY. Every new translation is saved as a draft awaiting human review (verbaly review), which no tool here can approve. Each language is saved as soon as its last batch lands, so a run that is cut keeps the languages it finished. A batch the provider never answers, or a language whose file cannot be saved, is reported in failed and everything else stays written, so a retry only asks for what is left. dryRun lists what would be translated without calling the provider. A locale the project does not have is an error that lists the ones it has, never an empty result. To see what is missing first, use verbaly_missing; to save translations you wrote yourself, verbaly_write_drafts.

Inputs: root, dryRun, locales. Returns: kept, lock, dryRun, failed, +3 more

verbaly_wrapWrap hardcoded JSX textA
DestructiveIdempotent

Find hardcoded user-visible text in JSX/TSX files and wrap it in a t tagged template so the compiler can extract it (what verbaly wrap does). This is how an existing codebase is onboarded, and verbaly_extract then adds the wrapped texts to the catalogs. It only reports unless write is set, and text already wrapped is skipped, so running it again is safe. Text it cannot wrap safely (a sentence split across markup, an expression rendering JSX) is listed as needing a human. A file that does not bind t is never written, because the rewrite would not compile. It comes back in blocked, with the binding this project needs there, so you can add it and run again.

Inputs: root, write. Returns: files, write, blocked, changed, +2 more

verbaly_write_draftsSave translations an agent wroteA
DestructiveIdempotent

Save translations you wrote yourself, so neither a catalog nor the state file is ever edited by hand. Each one is checked the way verbaly_translate checks a provider (params, rich tags and plural cases must survive), written only for keys the source catalog has, and marked as a draft awaiting human review. Existing translations are kept unless overwrite is set, which is how an outdated one gets rewritten. Approving is not a tool here: a human reads the drafts (verbaly_drafts lists them) and runs verbaly review --approve.

Inputs: locale (required), entries (required), root, overwrite. Returns: kept, lock, invalid, unknown, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool targets a distinct lifecycle step (init, extract, wrap, translate, write_drafts, missing, drafts, status, doctor), but the read-only reporting trio (status/missing/drafts) and the write side (translate vs write_drafts) sit close together. The descriptions do explicitly delimit them ('for counts use verbaly_status', 'to save translations you wrote yourself, verbaly_write_drafts'), so an agent can separate them, but it takes careful reading.

    Naming Consistency5/5

    Every tool uses the same verbaly_<verb/verb_noun> snake_case convention (translate, write_drafts, extract, wrap, init, doctor, missing, drafts, status). The prefix and casing are uniform throughout with no deviations.

    Tool Count5/5

    Nine tools map cleanly onto the CLI's commands and each earns its place: one per lifecycle stage plus three focused read-only diagnostics. The set is well within the ideal 3-15 range and nothing looks redundant at the command level.

    Completeness4/5

    The surface covers setup (init), source handling (extract, wrap), translation generation (translate, write_drafts), and full read-only insight (status, missing, drafts, doctor). The one deliberate gap is approval/review: machine drafts can only be accepted via `verbaly review --approve` outside the tools, which is an intentional human-in-the-loop dead end rather than an oversight.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers