--- title: "Keys aus dem Quellcode extrahieren" description: "Übernimm die Übersetzungs-Keys, die dein Code schon aufruft, in die Quell-Locale-Datei, füll ihren Text aus und gib sie an translate weiter." type: "how-to" --- # Keys aus dem Quellcode extrahieren Übernimm die Übersetzungs-Keys, die dein Code schon aufruft, in die Quell-Locale-Datei, füll ihren Text aus und gib sie an translate weiter. Nutze das, wenn dein Code deinem Katalog voraus ist: Du schreibst `t("cart.empty", "Your cart is empty")` in eine Komponente und willst den Key in der Quell-Locale-Datei, ohne ihn von Hand zu kopieren. Außerdem bringt es ein Projekt, das nie internationalisiert wurde, von seinem Code aus an den Start statt von einer leeren JSON-Datei. `verbatra extract` liest deinen Quellcode und schreibt nur die Quell-Locale-Datei. Es ruft keinen Provider auf, braucht keinen API-Key und stellt keine Netzwerkanfrage. Du brauchst: - eine verbatra-Konfiguration (führ [`verbatra init`](https://verbatra.kreitz-webdev.de/de/docs/cli/init.md) aus, wenn du keine hast); - Code, der `t(...)`, `$t(...)` oder `i18n.t(...)` von i18next aufruft, das einzige Framework, das `extract` heute liest; - einen Namespace pro Katalogdatei. Ein Key mit Namespace wie `t("common:nav.home")` wird gemeldet und nie geschrieben, weil eine Konfiguration genau eine Datei adressiert. ## Zeig verbatra deinen Quellcode [#zeig-verbatra-deinen-quellcode] Füg einen `extract`-Block mit den Verzeichnissen hinzu, die durchsucht werden sollen: ```ts title="verbatra.config.ts" export default defineConfig({ // ... extract: { framework: "i18next", roots: ["src"], // [!code highlight] }, }); ``` Außerhalb von `roots` wird nichts gelesen, und Build-Ausgaben wie `node_modules` und `dist` werden immer übersprungen. Liegt generierter Code unter einer Root, trag den Namen seines Verzeichnisses in `exclude` ein. Jedes Feld steht unter [`extract`](https://verbatra.kreitz-webdev.de/de/docs/config-file.md#extract). ## Sieh dir an, was hinzukäme [#sieh-dir-an-was-hinzukäme] ```bash verbatra extract --dry-run ``` Die Zusammenfassung listet die neuen Keys mit Datei und Zeile, die sie genannt haben, und schreibt nichts. Lies drei Teile davon, bevor du weitermachst: - **new keys**: was ein echter Lauf der Quelldatei hinzufügen würde. - **dynamic keys**: Aufrufstellen, deren Key kein vollständiger String ist, etwa `t("user." + id)` oder `` t(`nav.${page}`) ``. Sie werden nie geschrieben. Trag diese Keys von Hand in den Katalog ein oder schreib den Aufruf mit einem literalen Key. - **conflicts**: ein Key mit zwei verschiedenen Standardwerten an zwei Aufrufstellen. Keiner der Werte wird geschrieben, also wähl einen Text und bring die Aufrufstellen in Einklang. ## Füg die Keys hinzu [#füg-die-keys-hinzu] ```bash verbatra extract ``` ```text output verbatra extract 42 files scanned, 18 keys already present added 3 keys to locales/en.json new keys (3): nav.home src/components/Nav.tsx:14 nav.away src/components/Nav.tsx:15 cart.empty src/routes/cart.tsx:31 next: verbatra translate (translate the new keys) ``` Ein Standardwert aus der Aufrufstelle wird zum Quelltext des Keys. Ein Key, der schon im Katalog steht, behält seinen Wert, sodass ein erneutes `extract` deine Änderungen nie überschreibt, und ein Lauf, der nichts Neues findet, lässt die Datei byteidentisch. Ein Key, dessen Aufrufstelle keinen Standardwert hatte, wird mit leerem Wert hinzugefügt und im `--json`-Ergebnis unter `withoutDefault` aufgeführt. Schreib seinen Quelltext in die Quell-Locale-Datei, bevor du übersetzt. Wenn dein Format `xliff` oder `apple-xcstrings` ist, leg den Quellkatalog zuerst an (den `.xcstrings`-Katalog in Xcode): `extract` hängt an ihn an, legt ihn aber nie an. ## Übersetze die neuen Keys [#übersetze-die-neuen-keys] ```bash verbatra translate ``` Die neuen Keys fehlen in jeder Ziel-Locale, also übersetzt der Lauf genau sie und sonst nichts. Wenn der Stapel groß ist, schau dir die Kosten vorher mit [`--estimate`](https://verbatra.kreitz-webdev.de/de/docs/estimating-cost.md) an. Wenn du TypeScript nutzt, erzeug deine Key-Deklarationen mit [`verbatra types`](https://verbatra.kreitz-webdev.de/de/docs/cli/types.md) neu, damit ein Tippfehler in einem neuen Key die Kompilierung scheitern lässt. ## Halte Code und Katalog im Gleichschritt [#halte-code-und-katalog-im-gleichschritt] `extract` fügt nur hinzu. Zwei Prüfungen, die nur lesen, decken die anderen Richtungen ab: - `verbatra diff --unused` listet Quell-Keys, die keine Aufrufstelle mehr nennt. Es nutzt die `extract`-Roots und löscht nichts; ob du einen Key entfernst, entscheidest du. Unter [Ungenutzte Quell-Keys](https://verbatra.kreitz-webdev.de/de/docs/cli/diff.md#ungenutzte-quell-keys) steht, wann die Liste vollständig genug ist, um ihr zu trauen. - `verbatra doctor --literals` listet für Nutzer sichtbare Strings, die nie durch `t(...)` gegangen sind, etwa JSX-Text oder ein `aria-label`. Unter [Nicht übersetzte Literale](https://verbatra.kreitz-webdev.de/de/docs/cli/doctor.md#nicht-übersetzte-literale) steht, was zählt und wie du eines zurückhältst. Führ `verbatra extract` erneut aus, wann immer du Aufrufstellen hinzufügst. Das lässt sich gefahrlos wiederholen, und es endet mit `0`, egal was es findet. Ein CI-Schritt, der bei neuen Keys scheitern soll, liest deshalb die Liste `added` aus `--json` statt den Exit-Code. ## Siehe auch [#siehe-auch] - [`verbatra extract`](https://verbatra.kreitz-webdev.de/de/docs/cli/extract.md): die Aufrufformen, die es liest, der vollständige Bericht und das JSON-Ergebnis. - [Die Konfigurationsdatei](https://verbatra.kreitz-webdev.de/de/docs/config-file.md#extract): der `extract`-Block. - [`verbatra translate`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md): füllt die Ziel-Locales. - [Fehlercodes](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#extract_not_configured): `EXTRACT_NOT_CONFIGURED`, wenn der Block fehlt.