Schnellstart
Diese Seite führt ein einsprachiges Projekt zu seinen ersten übersetzten Dateien. Sie ist für eine JS/TS-App, eine Python-App, eine .NET-App, eine Website oder Dokumentationsseite oder eine Repository-README und andere Markdown-Dateien gedacht. Sie geht davon aus:
- Node.js
>=22.16.0, oder die eigenständige ausführbare Datei für ein Python- oder .NET-Projekt. - Ein API-Schlüssel für einen LLM-Anbieter oder eine lokale Ollama-Installation.
- Das Projekt befindet sich in der Versionskontrolle, damit Sie überprüfen können, was das Tool schreibt.
Zwei Dinge unterscheiden sich zwischen Projekten: wie das Tool Ihren Text findet und wie Ihre App das Ergebnis lädt. Wählen Sie Ihren Pfad unten führt Sie zum richtigen Leitfaden dafür.
Ausführbare Beispiele
Möchten Sie lieber zuerst ein fertiges Projekt ansehen? Kopieren Sie eines, ohne das Repository zu klonen:
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:syncErsetzen Sie console-app durch ein beliebiges anderes Node.js-Beispiel. Python- und .NET-Beispiele haben keine package.json; kopieren Sie sie auf die gleiche Weise. Die vier Python-Beispiele sind auch in ai-i18n-tools-python-examples.zip im GitHub Release enthalten, und die beiden .NET-Beispiele sind in ai-i18n-tools-dotnet-examples.zip. Die vollständige Liste, mit dem, was jedes Beispiel zeigt, finden Sie auf der Seite Beispiele.
Installieren
pnpm add -D ai-i18n-toolsnpm install --save-dev ai-i18n-tools und yarn add --dev ai-i18n-tools funktionieren ebenfalls. Python- und .NET-Projekte installieren die eigenständige ausführbare Datei und benötigen kein Node.js. Linux und macOS: curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash. Windows PowerShell: irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex. Weitere Installationsoptionen: Installation.
Anbieter und API-Schlüssel
Jeder Befehl, der ein LLM aufruft (translate-ui, translate-docs, translate-json, translate-svg und sync), benötigt beides:
- Mindestens ein Anbieter in
ai-i18n-tools.config.json: einproviders.<name>-Block mittranslationModelsund ein Top-Level-provider-Schlüssel, wenn mehr als ein Anbieter konfiguriert ist.init -P <provider>erstellt dieses Preset. Um Anbieter hinzuzufügen, siehe LLM-Anbieter. Um die Modellliste auszuwählen, siehe KI-Modelle. - Der passende API-Schlüssel in Ihrer Umgebung oder in
.env/.env.localnebenai-i18n-tools.config.json, wenn noch kein Anbieter-API-Schlüssel festgelegt ist. Jedes integrierte Preset liest eine benannte Variable aus der Preset-Tabelle, zum BeispielOPENROUTER_API_KEYmit-P openrouteroderOPENAI_API_KEYmit-P openai. Ollama verwendet einen lokalen Endpunkt und benötigt keinen Schlüssel.
export OPENROUTER_API_KEY=sk-or-v1-your-key-hereextract, status und andere Befehle, die das LLM nicht aufrufen, benötigen keines von beidem. Mehr zu Umgebungsdateien und PATH: Installation.
Wählen Sie Ihren Pfad
Finden Sie, was Sie haben, führen Sie die Befehle in seinem Block aus und fahren Sie dann im verlinkten Leitfaden fort.
Eine JS/TS-App
Ihre Schaltflächen und Nachrichten sind im Quelltext noch Klartext, daher hat das Tool noch nichts zu finden. Sie müssen zuerst in t() eingeschlossen werden, und die App benötigt eine kleine i18next-Setup-Datei.
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --applyFolgen Sie dann i18n zu einer JS/TS-App hinzufügen. Es behandelt den Wrapping-Schritt, mit einem Agent-Prompt, vor extract und translate-ui.
Eine Python-App
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --applyBefolgen Sie dann i18n zu einer Python-App hinzufügen.
Eine Django-App, Flask mit Flask-Babel-Katalogen oder eine App, die bereits gettext aufruft, behält diese Aufrufe bei. Erstellen Sie stattdessen ein Gerüst mit ui-python-django, ui-python-flask oder ui-python-gettext, und befolgen Sie dann i18n zu einer Django-/Python-gettext-App hinzufügen.
Eine .NET-App
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --applyFolgen Sie dann i18n zu einer .NET-App hinzufügen. Eine App, die bereits ResourceManager oder IStringLocalizer verwendet, nutzt stattdessen ui-dotnet-resx, dann i18n zu einer .NET ResourceManager-App hinzufügen. migrate-dotnet-i18n schreibt T($"…") in nummerierte {0}-Aufrufe um. --wrap prüft unmarkierte XAML- und C#-Bezeichnungen. Der Bericht listet benannte resx-Schlüssel, wie z.B. Resources.LoginButton, als Vorschläge auf und bearbeitet diese Zeilen nicht.
Eine Website oder Dokumentationsseite
Wählen Sie die Vorlage für Ihr Framework:
| Ihre Website | Vorlage |
|---|---|
| Astro Starlight | ui-starlight |
| Docusaurus | ui-docusaurus |
| VitePress | ui-vitepress |
| Nextra | ui-nextra |
| Fumadocs | ui-fumadocs |
| Einfache Astro-Website | ui-astro-website |
| Einfache HTML-Seiten | ui-plain-html oder docs-plain-html |
ai-i18n-tools init -t ui-vitepress -P openrouterBefolgen Sie dann i18n zu einer Website oder Dokumentationsseite hinzufügen. Die Eingabeaufforderung des Agenten aktiviert das i18n-Routing des Frameworks. Sie führen sync aus, nachdem Sie diese Arbeit überprüft haben.
Eine README- oder Markdown-Dokumentation
Die meisten Repositories möchten dies zusammen mit der App: Die Standardvorlage ui-markdown enthält bereits einen flachen README-Block. Für jede andere Vorlage fügen Sie --with-readme hinzu. Ein Repository, das nur Markdown verwendet, nutzt docs-markdown.
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouterFolgen Sie dann i18n zu Ihrer README und Markdown-Dokumentation hinzufügen. Fügen Sie den Sprachlisten-Marker in README.md vor sync ein. Der App-Pfad, falls vorhanden, ist weiterhin i18n zu einer JS/TS-App hinzufügen, i18n zu einer Python-App hinzufügen oder i18n zu einer .NET-App hinzufügen.
Etwas anderes
- Verschachteltes i18next-JSON, das unverändert bleibt:
ai-i18n-tools init -t ui-json-bundles -P openrouter, dann JSON. - SVG-Diagramme mit Textbeschriftungen: SVG-Übersetzung.
- Umstieg von Intlayer: Migration von Intlayer.
- Intlayer beibehalten und nur die Übersetzungen ausfüllen: Intlayer vor Ort übersetzen.
Die vollständige Vorlagenliste mit jeder init-Option finden Sie in der CLI-Setup-Referenz.
Ausführen und überprüfen
Wenn Ihr Projekt bereit ist:
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools statusdoctor prüft, ob die Konfiguration, Pfade, Provider und Umgebung bereit sind. Es überprüft auch Modell-IDs mit dem Provider, es sei denn, Sie übergeben --local. sync führt jeden Schritt aus, den Ihre Konfiguration aktiviert, und zwar der Reihe nach. status zeigt an, was pro Gebietsschema übersetzt wurde. Ein erster Durchlauf bei einem Projekt, in dem das Tool keinen Text erkennen kann, endet fehlerfrei und schreibt nichts Nützliches. Wenn also status keine Zeichenfolgen anzeigt, kehren Sie zum Leitfaden für Ihren Pfad zurück.
suggest-models stuft die Chat-Modelle des aktiven Anbieters anhand veröffentlichter Benchmarks ein. suggest-models --apply ersetzt translationModels und lässt uiModels und localeModels unverändert. Dasselbe Ranking befindet sich auf dem Dashboard auf dem Tab Modelle. Wie das Ranking funktioniert und warum die Liste mehr als ein Modell enthält: KI-Modelle. Befehlsreferenz: suggest-models.
Übersetzt halten
Führen Sie sync erneut aus, wann immer sich der Quelltext ändert. Ein SQLite-Cache bedeutet, dass nur neuer oder geänderter Text an das Modell gesendet wird, sodass erneute Ausführungen kostengünstig sind. Das Ausführen von sync in CI verhindert, dass Übersetzungen abweichen. ai-i18n-tools dashboard öffnet das Übersetzungs-Dashboard, um zwischengespeicherte Übersetzungen zu überprüfen und zu bearbeiten.
Empfohlene package.json-Skripte
Wenn das Paket lokal installiert ist, lösen Skripte ai-i18n-tools aus node_modules/.bin ohne zusätzliche Shell-Einrichtung auf. Für eine interaktive Shell konfigurieren Sie zuerst PATH: siehe Verwenden der CLI.
{
"i18n:extract": "ai-i18n-tools extract",
"i18n:sync": "ai-i18n-tools sync",
"i18n:translate:ui": "ai-i18n-tools translate-ui",
"i18n:translate:svg": "ai-i18n-tools translate-svg",
"i18n:translate:docs": "ai-i18n-tools translate-docs",
"i18n:translate:json": "ai-i18n-tools translate-json",
"i18n:status": "ai-i18n-tools status",
"i18n:statistics": "ai-i18n-tools statistics",
"i18n:dashboard": "ai-i18n-tools dashboard",
"i18n:cleanup": "ai-i18n-tools cleanup"
}Bevorzugen Sie sync gegenüber dem Verketten der einzelnen Übersetzungs-Skripte. Verwenden Sie die Einzelschritt-Skripte nur, wenn Sie einen Schritt isoliert benötigen.
Um die CLI-Ausgabe und das Dashboard in einer anderen Sprache anzuzeigen, übergeben Sie -L <code> oder legen Sie AI_I18N_LANG fest: siehe Sprache der Tool-Benutzeroberfläche.
Übersetzen Sie mehr als eine Art von Inhalt, wie z. B. App-Strings und eine Dokumentations-Website zusammen? Siehe Pipelines kombinieren.
Weiter: die Anleitung für Ihren Pfad unter Wählen Sie Ihren Pfad.