Migration von Intlayer zu Quellstring-Aufrufen
Intlayer ist ideal für Anwendungen, die Übersetzungen über typisierte Content-Wörterbücher oder Übersetzungsmanagement-Systeme verwalten. ai-i18n-tools zielt auf einen anderen Workflow ab: Code, der Quellstring-Aufrufe wie t('English source') verwendet. Der String in t() ist in sourceLocale geschrieben, was jede beliebige Sprache sein kann. Englisch in diesen Beispielen ist nur ein Beispiel. Durch das direkte Beibehalten dieses Quellstrings im Code vereinfacht dieser Ansatz die Wartung und reduziert die Komplexität. Wenn dieses Modell Ihren Anforderungen entspricht, importiert migrate-intlayer Ihre bestehenden Wörterbücher und schreibt kompatible Aufrufstellen automatisch um. Es lässt verbleibende Stellen unverändert und generiert einen Bericht mit spezifischen Ersetzungsanweisungen, wodurch Sie die Migration in Etappen abschließen oder den Bericht einem KI-Codierungsagenten übergeben können, um die Migration für Sie abzuschließen.
Verwenden Sie bereits i18next-JSON-Übersetzungsdateien? Dann benötigen Sie diesen Migrationsbefehl nicht; verwenden Sie stattdessen die JSON-Pipeline.
Direkt übersetzen oder migrieren?
Diese Seite migriert Ihre App von Intlayer auf die Quellstring-t()-Aufrufe von ai-i18n-tools, wie z. B. t('English source'). Der String ist in sourceLocale geschrieben, was jede beliebige Sprache sein kann. Wenn Sie Intlayer zur Laufzeit beibehalten und nur die fehlenden Übersetzungen ergänzen möchten, verwenden Sie stattdessen translate-intlayer – es übersetzt die *.content.ts direkt.
Was migrate-intlayer macht
- Parst
*.content.tsStandard-Exports (key+content+t({ locale: '…' })Blätter). - Befüllt
ui.stringsJsonund Locale-Dateien unterui.flatOutputDirmit dem Text der Quellsprache und allen bereits im Wörterbuch vorhandenen Übersetzungen. Importierte Zeilen haben keinmodels-Feld (sie wurden bei diesem Durchlauf nicht maschinell übersetzt). - Schreibt sichere Aufrufstellen um:
binding.path.to.leaf.value→t('English source')binding.path.value.replace('{token}', expr)→t('English {{token}}', { token: expr })
- Lässt alles andere (dynamische Schlüssel, JSX-Spreads, verkettete
.replace().replace(), Destructuring) unverändert. Der Bericht listet jede dieser Stellen mit dem genauen Ausdruck, einer konkretent()- oder JSX-Ersetzung und der hinzuzufügendenimport { t } from '…';-Zeile auf. - Standardmäßig ein Dry-Run. Übergeben Sie
--write, um die Katalog-Initialisierung und sichere Umschreibungen anzuwenden. Der Bericht wird immer geschrieben. Er listet auch Wörterbuchdateien und die verbleibende Verwendung vonuseIntlayer/IntlayerProviderauf, die nach den manuellen Umschreibungen gelöscht werden müssen, Katalogschlüssel, die nochextractund danntranslate-uibenötigen, sowie ein Runtime-Bootstrap zum Einfügen in das i18n-Modul der App.
Projekt migrieren
Installieren Sie
ai-i18n-tools(siehe Installation). Falls Ihr Projekt noch keineai-i18n-tools.config.jsonbesitzt, erstellen Sie eine:bashai-i18n-tools init -P gemini
Passen Sie sourceLocale und targetLocales an die Locales an, die bereits in Ihren Intlayer-Wörterbüchern vorhanden sind, und legen Sie ui.sourceRoots, ui.stringsJson und ui.flatOutputDir so fest, dass sie auf die Quell- und gewünschten Katalogpfade Ihrer App verweisen — dieselben Schlüssel, die translate-ui verwendet, siehe UI-Strings — Schritt 1: Initialisieren. 2. Zunächst ein Probelauf: ai-i18n-tools migrate-intlayer (ohne --write). Lesen Sie migrate-intlayer-report.md, um zu sehen, was gefunden wird und welche Aufrufstellen vor etwaigen Dateiänderungen einer manuellen Überprüfung bedürfen. 3. Führen Sie ai-i18n-tools migrate-intlayer --write aus, um ui.stringsJson / ui.flatOutputDir zu befüllen und die unbedenklichen Aufrufstellen umzuschreiben. 4. Übergeben Sie den neu generierten Bericht migrate-intlayer-report.md an einen KI-Coding-Agenten (empfohlen) oder arbeiten Sie ihn selbst ab, indem Sie diesen Schritten folgen:
- Der Bericht endet mit einem Schritt-für-Schritt-TODO: Schließen Sie die Bearbeitung jeder manuell zu prüfenden Aufrufstelle mit dem dort gezeigten konkreten
t('…')/JSX ab, fügen Sie dieimport { t } from '…';-Zeile hinzu und löschen Sie dann die übrig gebliebenen*.content.ts-Dateien sowie die im Bericht aufgelistete Verwendung vonuseIntlayer/IntlayerProvider.- Überschreiben Sie das i18n-Modul Ihrer App mit dem Runtime-Bootstrap aus dem Bericht. Rufen Sie in der Locale-Steuerung
loadLocale(next)und danni18n.changeLanguage(next)auf —loadLocaleregistriert nur das Flat-Bundle und wechselt nicht die aktive Sprache. - Führen Sie
ai-i18n-tools extractund dannai-i18n-tools translate-ui(odersync) für alle Quellstrings aus, die im Bericht als neu markiert sind.extractschreibt auchui-languages.json, was vom Bootstrap importiert wird; führen Sie es also vor dem Starten der App aus, selbst wenn kein neuer String hinzugefügt wurde. Bearbeiten Siestrings.json, die flachen Locale-Dateien oderui-languages.jsonnicht manuell — diese Befehle verwalten sie. - Sobald die Cleanup-Liste des Berichts abgearbeitet ist und die App auf ai-i18n-tools läuft, entfernen Sie die
intlayer- /react-intlayer-Abhängigkeiten und die Wörterbuchdateien.
- Überschreiben Sie das i18n-Modul Ihrer App mit dem Runtime-Bootstrap aus dem Bericht. Rufen Sie in der Locale-Steuerung
Beispiel ausführen
Die obigen Schritte gelten für jedes Intlayer-Projekt. Das Beispiel intlayer-migration führt sie an einer kleinen Vite + React-App mit einfachen (automatisch umschreibbaren) und komplexen (manuell zu überprüfenden) Fällen durch, sodass Sie den Bericht und den Runtime-Bootstrap sehen können, bevor Sie es mit Ihrem eigenen Code versuchen. intlayer-pristine/ wird niemals geändert; src/ ist die Arbeitskopie.
npx degit wsj-br/ai-i18n-tools/examples/intlayer-migration intlayer-migration
cd intlayer-migration
pnpm install
pnpm reset
pnpm migrate:dry
pnpm migrate:writeÜbergeben Sie migrate-intlayer-report.md an einen KI-Coding-Agenten (oder bearbeiten Sie die markierten Dateien selbst). Der Bericht enthält das Runtime-Modul zum Einfügen in src/i18n.ts. Rufen Sie in der Locale-Steuerung loadLocale(next) und dann i18n.changeLanguage(next) auf. loadLocale registriert nur das Flat-Bundle.
pnpm i18n:sync
pnpm devpnpm i18n:sync führt zuerst extract aus, wodurch ui-languages.json erstellt wird. Der Bootstrap importiert diese Datei, starten Sie die App daher erst nach der Extraktion. Bearbeiten Sie strings.json, die flachen Locale-Dateien oder ui-languages.json nicht manuell.
pnpm reset kopiert intlayer-pristine/ zurück über src/ und löscht generierte Kataloge, damit Sie von vorne beginnen können.
Vollständige Anleitung: examples/intlayer-migration/README.md.
Befehl
ai-i18n-tools migrate-intlayer [paths...] [--write] [--report <path>] [--content-glob <glob>] [--t-import <specifier>]Erfordert ui.stringsJson und ui.flatOutputDir in der Konfiguration (wie translate-ui). Ruft kein LLM auf.
| Option | Bedeutung |
|---|---|
[paths...] | Zu scannende Dateien/Verzeichnisse/Globs (Standard: ui.sourceRoots) |
--write | Katalog füllen und sichere Aufrufstellen umschreiben (Standard: Trockenlauf) |
--report <path> | Berichtspfad (Standard: migrate-intlayer-report.md) |
--content-glob <glob> | Wörterbuch-Dateinamen-Glob (Standard: **/*.content.ts) |
--t-import <specifier> | Import-Spezifizierer für generiertes t() (Standard: relatives ./i18n, falls src/i18n.ts existiert, ansonsten i18next) |
Nach --write schließen Sie die manuelle Überprüfung der im Bericht aufgeführten Sites ab, löschen Sie die ungenutzten *.content.ts-Dateien und den im Bericht aufgelisteten IntlayerProvider-Wrapper, fügen Sie den Runtime-Bootstrap ein und rufen Sie i18n.changeLanguage aus der Locale-Steuerung auf. Führen Sie extract und anschließend translate-ui (oder sync) für die Quellstrings aus, die im Bericht als neu markiert sind. extract erstellt zudem ui-languages.json, die vom Bootstrap importiert wird. Bearbeiten Sie strings.json, die flachen Locale-Dateien oder ui-languages.json nicht manuell.
Siehe auch: CLI – UI-Zeichenfolgen, i18next verdrahten