---
title: "Introduction"
description: "What verbatra is and the problem it solves: translating only the keys that changed. Learn how the CLI and SDK fit with Studio and the MCP server."
type: "overview"
---
# Introduction

What verbatra is and the problem it solves: translating only the keys that changed. Learn how the CLI and SDK fit with Studio and the MCP server.

<DocsHomeHeader
  eyebrow="Documentation"
  headline="Set up verbatra and keep every locale in sync."
  lead="Guides and reference for the CLI, the SDK, Studio, and the MCP server: start with the quickstart, or let your coding agent set verbatra up."
>

<DocsHomeTabs
  label="Entry points"
  tabs={[
    { label: "Quickstart", href: "/docs/quickstart" },
    { label: "CLI", href: "/docs/cli" },
    { label: "SDK", href: "/docs/sdk" },
    { label: "GitHub Action", href: "/docs/github-action" },
    { label: "MCP server", href: "/docs/cli/mcp" },
    { label: "Studio", href: "/docs/review-in-studio" },
  ]}
/>

<DocsHomeAgentTip title="Using a coding agent?">
Copy the prompt into Claude Code, Cursor, or any coding agent, and it sets verbatra up for you; [Set up with an AI agent](https://verbatra.kreitz-webdev.de/docs/start-with-ai.md) shows each step. To let it read and edit your translations directly, connect the [MCP server](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md).
</DocsHomeAgentTip>

</DocsHomeHeader>

<DocsHomeBody>

<DocsHomeSection title="Start from your goal" lead="Pick what you want to do; each card opens the page that does it.">

<DocsHomePaths
  cards={[
    {
      goal: "Translate a project",
      page: "Quickstart",
      body: "Install the CLI, preview the run without a key, then translate your first file.",
      href: "/docs/quickstart",
    },
    {
      goal: "Gate pull requests",
      page: "CI and exit codes",
      body: "Fail a pull request when a locale drifts, with JSON output for scripts.",
      href: "/docs/ci-and-exit-codes",
    },
    {
      goal: "Hand off to translators",
      page: "Human translation",
      body: "Export a workbook for a person to translate, then import it back.",
      href: "/docs/manual-translation",
    },
  ]}
/>

</DocsHomeSection>

<DocsHomeSection id="pick-your-stack" title="Pick your stack" lead="A card marked Quickstart opens a step-by-step guide for that stack; every other card opens its init command and file layout.">

<StackCards
  labelledBy="pick-your-stack"
  cards={[
    { label: "React", icon: "web", mark: "react", formats: ["i18next-json"], href: "/docs/quickstart/react", badge: "Quickstart", description: "Translate i18next JSON files in a React app." },
    { label: "Next.js", icon: "web", mark: "deviconNextjs", formats: ["next-intl-json"], href: "/docs/quickstart/nextjs", badge: "Quickstart", description: "Keep next-intl message files in sync across every locale." },
    { label: "Vue", icon: "web", mark: "fontawesomeVuejs", formats: ["vue-i18n-json"], href: "/docs/quickstart/vue", badge: "Quickstart", description: "Translate vue-i18n JSON messages in a Vue app." },
    { label: "Nuxt", icon: "web", mark: "deviconNuxt", formats: ["vue-i18n-json"], href: "/docs/pick-your-stack#vue-and-nuxt-with-vue-i18n", description: "Translate vue-i18n JSON messages in a Nuxt app." },
    { label: "Angular", icon: "web", mark: "angular", formats: ["ngx-translate-json"], href: "/docs/quickstart/angular", badge: "Quickstart", description: "Translate ngx-translate JSON files in an Angular app." },
    { label: "Flutter", icon: "mobile", mark: "fontawesomeFlutter", formats: ["arb"], href: "/docs/quickstart/flutter", badge: "Quickstart", description: "Translate ARB files for Flutter's gen-l10n." },
    { label: "Android", icon: "mobile", mark: "android", formats: ["android-xml"], href: "/docs/pick-your-stack#android", description: "Translate strings.xml resources, one folder per locale." },
    { label: "iOS and macOS", icon: "mobile", mark: "fontawesomeApple", formats: ["apple-strings", "apple-xcstrings"], href: "/docs/pick-your-stack#ios-and-macos", description: "Translate .strings, .stringsdict, and String Catalogs." },
    { label: "gettext", icon: "po", formats: ["gettext-po"], href: "/docs/pick-your-stack#gettext", description: "Translate PO files from a POT template." },
    { label: "Java and Spring", icon: "server", mark: "deviconSpring", formats: ["properties"], href: "/docs/pick-your-stack#java-and-spring", description: "Translate .properties message bundles." },
    { label: ".NET", icon: "server", mark: "dotnet", formats: ["resx"], href: "/docs/pick-your-stack#net", description: "Translate .resx resource files." },
    { label: "YAML", icon: "yaml", formats: ["yaml"], href: "/docs/pick-your-stack#yaml", description: "Translate nested YAML locale files." },
    { label: "XLIFF", icon: "xliff", formats: ["xliff"], href: "/docs/pick-your-stack#xliff", description: "Translate XLIFF files, the format translation tools exchange." },
    { label: "INI", icon: "ini", formats: ["ini"], href: "/docs/pick-your-stack#ini", description: "Translate flat INI locale files." },
  ]}
/>

<DocsHomeNote>
Don't see your stack? Start with the [generic quickstart](https://verbatra.kreitz-webdev.de/docs/quickstart.md), or teach verbatra your format with a [custom format adapter](https://verbatra.kreitz-webdev.de/docs/custom-format-adapters.md).
</DocsHomeNote>

</DocsHomeSection>

<DocsHomeSection title="Every run is a diff, not a rewrite." lead="What happens when you run `verbatra translate`.">

Hand-maintaining one source locale means every other locale file drifts: new keys go missing from the targets, edited strings leave stale translations behind, and deleted keys linger as orphans. verbatra closes that gap by diffing every target against a committed lock file, `verbatra.lock.json`, and sending only what changed to the provider you configure; a second run with nothing new to translate makes no provider call at all. Every result is checked before it is written, so a broken placeholder is withheld and retried, never shipped. See [How it works](https://verbatra.kreitz-webdev.de/docs/how-it-works.md) for the full pipeline.

<DocsHomeSteps />

verbatra reads and writes the common locale file formats, from JSON and YAML to XLIFF, gettext, and Android and Apple catalogs, and translates through any supported LLM or machine-translation provider behind one interface (or none, for a [human-only workflow](https://verbatra.kreitz-webdev.de/docs/human-only-workflow.md)), and a format it does not ship can be added as a [custom adapter](https://verbatra.kreitz-webdev.de/docs/custom-format-adapters.md). The full lists are on [Formats](https://verbatra.kreitz-webdev.de/docs/formats.md) and [Providers](https://verbatra.kreitz-webdev.de/docs/providers.md).

</DocsHomeSection>

<DocsHomeSection title="The packages" lead="One engine, four ways to drive it.">

<DocsHomeFeatures
  features={[
    {
      title: "@verbatra/cli",
      pkg: "cli",
      body: "The verbatra binary: every command, from init and extract to translate, check, export, and studio, as a thin wrapper over the SDK. Start here.",
      href: "/docs/cli",
    },
    {
      title: "@verbatra/sdk",
      pkg: "sdk",
      body: "The engine underneath: translate, watch, check, diff, doctor, extract, pseudolocalization, type generation, and the Excel and TMX round-trips, all from code.",
      href: "/docs/sdk",
    },
    {
      title: "@verbatra/studio",
      pkg: "studio",
      body: "A local dashboard with in-place editing, a review queue, an Overview of coverage and runs, and browser agent tools. Provider spend stays off unless you opt in.",
      href: "/docs/review-in-studio",
    },
    {
      title: "@verbatra/mcp",
      pkg: "mcp",
      body: "A stdio MCP server exposing translation status, glossary, and editing tools to Claude Code, Cursor, or any MCP client.",
      href: "/docs/cli/mcp",
    },
  ]}
/>

</DocsHomeSection>

</DocsHomeBody>