---
title: "Schnellstart"
description: "Installiere die CLI, erzeuge eine Konfiguration, sieh dir den Lauf ohne API-Schlüssel in der Vorschau an und übersetze deine erste Locale-Datei."
type: "tutorial"
---
# Schnellstart

Installiere die CLI, erzeuge eine Konfiguration, sieh dir den Lauf ohne API-Schlüssel in der Vorschau an und übersetze deine erste Locale-Datei.

Am Ende dieser Seite hat eine englische Locale-Datei eine deutsche Schwester, geschrieben von einem Provider und von verbatra geprüft, dazu die Lock-Datei, mit der jeder spätere Lauf nur noch übersetzt, was sich geändert hat. Du brauchst Node.js `^22.18.0 || >=24` und etwa zehn Minuten. Die ersten vier Schritte brauchen weder ein Konto noch einen API-Schlüssel.

<Callout title="Du hast schon Locale-Dateien und einen Coding-Agenten?">
Gib deinem Agenten den Prompt von [verbatra mit einem KI-Agenten einrichten](https://verbatra.kreitz-webdev.de/de/docs/start-with-ai.md). Er richtet verbatra um die Locale-Dateien ein, die dein Projekt schon hat, und hält an, bevor er etwas ausgibt. Die Schritte unten fangen bei null an.
</Callout>

Einen Schnellstart, der die übersetzte Datei auch in deiner App lädt, gibt es für [React](https://verbatra.kreitz-webdev.de/de/docs/quickstart/react.md), [Next.js](https://verbatra.kreitz-webdev.de/de/docs/quickstart/nextjs.md), [Vue](https://verbatra.kreitz-webdev.de/de/docs/quickstart/vue.md), [Angular](https://verbatra.kreitz-webdev.de/de/docs/quickstart/angular.md) und [Flutter](https://verbatra.kreitz-webdev.de/de/docs/quickstart/flutter.md).

## Schritte [#schritte]

<Steps>
<Step>

### Installiere die CLI [#installiere-die-cli]

```bash
npm install --save-dev @verbatra/cli
```

Die Befehle unten nutzen `npx`. Mit pnpm, yarn oder bun nimmst du stattdessen `pnpm verbatra`, `yarn verbatra` oder `bun run verbatra`. Bricht pnpm mit `ERR_PNPM_IGNORED_BUILDS` ab, hilft dir die [Fehlerbehebung](https://verbatra.kreitz-webdev.de/de/docs/troubleshooting.md#pnpm-blockiert-die-installationsskripte-einer-abhängigkeit-err_pnpm_ignored_builds).

</Step>
<Step>

### Lege eine Quell-Locale-Datei an [#lege-eine-quell-locale-datei-an]

Hat dein Projekt schon Locale-Dateien, überspringst du diesen Schritt. Sonst legst du eine an:

```json title="locales/en.json"
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}
```

</Step>
<Step>

### Erzeuge eine Konfiguration [#erzeuge-eine-konfiguration]

```bash
npx @verbatra/cli init --format i18next-json --provider gemini --yes
```

`--format` nennt dein Dateiformat: [Wähle deinen Stack](https://verbatra.kreitz-webdev.de/de/docs/pick-your-stack.md) hat die ID für jedes Framework. `--yes` übernimmt, was `init` erkannt hat, statt nachzufragen; lässt du es weg, beantwortest du die Fragen, die [`verbatra init`](https://verbatra.kreitz-webdev.de/de/docs/cli/init.md) auflistet.

```text output
created verbatra.config.ts
created .env.example
created .gitignore (.env, .env.local, .verbatra-local/, verbatra.cache.json)
detected format i18next-json, pattern locales/{locale}.json, locales en (confidence: medium)
next steps:
  - Copy .env.example to .env and set GEMINI_API_KEY there. Never commit .env.
  - npx @verbatra/cli doctor  (Check the setup. It calls no provider and reads no key value.)
  - npx @verbatra/cli translate --dry-run  (Preview what a run would translate, without calling the provider.)
```

Die neue `verbatra.config.ts` übersetzt von `en` nach `de`. Für weitere Sprachen ergänzt du Codes in `targetLocales`.

</Step>
<Step>

### Sieh dir den Lauf ohne Schlüssel an [#sieh-dir-den-lauf-ohne-schlüssel-an]

```bash
npx @verbatra/cli translate --dry-run
```

```text output
verbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
  de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)
```

Das ist die Form im interaktiven Terminal; in einer Pipe oder in CI bekommt jeder Schritt zusätzlich eine eigene Zeile, siehe [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe). Ein Probelauf baut keinen Provider, braucht also keinen Schlüssel, kostet nichts und schreibt nichts. [`verbatra doctor`](https://verbatra.kreitz-webdev.de/de/docs/cli/doctor.md) prüft den Rest der Einrichtung auf dieselbe Weise.

</Step>
<Step>

### Übersetze [#übersetze]

```bash
cp .env.example .env
```

Öffne `.env` und füge deinen Schlüssel hinter `GEMINI_API_KEY=` ein. Schlüssel kommen immer nur aus der Umgebung, und die CLI lädt [`.env.local` und `.env`](https://verbatra.kreitz-webdev.de/de/docs/cli.md#umgebungsdateien) hinein. Noch kein Schlüssel? Gemini hat eine kostenlose Stufe: Erstelle einen im [Google AI Studio](https://aistudio.google.com/apikey). Alle anderen Provider und ihre Variablen stehen unter [Provider](https://verbatra.kreitz-webdev.de/de/docs/providers.md).

```bash
npx @verbatra/cli translate
```

verbatra schickt die zwei fehlenden Keys an Gemini, prüft jedes Ergebnis und schreibt die deutsche Datei. Die Zusammenfassung beginnt mit `de: 2 translated, 0 unchanged` und nennt die Tokens, die der Lauf verbraucht hat. Der Wortlaut hängt vom Modell ab, zum Beispiel:

```json title="locales/de.json"
{
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "empty": "Dein Warenkorb ist leer."
  }
}
```

</Step>
<Step>

### Prüfe, ob jede Locale synchron ist [#prüfe-ob-jede-locale-synchron-ist]

```bash
npx @verbatra/cli check
```

```text output
[ok] checking the locales (0.0s)
verbatra check
  de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in sync
```

`check` ruft keinen Provider auf und endet mit `1`, sobald eine Locale nicht mehr synchron ist. Derselbe Befehl kann also einen Pull Request absichern.

</Step>
</Steps>

## Was gerade passiert ist [#was-gerade-passiert-ist]

- `locales/de.json` hat dieselben Keys in derselben Reihenfolge wie deine Quelle, und `{{name}}` ist erhalten geblieben: Ein Ergebnis, das einen Platzhalter verliert, wird zurückgehalten und nie geschrieben. Siehe [Übersetzungssicherheit](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md).
- `verbatra.lock.json` speichert einen Hash des Quelltexts hinter jeder Übersetzung, damit der nächste Lauf nur neue und geänderte Keys schickt. Siehe [Die Lock-Datei](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md).
- `verbatra.provenance.json` hält fest, welcher Provider und welches Modell jeden Wert geschrieben hat. Siehe [Herkunft](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md#herkunft-wer-welchen-wert-geschrieben-hat).
- `verbatra.cache.json` und `.verbatra-local/` enthalten den neu erzeugbaren Übersetzungscache und den lokalen Laufzustand. `init` hat beide schon in die `.gitignore` eingetragen. Siehe [Der Cache](https://verbatra.kreitz-webdev.de/de/docs/the-cache.md).

Committe die Locale-Dateien, die Lock-Datei und die Herkunftsdatei zusammen, damit jeder Rechner und deine CI gegen dieselbe Basis vergleichen.

## Nächste Schritte [#nächste-schritte]

<Cards>
  <Card title="Eine Sprache hinzufügen" href="https://verbatra.kreitz-webdev.de/de/docs/add-a-language.md" description="Ergänze eine Ziel-Locale und lass einen Lauf sie füllen." />
  <Card title="verbatra in der CI ausführen" href="https://verbatra.kreitz-webdev.de/de/docs/ci-and-exit-codes.md" description="Lass einen Pull Request fehlschlagen, wenn eine Locale abweicht." />
  <Card title="So funktioniert ein Lauf" href="https://verbatra.kreitz-webdev.de/de/docs/how-it-works.md" description="Die Pipeline hinter den Befehlen, die du gerade ausgeführt hast." />
  <Card title="Konfigurationsdatei" href="https://verbatra.kreitz-webdev.de/de/docs/config-file.md" description="Alles, was verbatra.config.ts enthalten kann." />
</Cards>