i18n-Experte
Überblick
Liefern Sie ein vollständiges i18n-Setup und einen Audit-Durchlauf: Konfigurieren Sie das i18n-Framework, ersetzen Sie benutzerseitige Zeichenfolgen durch Schlüssel, stellen Sie die Locales-Parität sicher und validieren Sie Pluralisierung/Formatierung für en-US und zh-CN.
Kernfähigkeiten
- Bibliotheksauswahl und Einrichtung (React, Next.js, Vue).
- Schlüsselarchitektur und Organisation der Locale-Dateien.
- Übersetzungsgenerierung und Qualitätsstrategie (KI, professionell, manuell).
- Routing und Spracherkennung/-umschaltung.
- SEO- und Metadatenlokalisierung (falls zutreffend).
- RTL-Unterstützung (nur wenn RTL-Locales im Umfang enthalten sind).
Umfangseingaben (bei Unklarheiten nachfragen)
- Framework und Routing-Stil.
- Vorhandener i18n-Status (keine, teilweise, Legacy).
- Ziel-Locales (Standard: en-US + zh-CN).
- Anforderungen an die Übersetzungsqualität (KI vs. professionell vs. manuell).
- Locale-Formate in Verwendung (JSON, YAML, PO, XLIFF).
- Formalitäts-/kulturelle Anforderungen (falls vorhanden).
Arbeitsablauf (Audit -> Beheben -> Validieren)
- Umfang und Locale-Ziele bestätigen
- Identifizieren Sie das i18n-Framework und die Locale-Speicherorte.
- Bestätigen Sie die Locales; standardmäßig en-US + zh-CN, wenn angegeben.
- i18n-Baseline einrichten (falls fehlend)
- Wählen Sie eine zum Framework passende Bibliothek (z.B. React: react-i18next; Next.js: next-intl; Vue: vue-i18n).
- Installieren Sie Pakete und erstellen Sie die i18n-Einstiegs-/Konfigurationsdatei.
- Verdrahten Sie den Provider auf der App-Wurzel und laden Sie die Locale-Ressourcen.
- Fügen Sie einen Sprachumschalter und Persistenz (Route/Param/localStorage) nach Bedarf hinzu.
- Legen Sie das Locale-Datei-Layout und die Schlüssel-Namespaces fest.
- Wenn das Routing Locale-bewusst ist, definieren Sie die Locale-Segment-Strategie frühzeitig (Unterpfad, Subdomain, Query-Parameter).
- Wenn Metadaten benutzerseitig sind, fügen Sie Übersetzungen für Titel/Beschreibungen hinzu.
- Schlüsselverwendung und Locale-Parität prüfen
- Führen Sie aus:
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json> - Behandeln Sie fehlende Schlüssel/Paritätslücken als Blockierer.
- Überprüfen Sie manuell dynamische Schlüssel (
t(var)).
- Rohe benutzerseitige Zeichenfolgen finden
- Suchen:
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<" rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\"" - Lokalisieren Sie Accessibility-Labels.
- Zeichenfolgen durch Schlüssel ersetzen
- Verwenden Sie
t('namespace.key')für UI-Text. - Für Pluralformen verwenden Sie
t('key', { count })+_one/_other-Schlüssel. - Verwenden Sie Intl/App-Formatierer für Zeit/Datum/Zahl.
- Fehlerbehandlung lokalisieren (kritisch)
- Ordnen Sie Fehlercodes lokalisierten Schlüsseln zu; zeigen Sie nur lokalisierte UI an.
- Protokollieren Sie nur rohe Fehlerdetails.
- Stellen Sie einen lokalisierten Fallback für unbekannte Codes bereit.
- Locale-Dateien aktualisieren
- Fügen Sie fehlende Schlüssel in beiden Locales hinzu.
- Halten Sie Platzhalter konsistent; vermeiden Sie Umbenennungen, es sei denn, sie werden angefordert.
- Generieren Sie Übersetzungen mit der vereinbarten Methode; bewahren Sie Platzhalter und Pluralregeln.
- Validieren
- Führen Sie das Audit erneut durch, bis keine fehlenden/Paritätsprobleme mehr vorhanden sind.
- Validieren Sie JSON (z.B.
python -m json.tool <file>). - Aktualisieren Sie Tests, die sichtbaren Text bestätigen.
Schutzmaßnahmen
- Geben Sie niemals rohe
error.messagein der UI aus; zeigen Sie nur lokalisierte Zeichenfolgen an. - Fügen Sie keine zusätzlichen Locales hinzu, es sei denn, sie werden ausdrücklich angefordert.
- Bevorzugen Sie strukturierte Namespaces (z.B.
errors.*,buttons.*,workspace.*). - Halten Sie Übersetzungen präzise und konsistent.
- Einige technische/ Markenbegriffe sollten unübersetzt bleiben (z.B. Produktname, API, MCP, Bash).
Liefergegenstände (erwartete Ausgaben)
- i18n-Konfiguration/Provider-Verdrahtung.
- Locale-Dateien für jede Zielsprache.
- Ersetzte UI-Zeichenfolgen mit stabilen Schlüsseln.
- Sprachumschalter und Persistenz (falls zutreffend).
- Aktualisierte Tests für sichtbaren Text.
Architekturanleitung (kurz halten)
- Schlüsselstruktur: Bevorzugen Sie verschachtelte Namespaces nach Bereich (z.B.
common.buttons.save,pricing.tier.pro). - Dateilayout: Eine Datei pro Locale oder pro Locale-Namespace; halten Sie Schlüssel über Locales hinweg synchron.
- Platzhalter: Bewahren Sie
{name}/{{name}}genau; validieren Sie Pluralformen nach Locale-Regeln. - Formatierung: Verwenden Sie Intl/App-Helfer für Datums-, Zeit-, Zahlen- und Listenformatierung.
- SEO/Metadaten: Lokalisieren Sie Titel und Beschreibungen, wenn die App sie bereitstellt.
- RTL: Nur für RTL-Locales erforderlich; verwenden Sie logische CSS-Eigenschaften und testen Sie das Layout.
- Nicht-Web-Oberflächen (Electron-Hauptprozess-Dialoge, CLI-Eingabeaufforderungen, native Menüs) benötigen ebenfalls Lokalisierung.
Leistungshinweise (kurz)
- Laden Sie Locale-Bundles lazy, wenn die App dies unterstützt.
- Teilen Sie große Locale-Dateien nach Namespace auf.
Fehlermodi (Überwachungsliste)
- Fehlende Übersetzungen: Fallback auf das Standard-Locale und Protokollierung von Warnungen.
- RTL-Layoutprobleme: Überprüfen Sie logisches CSS und testen Sie Seiten.
- Fehlendes SEO: Stellen Sie sicher, dass Alternativen und Metadaten bei Bedarf lokalisiert werden.
Validierungs-Checkliste (kurz)
- Keine fehlenden Schlüssel und keine rohen UI-Zeichenfolgen.
- Sprachumschaltung funktioniert und bleibt erhalten.
- Pluralformen und Formatierung in beiden Locales überprüft.
- Fallback-Locale konfiguriert.
Ressourcen
scripts/
scripts/i18n_audit.py: Extrahiert die Verwendung vont('key')und vergleicht sie mit den JSON-Locale-Dateien.
Aktivierungsauslöser
Zuordnung von Fehlercodes zu lokalisierten Meldungen sowie Validierung der Schlüsselparität, Pluralisierung und Formatierung.