@intlayer/docs 9.4.2 → 9.4.3

package/blog/de/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Datums- und Zahlenformatierung nach Locale mit Intl"
+description: Sie brauchen wahrscheinlich keine externe Formatierungsbibliothek. Wie Intl Daten, Zahlen, Währungen und Listen nach Locale handhabt, Caching-Aufwand und Hydration-Bugs in Produktion.
+keywords:
+  - datum nach locale formatieren
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - währungsformatierung locale
+  - relative zeit formatieren
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Datums- und Zahlenformatierung nach Locale mit Intl
+
+Das Übersetzen von Texten ist nur die sichtbare Hälfte der Internationalisierung. Die andere Hälfte, die regelmäßig Fehlerberichte erzeugt, ist die Formatierung: ein deutscher Nutzer, der `1,234.56` statt `1.234,56` sieht, ein japanischer Nutzer, der `08/02/2026` als August liest, oder ein Datum, das auf Server und Client unterschiedlich rendert und beim Hydrieren die Anwendung zum Absturz bringt.
+
+Für nichts davon ist eine externe Bibliothek erforderlich. `Intl` ist in jeder modernen JavaScript-Laufzeitumgebung integriert.
+
+## Inhaltsverzeichnis
+
+<TOC/>
+
+## Beginnen Sie damit, eigene Datums-Hilfsfunktionen zu löschen
+
+Fast jede Codebasis enthält irgendwo ein selbst geschriebenes `formatDate`, das entstand, bevor jemand an Locales dachte. Es legt eine starre Reihenfolge, Trennzeichen und meist englische Monatsnamen fest.
+
+```ts
+// Zu löschen:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` ersetzt dies vollständig und ist für jede Locale korrekt:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+Dasselbe gilt für Zahlenwerte. `toFixed(2)` erzeugt überall `1234.56`, was im Großteil Europas schlichtweg falsch ist.
+
+## Was `Intl` abdeckt
+
+| API                       | Verwendungszweck                                          |
+| :------------------------ | :-------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Datums- und Zeitangaben mit `dateStyle` / `timeStyle`     |
+| `Intl.NumberFormat`       | Dezimalzahlen, Währungen, Prozent, Einheiten, Kompaktform |
+| `Intl.RelativeTimeFormat` | "vor 3 Tagen", "in 2 Stunden"                             |
+| `Intl.ListFormat`         | "a, b und c" im Vergleich zu "a, b, and c"                |
+| `Intl.PluralRules`        | Pluralisierungskategorien für Zahlenwerte                 |
+| `Intl.Collator`           | Sprachlich korrekte Sortierung von Zeichenketten          |
+
+`Intl.Collator` wird gern übersehen. Ein einfaches `array.sort()` auf Strings nutzt die Unicode-Codepoint-Reihenfolge, wodurch Umlaute hinter das `z` rutschen und das schwedische `ö` an falscher Stelle landet. Wer für Nutzer sichtbare Listen sortiert, sollte stets einen Collator einsetzen.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("de").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Voreinstellungen bevorzugen statt manueller Optionen
+
+`dateStyle` und `timeStyle` überlassen der jeweiligen Locale die logische Reihenfolge und Trennzeichen. Wer `year`, `month` und `day` manuell kombiniert, greift in Bereiche ein, die man besser meidet, da die korrekte Anordnung je nach Land variiert und man CLDR-Daten mit eigenen Annahmen überschreibt.
+
+```ts
+// Die Locale bestimmt die Struktur:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Selbst bestimmt, und in anderen Regionen fehlerhaft:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Spezifizieren Sie Einzelteile nur dann explizit, wenn das Design zwingend eine feste Breite vorschreibt, beispielsweise in einer engen Tabellenspalte.
+
+## Das Erstellen von Formatierern ist rechenintensiv
+
+Dies ist das Performance-Detail, auf das es ankommt. Die Initialisierung eines `Intl.NumberFormat` lädt umfangreiche Locale-Daten und ist deutlich teurer als der eigentliche Aufruf von `.format()`. Dies in einer Schleife über tausend Tabellenzeilen auszuführen, bremst spürbar.
+
+```ts
+// Erstellt den Formatierer für jede Zeile neu:
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Einmal erstellen und wiederverwenden:
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` und `toLocaleString()` verbergen intern denselben Mechanismus: Jeder Aufruf instanziiert einen neuen Formatierer. Für Einzelwerte völlig in Ordnung, für Listen fehl am Platz.
+
+Cachen Sie Formatierer basierend auf Locale und Optionen:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## Der Zeitzonen-Fehler, der nur in Produktion auftritt
+
+Dieses Problem hat schon unzählige Stunden gekostet. Der Server rendert ein Datum bei der serverseitigen Generierung, der Browser hydriert es im Client, und React bricht mit einem Hydration Mismatch ab, weil beide Umgebungen unterschiedlichen Text erzeugt haben.
+
+Die Ursache: `Intl.DateTimeFormat` verwendet die lokale Zeitzone des Systems, wenn keine angegeben wird. Ihr Produktionsserver läuft unter UTC, Ihr lokaler Entwicklungsrechner nicht. Der Fehler ist lokal unsichtbar und tritt erst in Produktion auf.
+
+```ts
+// Server in UTC und Browser in UTC+9 liefern unterschiedliche Texte. Hydration Mismatch.
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Beide Umgebungen stimmen überein:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Drei gangbare Lösungswege:
+
+- **Zeitzone auf dem Server fixieren** und explizit übergeben. Deterministisch, aber alle Nutzer sehen UTC.
+- **Nur auf dem Client rendern**, mit einem Platzhalter während des Server-Passes. Individuell korrekt, erzeugt jedoch ein leichtes Nachladen.
+- **Zeitzone des Nutzers speichern** und an beiden Stellen übergeben. Das beste Ergebnis bei moderatem Mehraufwand.
+
+Unabhängig von der Wahl: Übergeben Sie `timeZone` bei isomorphen Datumsangaben immer explizit. Ein Datum ohne definierte Zeitzone führt unweigerlich zu zwei abweichenden Werten.
+
+## Währungen benötigen eine Währung, keine Locale
+
+Locale und Währung sind unabhängig voneinander. `fr-FR` bedeutet nicht automatisch Euro: Ein französischer Kunde kann durchaus eine Rechnung in US-Dollar betrachten.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+Die Locale steuert Trennzeichen, Zifferngruppierung und die Platzierung des Währungssymbols. Die Währung selbst stammt aus Ihren Geschäftsdaten. Die Ableitung des einen aus dem anderen führt unweigerlich zu Fehlern in der Buchhaltung.
+
+Beachten Sie auch `currencyDisplay`. In Systemen mit mehreren Währungen, die das Dollarzeichen teilen, beseitigt `"code"` jegliche Mehrdeutigkeit zwischen US-, kanadischen und australischen Dollar.
+
+## Relative Zeitangaben sind oft lesbarer als absolute Daten
+
+Für kürzlich zurückliegende Ereignisse ist "vor 2 Stunden" weit eingängiger als ein Zeitstempel, und `Intl.RelativeTimeFormat` lokalisiert dies automatisch.
+
+```ts
+new Intl.RelativeTimeFormat("de", { numeric: "auto" }).format(-1, "day");
+// "gestern"
+```
+
+`numeric: "auto"` liefert "gestern" statt "vor 1 Tag". Ohne diese Option erhält man die unnatürlich wirkende rein numerische Schreibweise.
+
+## Was Intlayer ergänzt
+
+Intlayer bündelt diese APIs in gecachten Hilfsfunktionen, sodass Sie keine eigene Cache-Map verwalten müssen, und wendet die aktive Locale standardmäßig an, ohne dass sie an jeder Aufrufstelle übergeben werden muss.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1.234,5"
+currency(1234.5, { currency: "EUR" }); // "1.234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "vor 2 Stunden"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 Kilometer"
+compact(1200); // "1,2 Tsd."
+list(["Apfel", "Banane", "Orange"]); // "Apfel, Banane und Orange"
+```
+
+Die Funktion `date()` unterstützt zudem Presets (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`), womit typische Anwendungsfälle ohne Options-Objekt auskommen. Für React und Vue stehen Hooks und Composables bereit, die die aktive Sprache direkt aus dem Kontext ermitteln.
+
+Dabei handelt es sich um eine komfortable Caching- und Locale-Schicht über der nativen Plattform-API. Das eigentliche Formatierungsverhalten basiert vollständig auf `Intl`. Sämtliche Signaturen finden sich in der [Formatierungsdokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/formatters.md).
+
+## Häufige Fehler
+
+- **`toLocaleDateString()` ohne Locale-Angabe.** Verwendet die Standard-Locale des Systems, die auf einem Server vom Container abhängt.
+- **Formatieren in einer Schleife ohne Caching.** Die Instanziierung des Formatierers dominiert die Laufzeit.
+- **Fehlende `timeZone`-Angabe bei isomorphen Datumsangaben.** Führt zu Hydration-Fehlern, die lokal nicht auftreten.
+- **Währung aus der Locale ableiten.** `fr-FR` garantiert keine Euro-Werte.
+- **Einfaches `sort()` auf sichtbaren Texten.** Nutzen Sie stets `Intl.Collator`.
+- **Monats- oder Wochentagsnamen fest codieren.** Sie sind bereits in jeder Sprache im CLDR hinterlegt.
+- **`numeric: "always"` bei relativen Zeiten beibehalten.** Erzeugt "vor 1 Tag", obwohl jede Sprache ein Wort wie gestern kennt.
+
+## Weiterführende Ressourcen
+
+- [Formatierer und Locale-Hilfsfunktionen: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/formatters.md)
+- [Konfigurationsreferenz](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md)
+- [Framework-Benchmarkberichte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/benchmark/index.md)
+- [react-intl-Kompatibilitätsadapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/react-intl.md)
+- [ICU Message Format: Plurale, Select und Zahlenskelette](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/icu_message_format.md)
+- [Übersetzungen testen: Inklusive Formatierer und Pluralregeln](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/i18n_testing_strategies.md)
+- [Was Internationalisierung wirklich umfasst](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/what_is_internationalization.md)

package/blog/de/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Fehlende Übersetzungen aufspüren, bevor es Ihre Nutzer tun"
+description: Fehlende Übersetzungen schlagen geräuschlos fehl. Warum Fallbacks sie verschleiern, welche vier Erkennungsebenen wirklich funktionieren und wie man Builds bei unübersetzten Schlüsseln abbricht.
+keywords:
+  - fehlende übersetzungen finden
+  - fehlende übersetzungsschlüssel
+  - i18n audit
+  - unübersetzte zeichenketten
+  - übersetzungsabdeckung
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Fehlende Übersetzungen aufspüren, bevor es Ihre Nutzer tun
+
+Eine fehlende Übersetzung wirft so gut wie nie einen sichtbaren Fehler. Je nach Setup zeigt sie einem japanischen Nutzer den englischen Text oder gibt `checkout.summary.total` direkt auf der Benutzeroberfläche in Produktion aus. Beides wird deployt, beides besteht jedes Code-Review und beides wird am Ende von Kunden bemerkt statt von Ihnen.
+
+## Inhaltsverzeichnis
+
+<TOC/>
+
+## Dies gilt unabhängig von der verwendeten Bibliothek
+
+Nichts hier ist an einen bestimmten Stack gebunden. Die folgenden Erkennungsebenen funktionieren bei i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate oder Lingui identisch, weil alle Bibliotheken Schlüssel nach demselben Prinzip auflösen und auf dieselbe Weise versagen.
+
+Auch die Werkzeuge lassen sich nahtlos übertragen: Liegen Ihre Nachrichten heute in JSON-Katalogen, verknüpft das [Sync JSON-Plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/plugins/sync-json.md) Intlayer mit diesen Dateien. Dadurch erhalten Sie Audit-, Fill- und Test-Befehle, ohne Inhalte zu verschieben oder Imports anzupassen:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // oder "icu" für next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Möchten Sie auch die gewohnte Runtime-API beibehalten, erstellen [Kompatibilitätsadapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/index.md) Aliasse für `useTranslation`, `$t` und Co. auf Bundler-Ebene. Betrachten Sie die folgenden Befehle als konkrete Umsetzung des Konzepts, nicht als starre Vorgabe.
+
+## Warum fehlende Übersetzungen unsichtbar bleiben
+
+Jede i18n-Bibliothek löst Schlüssel über dieselbe Kette auf: Aktive Locale suchen, auf die Standard-Locale zurückfallen und bei erneutem Misserfolg den Schlüssel selbst als String zurückgeben. Genau dieser letzte Schritt ist das Problem. Es gibt keinen Laufzeitfehler, keine Warnung in Produktion und keinen fehlschlagenden Test, weil kein Glied der Kette einen fehlenden Schlüssel als unnormal einstuft.
+
+Das Fallback-Verhalten verschlimmert die Lage: Eine Seite, die stillschweigend auf Englisch rendert, sieht für einen englischsprachigen Entwickler und für automatisierte Tests völlig in Ordnung aus. Der Fehler ist nur für denjenigen sichtbar, der die Sprache nicht versteht.
+
+Die Frage lautet daher nicht: „Wie fange ich fehlende Übersetzungen zur Laufzeit ab?“, sondern: „Wie stelle ich sicher, dass fehlende Übersetzungen gar nicht erst gemergt werden können?“
+
+## Die vier Ebenen zur Erkennung
+
+Jede Ebene deckt Dinge auf, die den anderen entgehen. Sie sollten mehr als eine davon einsetzen.
+
+| Ebene           | Erkennt                                            | Übersieht                                      |
+| :-------------- | :------------------------------------------------- | :--------------------------------------------- |
+| Typen           | Schlüssel, die überhaupt nicht existieren          | Schlüssel existiert, ist aber in `ja` leer     |
+| Linter          | Fest codierte Texte, die nie externalisiert wurden | Schlüssel, die in einem Katalog fehlen         |
+| Audit           | Locale-Abdeckung über alle deklarierten Schlüssel  | Texte, die nie als übersetzbar markiert wurden |
+| Rendering-Tests | Schlüssel, die auflösen, aber falsch rendern       | Alles, was nicht von einem Test abgedeckt ist  |
+
+Die häufigste Schwachstelle liegt in der dritten Zeile: Teams wissen, dass ihre Schlüssel syntaktisch existieren, prüfen aber nie, ob tatsächlich alle achtzehn Sprachen mit Inhalten hinterlegt sind.
+
+## Ebene 1: Den Schlüssel zu einem Typen machen, nicht zu einem String
+
+`t("checkout.summry.total")` ist ein Tippfehler, der problemlos kompiliert. Sind Schlüssel reine Strings, birgt jedes Umbenennen ein Produktionsrisiko und jedes Löschen hinterlässt Leichen im Code.
+
+Typisierte Schlüssel machen daraus einen Compiler-Fehler. `react-i18next` unterstützt dies über Declaration Merging, `next-intl` leitet Typen aus Nachrichtenstrukturen ab, Lingui generiert IDs aus Quelltexten und Intlayer erzeugt Typen direkt aus den Deklarationsdateien. Alle Ansätze funktionieren; sie unterscheiden sich lediglich im Aufwand der Konfiguration.
+
+Diese Ebene ist notwendig, aber nicht ausreichend. Typen beschreiben lediglich die Struktur des Standardkatalogs. Sie garantieren nicht, dass im Koreanischen ein Wert hinterlegt ist.
+
+## Ebene 2: Fest codierte Zeichenketten per Linter abfangen
+
+Die Übersetzung, die man nicht findet, ist oft jene, die nie als Schlüssel angelegt wurde. Ein fest codiertes Label in einer Komponente ist für jeden Katalog-Audit unsichtbar, weil der String für die Tools schlicht nicht existiert.
+
+Das ESLint-Plugin von Intlayer deckt dies mit `no-raw-text` ab, ergänzt durch `no-unused-content` für den umgekehrten Fall: deklarierte Inhalte, die nirgendwo mehr referenziert werden.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` verhindert, dass Kataloge ins Unendliche wachsen. Tote Schlüssel stören die Funktion nicht, treiben jedoch Übersetzungskosten unnötig in die Höhe. Die vollständige Regelliste finden Sie in der [ESLint-Plugin-Dokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/eslint.md).
+
+## Ebene 3: Auditierung der Locale-Abdeckung
+
+Diese Ebene beantwortet die eigentliche Kernfrage. Intlayer stellt dafür einen CLI-Befehl bereit:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Der Befehl liest die konfigurierten Sprachen sowie deklarierte Wörterbücher ein und meldet präzise, welchen Schlüsseln welche Sprachen in welcher Datei fehlen.
+
+Ein wichtiges Detail für Ihre Pipelines: **Die CLI gibt einen Bericht aus, beendet sich aber stets mit dem Exit-Code 0.** Wer den Befehl unbedarft in die CI einbindet, erhält grüne Builds mit Textausgaben, die niemand liest. Für Schrankenfunktionen (Gates) nutzen Sie stattdessen die nachfolgend beschriebene programmatische API.
+
+## Ebene 4: Zusicherungen (Assertions) in der Test-Suite
+
+`listMissingTranslations()` liefert dasselbe Audit als strukturiertes Datenobjekt, perfekt geeignet für eine CI-Schranke.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("hat keine fehlenden erforderlichen Locales", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Drei Felder werden zurückgegeben:
+
+- `missingTranslations`: Aufgeschlüsselt nach Schlüssel, welche Sprachen in welcher Datei fehlen. Dies gibt man bei Testfehlern aus.
+- `missingLocales`: Die Gesamtmenge aller fehlenden Sprachen über alle Schlüssel hinweg.
+- `missingRequiredLocales`: Beschränkt auf die in der Konfiguration definierten `requiredLocales`, oder alle Sprachen, falls nicht separat konfiguriert.
+
+## `requiredLocales` macht Prüfungen praxistauglich
+
+Achtzehn Sprachen anzubieten bedeutet nicht, dass stets alle achtzehn komplett sein müssen, um deployen zu können. Die meisten Teams unterscheiden zwischen einer unverzichtbaren Stufe, die Releases blockiert, und Sprachen, die nachgeliefert werden.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Ohne `requiredLocales` gilt jede definierte Sprache als verpflichtend, und der Build bleibt rot, bis die letzte Übersetzung vorliegt. Das führt fast immer dazu, dass die Prüfung entnervt abgeschaltet wird.
+
+## Lücken aufspüren, die bereits in Produktion sind
+
+Die obigen Ebenen verhindern neue Lücken. Für bereits ausgelieferte Anwendungen helfen zwei Ansätze:
+
+**Pseudolokalisierung.** Nutzen Sie eine Test-Locale, in der alle Zeichenketten transformiert werden, z. B. `[!!! Ĉĥéçķöũţ !!!]`. Alles, was weiterhin in reinem Englisch erscheint, ist im Code fest verdrahtet. Dies deckt in zehn Minuten auf, was ein Katalog-Audit technisch unmöglich sehen kann.
+
+**Die eigene Website crawlen.** Bei lokalisierten URLs ruft man Stichproben pro Sprache ab und durchsucht das HTML nach Texten der Standardsprache. Eine Seite unter `/ja/`, die „Add to cart“ enthält, weist entweder auf eine fehlende Übersetzung oder ein unbemerktes Fallback hin.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Lücken schließen
+
+Sind Lücken lokalisiert, füllt `intlayer fill` leere Einträge automatisch auf, während die Option `autoFill` sprachspezifische Dateien direkt bei der Deklaration von Inhalten generieren kann. Siehe [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/autoFill.md).
+
+Man sollte sich darüber im Klaren sein: Maschinell gefüllte Übersetzungen machen eine _sichtbare_ Lücke zu einer _unsichtbaren_. Der Schlüssel besitzt nun Inhalt, der Audit wird grün, gelesen hat den Text jedoch niemand. Nutzen Sie dies, um Releases zu entblocken, und lassen Sie Texte vor Kaufentscheidungen stets durch Menschen gegenlesen.
+
+## Häufige Fehler
+
+- **Fallbacks als Sicherheitsfeature begreifen.** Es ist eine Notfallstrategie, kein Sicherheitsnetz. Eine stillschweigend englische Seite ist ein unbemerkter Fehler.
+- **CLI-Berichte zur Build-Sicherung nutzen.** `intlayer content test` beendet sich mit 0. Nutzen Sie Test-Assertions.
+- **Jede Sprache zwingend vorschreiben.** Die Prüfung fliegt raus, sobald sie den ersten Release aufhält.
+- **Kataloge prüfen, aber nie die gerenderte Seite.** Fest codierte Strings sind im Katalog per Definition unsichtbar.
+- **Nur die Standardsprache in Tests abdecken.** Das ist die einzige Sprache, die unmöglich fehlen kann.
+- **Den Prozess mit maschinellem Befüllen abschließen.** Grüner Audit, unüberprüfte Texte.
+
+## Weiterführende Ressourcen
+
+- [Inhalte testen: CLI-Audit, programmatische API und UI-Assertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/testing.md)
+- [ESLint-Plugin-Regeln, einschließlich `no-raw-text` und `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/eslint.md)
+- [autoFill: Generierung sprachspezifischer Deklarationsdateien](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/autoFill.md)
+- [Konfigurationsreferenz: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md)
+- [Benchmark-Berichte über Frameworks hinweg](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/benchmark/index.md)
+- [i18next-Kompatibilitätsadapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/i18next.md)
+- [Was Internationalisierung wirklich umfasst](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/what_is_internationalization.md)
+- [Komponentenbasierte vs. zentralisierte i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/per-component_vs_centralized_i18n.md)

package/blog/de/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Übersetzungen in CI/CD automatisieren ohne fehlerhafte Texte auszuliefern"
+description: Drei Ebenen zur i18n-Automatisierung, Pre-Push, Pull Request und Laufzeit. Wie man Builds über Abdeckung absichert, sicher automatisch befüllt und endlose CI-Commit-Schleifen vermeidet.
+keywords:
+  - übersetzungen automatisieren ci
+  - i18n ci cd
+  - github actions übersetzungen
+  - husky pre-push
+  - kontinuierliche lokalisierung
+  - translation pipeline
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Übersetzungen in CI/CD automatisieren ohne fehlerhafte Texte auszuliefern
+
+Manuelle Übersetzung hält modernen Release-Zyklen nicht stand. Jemand fügt am Freitag einen String hinzu, der Export erfolgt im nächsten Sprint, und bis dahin hinken drei weitere Sprachen hinterher. Die Automatisierung an sich ist unkompliziert. Sie so zu gestalten, dass nicht unbemerkt maschinell erzeugte Texte vor die Augen von Kunden geraten, ist der entscheidende Punkt.
+
+## Inhaltsverzeichnis
+
+<TOC/>
+
+## Keine Migration erforderlich zur Automatisierung
+
+Die folgenden Pipeline-Architekturen sind bibliotheksunabhängig, genau wie die verwendeten Werkzeuge. Wenn Ihre Nachrichten in JSON-Katalogen für i18next, next-intl, react-intl, vue-i18n oder next-translate liegen, liest und schreibt das [Sync JSON-Plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/plugins/sync-json.md) diese Dateien direkt an Ort und Stelle:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // oder "icu" für next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Ihre Anwendung importiert weiterhin genau das, was sie bisher importiert hat. Die nachfolgenden CI-Jobs befüllen und überwachen Ihre vorhandenen Kataloge, und das Diff, das ein Reviewer sieht, betrifft `locales/fr/checkout.json` und keine Architekturmigration. Es gibt auch ein [Sync PO-Plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/plugins/sync-po.md) für gettext-Workflows sowie [Kompatibilitätsadapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/index.md), um die gewohnte Runtime-API beizubehalten.
+
+## Die Schranke (Gate) vom Befüllen (Fill) trennen
+
+Zwei unterschiedliche Aufgaben werden ständig verwechselt.
+
+Ein **Gate** ist eine Prüfung, die fehlschlägt. Sie besagt, dass dieser Build nicht freigegeben werden darf, weil erforderliche Sprachen unvollständig sind. Ein Gate schreibt keine Dateien.
+
+Ein **Fill** ist eine Mutation. Er generiert die fehlenden Übersetzungen und committet sie. Ein Fill lässt einen Build niemals fehlschlagen.
+
+Führt man nur einen Fill aus, wird niemals etwas blockiert, und ungesehene maschinelle Übersetzungen gelangen ungeprüft in Produktion. Führt man nur ein Gate aus, schlägt der Build fehl und ein Entwickler muss jedes Mal manuell eingreifen. Die meisten Teams kombinieren beides an getrennten Auslösern: Fill bei einem Pull Request, Gate beim Merge in den Release-Branch.
+
+## Wo Automatisierung stattfinden kann
+
+| Phase          | Auslöser    | Geeignet für                              | Kosten                                          |
+| :------------- | :---------- | :---------------------------------------- | :---------------------------------------------- |
+| Pre-Push-Hook  | Lokales Git | Schnelles Feedback, keine CI-Minuten      | Läuft auf dem Entwickler-Rechner mit dessen Key |
+| Pull Request   | CI-Job      | Review vor dem Merge, ein Ort für Secrets | CI-Minuten plus Modellaufrufe pro PR            |
+| Release-Branch | CI-Job      | Harte Schranke bezüglich Abdeckung        | Günstig, keine Modellaufrufe                    |
+| Laufzeit       | CMS         | Inhaltsänderungen ohne Rebuild            | Gehostete Abhängigkeit                          |
+
+## Pre-Push: Der schnellste Zyklus
+
+Husky führt das Befüllen aus, bevor der Code die lokale Maschine verlässt, sodass Übersetzungen im selben Push ankommen wie die neuen Strings.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` beschränkt die Arbeit auf noch nicht gepushte Inhalte, wodurch der Vorgang nicht bei jedem Push eine Minute dauert. `--mode complete` befüllt nur das, was fehlt, ohne bestehende Übersetzungen zu überschreiben, sodass bereits überprüfte Texte nicht verloren gehen.
+
+In einem Monorepo grenzen Sie jede Anwendung ab:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+Der Nachteil liegt auf der Hand: Jeder Entwickler benötigt einen API-Key, und die Kosten trägt derjenige, der pusht. Deshalb verlagern die meisten Teams diesen Schritt in die CI, sobald das Team wächst.
+
+## Pull Request: Befüllen dort, wo das Review stattfindet
+
+Derselbe Ablauf in GitHub Actions, begrenzt auf das Git-Diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Vier Details sind hier essenziell:
+
+- **`fetch-depth: 0`** ist erforderlich, damit `--git-diff` funktioniert. Ein flacher Klon hat keine Basis für ein Diff, und der Vorgang befüllt stillschweigend nichts.
+- **`[skip ci]` in der Commit-Nachricht** verhindert, dass sich der Workflow endlos selbst auslöst. Ohne diesen Zusatz committet der Job, startet einen neuen CI-Lauf, der wieder committet, der klassische Weg, um das CI-Budget über Nacht zu leeren.
+- **`concurrency` mit `cancel-in-progress`** stoppt konkurrierende Pushes daran, gleichzeitig in dieselben Dateien zu schreiben.
+- **`--git-diff`** beschränkt die Generierung auf die Änderungen im PR. Ohne dieses Flag wird bei jedem Durchlauf der gesamte Katalog neu übersetzt.
+
+Die Übersetzungen landen als Commit direkt auf dem PR-Branch, sodass der Reviewer sie im Diff begutachten kann. Genau darin liegt der Vorteil gegenüber einer Generierung nach dem Merge.
+
+## Release-Branch: Das Gate
+
+Das Gate benötigt keinen Modellzugriff und muss schnell sein.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Abgesichert durch einen Test, der die Abdeckung per Assertion prüft, statt sich auf Terminal-Ausgaben zu verlassen:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("hat keine fehlenden erforderlichen Locales", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` gibt einen Bericht aus, beendet sich aber mit Status 0, informiert also nur, ohne den Build anzuhalten. Nutzen Sie es lokal; nutzen Sie den Assertion-Test in der CI. Mehr dazu in [Fehlende Übersetzungen aufspüren](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/detecting_missing_translations.md).
+
+## `requiredLocales` macht das Gate alltagstauglich
+
+Ein Gate, das alle achtzehn Sprachen als vollständig verlangt, blockiert jeden Release, bis die letzte Sprache fertig ist, und wird innerhalb eines Monats deaktiviert.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Deklarieren Sie die angebotenen Locales und verlangen Sie nur diejenigen verpflichtend, die einen Release tatsächlich blockieren müssen. Der Rest wird asynchron befüllt und hält Auslieferungen nicht auf.
+
+## Übersetzungen komplett aus dem Repository auslagern
+
+Das alternative Modell deklariert eine Quellsprache im Code und verwaltet den Rest extern über das CMS mit Live Sync. Inhaltsänderungen erfordern dann überhaupt keinen Rebuild mehr, was redaktionelle Anpassungen von Software-Releases entkoppelt.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Dies eignet sich besonders für Teams, in denen Nicht-Entwickler Texte pflegen. Es ist ein Kompromiss: Man gewinnt redaktionelle Unabhängigkeit, verliert jedoch die Eigenschaft, dass ein Git-Checkout den genauen Render-Zustand der Anwendung widerspiegelt. Details in der [CMS-Dokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/intlayer_CMS.md).
+
+Beachten Sie, dass `clientSecret` ein vertraulicher Serverschlüssel ist. Er gehört in CI-Secrets und Server-Umgebungsvariablen, niemals in ein Client-Bundle.
+
+## Die ehrliche Einschränkung
+
+Alles oben Genannte automatisiert die _Abdeckung_, nicht die _Qualität_. Ein maschineller Fill verwandelt eine sichtbare Lücke in eine unsichtbare: Das Audit wird grün, weil der Schlüssel nun einen Wert hat, den jedoch kein Mensch gegengelesen hat.
+
+Das ist akzeptabel für interne Tools, Changelogs oder Beta-Sprachen. Es ist ungeeignet für Preisseiten, rechtliche Hinweise, Zahlungsfehlermeldungen oder Texte vor Kaufentscheidungen. Leiten Sie diese durch menschliche Reviews und nutzen Sie überall `--mode complete`, damit manuell geprüfte Strings nicht überschrieben werden.
+
+Geben Sie dem Modell Kontext für konsistente Ergebnisse:
+
+```ts
+ai: {
+  applicationContext: "B2B-Rechnungs-App. Formeller Tonfall. Den Produktnamen niemals übersetzen.",
+}
+```
+
+## Häufige Fehler
+
+- **Kein `[skip ci]` beim Auto-Commit.** Der Job startet sich endlos in einer Schleife neu.
+- **Flacher Klon mit `--git-diff`.** Keine Vergleichsbasis vorhanden, nichts wird befüllt, kein Fehler gemeldet.
+- **Gesamten Katalog bei jedem Durchlauf füllen.** Mit `--git-diff` oder `--unpushed` eingrenzen, um Kosten zu sparen.
+- **CLI-Bericht als Gate nutzen.** Er beendet sich mit Return-Code 0.
+- **Jede Sprache zwingend verlangen.** Die Schranke wird beim ersten blockierten Release abgeschaltet.
+- **Fill-Job ganz ohne Gate.** Nichts schlägt fehl, ungeprüfte Texte wandern unbemerkt in Produktion.
+- **Modell-API-Keys im Repository.** Gehören ebenso wie `clientSecret` in CI-Secrets.
+
+## Weiterführende Ressourcen
+
+- [CI/CD: Übersetzungen automatisch generieren mit Husky, GitHub Actions und CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/CI_CD.md)
+- [Inhalte testen und Builds auf Abdeckung absichern](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/testing.md)
+- [autoFill: Deklarationsdateien pro Locale erzeugen](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/autoFill.md)
+- [Konfigurationsreferenz: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md)
+- [Benchmark-Berichte über Frameworks hinweg](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/benchmark/index.md)
+- [i18next-Kompatibilitätsadapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/i18next.md)
+- [Fehlende Übersetzungen aufspüren](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/detecting_missing_translations.md)
+- [Übersetzungen testen ohne fragile Tests](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/i18n_testing_strategies.md)