Von i18next migrieren

Bevor Sie beginnen

Drei Dinge, dann sind Sie bereit zum Importieren:

• Ein Projekt. Erstellen Sie eines im Dashboard und kopieren Sie dessen project_uuid.
• Ein API-Schlüssel mit dem Scope mcp:*. Die CLI läuft über die MCP-Oberfläche — ein auf das Projekt beschränkter Schlüssel gibt 403 zurück. Die CLI-Referenz beschreibt, wie man einen erstellt.
• Node 18+ und Ihre bestehenden i18next-Dateien, angeordnet als <lang>/<namespace>.json (untypische Anordnungen werden ebenfalls unterstützt).

1. Installieren und initialisieren

Installieren Sie die CLI global, generieren Sie eine Konfiguration, die auf Ihr Projekt zeigt, und exportieren Sie Ihren Schlüssel.

1# one global install — gives you the `sonenta` command (Node >= 18)2npm i -g @sonenta/cli 4# scaffold sonenta.config.json and point it at your project5sonenta init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export SONENTA_TOKEN=snt_live_<prefix>.<secret>

sonenta init schreibt eine sonenta.config.json, die Sie committen können. In der CI überspringen Sie init und übergeben --project sowie die Umgebungsvariable SONENTA_TOKEN. sonenta und SONENTA_* sind kanonisch; der alte Befehl sonenta und die Variablen SONENTA_* funktionieren während des Übergangs noch.

2. Vorschau, dann importieren

Der Importer liest den Pfad jeder Datei, um deren Sprache und Namespace abzuleiten: ein konventioneller locales/-Baum benötigt keine Optionen. Führen Sie zuerst einen Dry-Run durch, um den Plan zu sehen, und entfernen Sie dann --dry-run, um ihn anzuwenden.

1# the importer infers (language, namespace) from each path:2#   <lang>/<namespace>.json3locales/4├─ en/5│  ├─ common.json     → language en · namespace common6│  └─ checkout.json   → language en · namespace checkout7└─ fr/8   ├─ common.json     → language fr · namespace common9   └─ checkout.json   → language fr · namespace checkout

1# preview first — no writes, prints exactly what WOULD change2sonenta import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5sonenta import "./locales/**/*.json" 7✓ common · checkout   (en, fr)8  keys           312 created · 0 reused9  translations   624 created · 0 updated · 0 unchanged10  errors 0 · glossary 0 violations 12# non-standard layout? override the inference per file:13sonenta import strings.fr.json --language fr --namespace common

Bäume können verschachtelt oder flach sein — beide werden identisch importiert. --status legt den eingehenden Status fest (draft oder translated, Standard translated); --version zielt auf eine nicht standardmäßige Version. Pluralformen, die als CLDR-Dictionary ({ one, other }) ausgedrückt sind, werden automatisch als Pluralformen gespeichert.

3. Auf dem CDN veröffentlichen

Der Import füllt das Projekt; die Veröffentlichung macht es auslieferbar. Erstellen Sie ein Release, und die Bundles verbreiten sich auf dem globalen CDN, von dem das SDK liest.

1# cut a CDN release so the SDK and your build can fetch it2sonenta releases publish 4→ released "main" · propagating to cdn.sonenta.com

Releases sind unveränderliche Snapshots einer Version. Veröffentlichen Sie erneut, sobald Sie neue Inhalte importieren — sowohl das SDK als auch Ihr statischer Build holen sich das neueste Release.

4. Das Bundle verifizieren

Bestätigen Sie, dass der Inhalt live ist. Ein veröffentlichtes Bundle ist eine einfache, öffentliche JSON-Datei pro Sprache und Namespace — holen Sie eine direkt ab oder öffnen Sie das Projekt im Dashboard.

1# the published bundle is public — no auth needed2curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.json

Ein 404 bei einer Sprache? Sie gehört noch nicht zu den Sprachen des Projekts, oder das Release hat sich noch nicht verbreitet — warten Sie ein paar Sekunden und versuchen Sie es erneut.

5. Ihr SDK auf Sonenta ausrichten

Tauschen Sie Ihr i18next-Backend gegen den Sonenta-Provider aus. Ihre t()-Aufrufe, Ihre Schlüssel und Ihre Namespaces bleiben identisch — die Übersetzungen kommen jetzt aus dem CDN-Bundle, das Sie gerade veröffentlicht haben.

1// src/main.tsx — point @sonenta/react-i18next at the same project2import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5  projectUuid="<project_uuid>"6  token={import.meta.env.VITE_SONENTA_TOKEN}7  defaultLocale="fr"8  namespaces={["common", "checkout"]}9>10  <App />11</SonentaProvider>

Schlüssel, die Punkte enthalten (eine Version, ein Preis, eine Bibelstelle)? Setzen Sie keySeparator={false} und stellen Sie das Projekt auf flach um — siehe die Anleitung Flache oder verschachtelte Schlüssel. Andernfalls funktioniert der verschachtelte Standard ohne Weiteres.

Was der Importer übernimmt

• Verschachtelt oder flach. Beide JSON-Formen werden auf dieselben Schlüssel importiert — keine Vorverarbeitung.
• Pluralformen. CLDR-Plural-Dictionaries ({ one, other, … }, mit erforderlichem other) werden automatisch zu Plural-Schlüsseln.
• Resilienz pro Datei. Eine unbekannte Sprache oder ein unbekannter Namespace wird als Fehler pro Einheit gemeldet — der Rest des Imports gelingt trotzdem.
• Glossar-Prüfungen. Importierte Übersetzungen durchlaufen Ihr Glossar; Verstöße werden aufgelistet und bei strenger Durchsetzung übersprungen.
• Bereinigung fehlender Schlüssel. Offene Ereignisse über fehlende Schlüssel für die importierten Schlüssel werden aufgelöst, sobald die Werte eintreffen.