Benutzeroberflächen-Strings
Referenz für extract und translate-ui, die Pipeline, die t()-Aufrufe in sprachspezifische Kataloge umwandelt. Fügen Sie einer App zum ersten Mal i18n hinzu? Beginnen Sie bei i18n zu einer JS/TS-App hinzufügen, i18n zu einer Python-App hinzufügen oder i18n zu einer .NET-App hinzufügen. Sie behandeln den Wrapping-Schritt und leiten Sie dann für die Schritte 2 bis 4 hierher zurück.
Diese Pipeline unterstützt JS/TS-Projekte (React, Next.js Client- und Serverkomponenten, Node.js-Dienste, reines HTML, Astro-Websites und CLI-Tools), Python-Anwendungen und .NET-Anwendungen. JS/TS sucht Strings mit i18next, nachdem der Quellcode t() aufruft. Python ruft t() oder gettext über ein generiertes i18n.py auf (Django behält Djangos gettext). .NET ruft T() über ein generiertes I18n.cs auf.
Welchen Leitfaden Sie lesen sollten
| Ihre App | Als Nächstes lesen |
|---|---|
JS/TS mit hartcodierten Quelltexten, noch kein t() | i18n zu einer JS/TS-App hinzufügen |
React / Next.js / Node, t() bereits im Quellcode | i18next einbinden |
Python (t(), _(), gettext, Jinja, Django) | Python-Anwendungen. Initialisierung: ui-python, ui-python-gettext, ui-python-flask oder ui-python-django. Hilfsprogramm: i18n.py. Um Lokalisierungen zu einer bestehenden Anwendung hinzuzufügen, siehe i18n zu einer Python-Anwendung hinzufügen, oder i18n zu einer Django-/Python-gettext-Anwendung hinzufügen wenn die Anwendung gettext verwendet. |
.NET (T(), Tn, Tp, XAML loc:Tr) | .NET-Anwendungen. Initialisierung: ui-dotnet (I18n.cs) oder ui-dotnet-resx (i18n zu einer .NET ResourceManager-App hinzufügen). Um einer bestehenden App Lokalisierungen hinzuzufügen, siehe i18n zu einer .NET-App hinzufügen. |
Reines HTML (kein t() im Markup) | Reine HTML-Apps |
| Astro Marketing-Website (hybrid) | Astro-Website |
t()-Regeln, Interpolation, Plurale | t()-Aufrufe & Plurale |
| Sprachauswahl / RTL | Sprachumschalter & RTL |
| Laufzeit-API-Signaturen | Laufzeit-Helfer |
Intlayer .content.ts-Wörterbücher, Umstieg von Intlayer | Migration von Intlayer |
Intlayer .content.ts-Wörterbücher, Intlayer beibehalten | Intlayer direkt übersetzen |
Schritt 1: Initialisieren
ai-i18n-tools init -P openrouterDies schreibt ai-i18n-tools.config.json mit der ui-markdown-Vorlage (einschließlich des provider- / providers-Blocks für dieses Preset). Diese Vorlage aktiviert auch die Dokumentübersetzung für README.md, die als flache Dateien unter translated-docs/ geschrieben werden. Nur-README-Repositories verwenden stattdessen init -t docs-markdown. Siehe i18n zu Ihrem README und Markdown-Dokumenten hinzufügen. Bevor Sie translate-ui oder sync ausführen, legen Sie den API-Schlüssel für diesen Anbieter in der Umgebung oder in .env fest – Ollama ausgenommen; siehe Anbieter und API-Schlüssel. Vier Schlüssel sind für UI-Zeichenfolgen wichtig:
sourceLocale: der BCP-47-Code der Sprache, in der Ihr Quelltext geschrieben ist. Jede Sprache ist gültig;"en-GB"ist nur ein Beispiel. Er muss mitSOURCE_LOCALEübereinstimmen, das aus Ihrer Laufzeit-i18n-Setup-Datei (src/i18n.ts/src/i18n.js) exportiert wird. Die Zeichenfolge innerhalb vont()ist diese Quellsprache, und flache Lokalisierungsdateien verwenden sie als Schlüssel.targetLocales: BCP-47-Codes für Ihre Zielsprachen (zum Beispiel["de", "fr", "pt-BR"]). Führen Siegenerate-ui-languagesaus, um dasui-languages.json-Manifest aus dieser Liste zu erstellen.ui.sourceRoots: Verzeichnisse oder Glob-Muster, die nacht("…")-Aufrufen durchsucht werden sollen (zum Beispiel["src/"]).ui.stringsJsonundui.flatOutputDir: wo der Masterkatalog und die sprachspezifischen Dateien (de.json,pt-BR.json) geschrieben werden.
Jeder andere Schlüssel, einschließlich providers.<active>.uiModels, ist in Konfiguration.
Schritt 2: Zeichenfolgen extrahieren
extract tut nichts Nützliches, solange diese t()- / i18n.t()-Aufrufe nicht existieren. Umschließen Sie zuerst hartcodierten Text: i18n zu einer JS/TS-App hinzufügen.
ai-i18n-tools extractDurchsucht Dateien unter ui.sourceRoots nach t("literal")- und i18n.t("literal")-Aufrufen. Schreibt (oder führt zusammen in) ui.stringsJson.
Der Scanner ist konfigurierbar: Fügen Sie benutzerdefinierte Funktionsnamen über ui.uiExtractor.funcNames (oder das ältere ui.reactExtractor.funcNames) hinzu. Für Astro-Seiten und -Komponenten fügen Sie .astro zu ui.uiExtractor.extensions hinzu. Für reines HTML siehe Reine HTML-Apps.
Was sind Extrakt-Scans
- Standarderweiterungen sind nur
.js,.jsx,.tsund.tsx..mjs,.cjs,.mtsund.ctswerden nur eingeschlossen, wenn Sie sie zuui.uiExtractor.extensionshinzufügen. - Ein nicht-literaler Schlüssel wie
t(variable)oder ein Template-Literal wird ohne Warnung übersprungen. package.jsondescriptionist standardmäßig enthalten (ui.uiExtractor.includePackageDescription).- Vue- und Svelte-Single-File-Komponenten werden nicht unterstützt. Das Hinzufügen von
.vueoder.sveltezuextensionsextrahiert keinen Vorlagentext. Es gibt keinen SFC-Parser.
Schritt 3: UI-Zeichenfolgen übersetzen
ai-i18n-tools translate-uiLiest strings.json, sendet Batches an die Modelle des aktiven LLM-Anbieters für jedes Ziellokal, schreibt flache JSON-Dateien (de.json, fr.json usw.) nach ui.flatOutputDir. Die Modellauswahl verwendet die UI-Kette: localeModels(locale) → uiModels → translationModels (siehe KI-Modelle). Innerhalb eines Lokals laufen bis zu uiBatchConcurrency Batches gleichzeitig (Standard 2; siehe Konfiguration — uiBatchConcurrency). -j parallelisiert weiterhin nur Ziellokale. Jeder erfolgreiche Batch wird in strings.json und die flache Lokaldaten-Datei geschrieben, bevor der nächste Batch startet, sodass das Beenden des Laufs oder ein späterer API-Fehler die bereits abgeschlossenen Batches beibehält.
Übersetzungsdatenbank (strings.json)
Für jeden Eintrag speichert translate-ui die Modell-ID des aktiven Anbieters, der jede Sprache erfolgreich übersetzt hat, in einem optionalen models-Objekt (dieselben Sprachschlüssel wie translated). Im Übersetzungs-Dashboard bearbeitete Zeichenfolgen werden mit dem Sentinel-Wert user-edited in models für diese Sprache markiert. Die sprachspezifischen Flatfiles unter ui.flatOutputDir bleiben nur Quellzeichenfolge → Übersetzung; sie enthalten keine models (sodass Laufzeit-Bundles unverändert bleiben).
Hinweis: Dashboard-Bearbeitungen an UI-Strings befinden sich in
strings.json, nicht im SQLite-Dokumentations-Cache. Führen Siesyncodertranslate-ui(ohne spezielles Flag) aus, um flache Lokalisierungsdateien aus dem Katalog neu zu schreiben —--force-updatewird nicht an den UI-Schritt weitergeleitet. Vermeiden Sie--forcebei UI-Befehlen nach manuellen Bearbeitungen: Es übersetzt jeden Eintrag neu und kann Ihreuser-edited-Zeilen überschreiben. Katalogzeilen, deren gespeicherte Übersetzung die Überprüfung des Schreibsystems der Lokalisierung nicht besteht (zum Beispiel romanisiertes Hindi fürhi), werden als fehlend behandelt und ohne--forceneu übersetzt.
Schritt 4: Die Ausgabe in Ihrer App verwenden
translate-ui schreibt nur Dateien. Die App muss sie laden.
- JS/TS: i18next mit den Laufzeit-Helfern einrichten, die vom Benutzer ausgewählte Lokalisierungsdatei laden und einen Sprachumschalter hinzufügen. Siehe i18next einbinden und Sprachumschalter und RTL.
- Python: das generierte
i18n.pyoder Ihre gettext-Kataloge verwenden. Siehe Python-Anwendungen. - .NET: das generierte
I18n.csverwenden oderI18nResx.cs, wenn die App bereitsResourceManagerverwendet. Siehe .NET-Anwendungen und i18n zu einer .NET ResourceManager-App hinzufügen.migrate-dotnet-i18nschreibt unsichereT()-Argumente um.--wrapprüft unmarkierte Labels. - Reines HTML: das Laufzeitskript neben der Seite laden. Siehe Apps mit reinem HTML.
- Astro: siehe Astro-Website.
Optional
Modellüberschreibungen pro Gebietsschema
Einige Modelle übersetzen bestimmte Sprachen besser als andere. Zum Beispiel eignen sich qwen- und z-ai-Modelle oft gut für asiatische Sprachen. Fügen Sie providers.<active>.localeModels-Einträge hinzu, um eine priorisierte Modellliste für jede BCP-47-Lokalisierung anzugeben. Diese Listen werden vor uiModels und translationModels für diese Lokalisierung versucht. Lokalisierungs-Tags stimmen unabhängig von der Groß-/Kleinschreibung überein (zh-cn und ZH-CN sind äquivalent). Ohne passenden Eintrag verwendet das Tool die Standardreihenfolge von uiModels und translationModels. Derselbe localeModels-Mechanismus gilt für die Dokument-, JSON- und SVG-Übersetzung.
Exportieren nach XLIFF 2.0
Um UI-Zeichenketten an einen Übersetzungsdienstleister, ein TMS oder ein CAT-Tool weiterzugeben, exportieren Sie den Katalog als XLIFF 2.0 (eine Datei pro Zielsprachgebiet). Dieser Befehl ist schreibgeschützt: Er verändert strings.json nicht und ruft keine API auf.
ai-i18n-tools export-ui-xliffStandardmäßig werden die Dateien neben ui.stringsJson abgelegt, mit Namen wie strings.de.xliff, strings.pt-BR.xliff (Basisname Ihres Katalogs + Sprachgebiet + .xliff). Verwenden Sie -o / --output-dir, um an anderer Stelle zu schreiben. Vorhandene Übersetzungen aus strings.json erscheinen in <target>; fehlende Sprachgebiete verwenden state="initial" ohne <target>, sodass Tools diese ergänzen können. Verwenden Sie --untranslated-only, um nur Einheiten zu exportieren, die für jedes Sprachgebiet noch übersetzt werden müssen (nützlich für Aufträge an Dienstleister). --dry-run gibt Pfade aus, ohne Dateien zu schreiben.