Weiter zum Hauptinhalt

Übersetzungs-Wartungsworkflow

Für allgemeine Dokumentationsbefehle (Erstellen, Bereitstellen, Screenshots, README-Generierung) siehe Dokumentationstools.

Übersicht​

Die Dokumentation verwendet Docusaurus i18n mit Englisch als Standard-Gebietsschema. Die Quelldokumentation befindet sich in docs/; Übersetzungen werden unter i18n/{locale}/ erstellt. Unterstützte Gebietsschemas: en-GB (Standard), fr, de, es, pt-BR, hi, zh-Hans.

KI-Übersetzung für die App-Benutzeroberfläche, Docusaurus Markdown/JSON, SVG-Assets und Standard-Benachrichtigungsvorlagen wird von ai-i18n-tools aus der Repository-Wurzel behandelt, konfiguriert in ai-i18n-tools.config.json (nicht innerhalb von documentation/). Legen Sie OPENROUTER_API_KEY fest, wenn Sie Übersetzungsbefehle ausführen.

Um einen unveröffentlichten Checkout auf derselben Maschine zu testen (Standard ../ai-i18n-tools), wechseln Sie die Abhängigkeit mit pnpm i18n:tools --local oder ./scripts/link-ai-i18n-tools.sh --local. Dadurch werden sowohl die CLI (pnpm i18n:*) als auch der ai-i18n-tools/runtime-Import verknüpft. Erstellen Sie das Tools-Paket nach Quelländerungen neu (pnpm build in diesem Checkout). Stellen Sie das neueste npm-Paket mit --remote wieder her. Committen Sie nicht den link:-Spezifikator.

Wann sich die englische Dokumentation ändert​

  1. Quelle bearbeiten in documentation/docs/ (nur Englisch). Text der Landingpage ist documentation/src/landing/landing.html.
  2. Docusaurus-UI-Zeichenfolgen (Design-Labels, Navigationsleiste usw.): Führen Sie bei Bedarf pnpm write-translations in documentation/ aus, damit i18n/en/*.json neue Schlüssel übernimmt.
  3. Überschriften-IDs: pnpm write-heading-ids (aus documentation/).
  4. Übersetzen aus dem Repo-Root (oder verwenden Sie die folgenden Tastenkürzel aus documentation/):
    • pnpm i18n:extract — src/locales/strings.json aus t('…') in der Next.js-App aktualisieren.
    • pnpm i18n:translate:docs — Markdown, Docusaurus-Shell-JSON und das Landing-HTML gemäß Konfiguration nach documentation/i18n/ und documentation/src/landing/i18n/ übersetzen.
    • pnpm i18n:translate:svg — SVGs unter documentation/static/img wie konfiguriert übersetzen.
    • pnpm i18n:translate:json — Standard-Benachrichtigungsvorlagen in src/locales/templates/ aus en-GB.json übersetzen.
    • Oder alles ausführen: pnpm i18n:translate.
  5. Erstellen: cd documentation && pnpm build (alle Gebietsschemas).

Innerhalb von documentation/ sind dieselben Abläufe wie pnpm translate → Wurzel i18n:translate verdrahtet, zusätzlich pnpm translate:docs, translate:ui, translate:svg, translate:status, i18n:extract, i18n:sync.

UI-Pluralformen​

Kardinal-Pluralformen in der Next.js-App verwenden ai-i18n-tools, keine manuell geschriebenen _one / _other-Schlüssel.

Schreiben Sie eine englische Quellzeichenfolge (normalerweise die Pluralform) und übergeben Sie ein einfaches Objekt-Literal mit plurals: true und einer numerischen count:

t("{{count}} backups selected", { plurals: true, count: selectedBackups.size })

Regeln:

  • Verwenden Sie keine item(s)-Unsicherheiten oder count === 1 ? t('…') : t('…')-Paare.
  • Unabhängige numerische Zählungen benötigen separate t()-Aufrufe — eine Pluralachse kann nicht zwei Zahlen flexibel anpassen (zum Beispiel 1 erfolgreich und 2 fehlgeschlagen). Verketten Sie die Fragmente:
`${t("Tested {{count}} connections:", { plurals: true, count: total })} ` +
  `${t("{{count}} successful,", { plurals: true, count: successCount })} ` +
  `${t("{{count}} failed", { plurals: true, count: failureCount })}`
  • Nicht-numerische Interpolationen (Namen, Bezeichnungen usw.) sind in derselben Pluralzeichenfolge wie {{count}} zulässig.
  • pnpm i18n:extract markiert die Katalogzeile "plural": true. pnpm i18n:translate:ui füllt CLDR-Formen aus und schreibt src/locales/en-GB.json (nur Pluralschlüssel).
  • src/i18n.ts und src/lib/i18n-server.ts laden diese Datei als sourcePluralFlatBundle, sodass englische Singular-/Pluralformen zur Laufzeit aufgelöst werden.

Standard-Benachrichtigungsvorlagen​

Einstellungen → Vorlagen → Zurücksetzen lädt Standards aus src/locales/templates/{locale}.json (verdrahtet in src/lib/default-notification-templates.ts).

  1. Bearbeiten Sie nur src/locales/templates/en-GB.json (englische Quelle).
  2. Führen Sie pnpm i18n:translate:json (oder pnpm i18n:translate) aus der Repository-Wurzel aus.
  3. Überprüfen Sie Diffs — Platzhalter wie {backup_name} und {problem_table} müssen unverändert bleiben; priority und tags werden von keyPolicy in ai-i18n-tools.config.json übersprungen.
  4. Führen Sie pnpm i18n:status aus, um JSON-Blockabdeckung zu sehen.

Siehe ai-i18n-tools JSON-Leitfaden für Flags (--locale, --force usw.).

Landingpage-HTML​

Der Textkörper der Docs-Startseite ist eine einzelne englische HTML-Datei, keine React-Abschnittskomponenten.

  1. Bearbeiten Sie documentation/src/landing/landing.html (und documentation/src/landing/landing.css für das Layout). Behalten Sie die Hash-IDs features, dashboard, workflow, security und install bei.
  2. Führen Sie pnpm i18n:translate:docs aus dem Repo-Root aus (oder pnpm translate:docs aus documentation/).
  3. Generierte Kopien werden nach documentation/src/landing/i18n/{locale}/landing.html geschrieben. Bearbeiten Sie diese Dateien nicht manuell.

translate-docs verwendet die HTML-Seiten-Pipeline: Sichtbarer Text und alt / title / aria-label werden übersetzt; <pre> und <code> bleiben auf Englisch. Navigationsleisten-Labels und der Seitentitel verbleiben in Docusaurus Translate (homepage.nav.*, homepage.meta.*).

Fügen Sie dieser Datei keine data-i18n-Markierungen hinzu und listen Sie sie nicht unter ui.sourceRoots auf. Dieselbe HTML-Datei darf sich nicht sowohl in der Dokumenten-Pipeline als auch in der UI-Zeichenfolgen-Pipeline befinden.

Glossar​

  • UI-Terminologie für die Dokumentation stammt aus jedem ui[]-Katalog, wobei uiGlossary aktiviert bleibt (Standard). Der Next.js-App-Katalog ist src/locales/strings.json (erstellt durch pnpm i18n:extract). Setzen Sie glossary.uiGlossary nicht; dieser Schlüssel wird abgelehnt.
  • Überschreibungen befinden sich in documentation/glossary-user.csv (glossary.userGlossary in der Konfiguration). Informationen zum Spaltenformat finden Sie in der ai-i18n-tools-Glossardokumentation.
  • Eine CSV-Vorlage generieren: pnpm i18n:glossary-generate (Root).

Cache​

Der Übersetzungscache für ai-i18n-tools befindet sich unter .translation-cache/ im Repository-Root (cacheDir in ai-i18n-tools.config.json). Er ist gitignored. Verwenden Sie pnpm i18n:status und die CLI-Optionen --force / Cache-Flags gemäß der ai-i18n-tools-Dokumentation, wenn Sie eine vollständige Aktualisierung benötigen.

Überschriften-IDs und Anker​

Verwenden Sie explizite IDs, damit Links über Sprachen hinweg stabil bleiben. Bevorzugen Sie die MDX-Kommentarsyntax (pnpm write-heading-ids verwendet --syntax mdx-comment):

## This is a heading {/* #this-is-a-heading */}

Platzieren Sie IDs auf h2 und darunter. Docusaurus write-heading-ids überspringt h1 (den Seitentitel / Seitenleistentitel). documentation/docusaurus.config.ts entfernt auch Überschriften-ID-Kommentare aus abgeleiteten Titeln, da die Docusaurus-Metadatenerfassung immer noch nur klassische {#id} entfernt.

cd documentation
pnpm write-heading-ids

Ignorierlisten​

Verwenden Sie .translate-ignore im Repository-Root (gleiche Idee wie .gitignore) für Pfade, die der Dokumentationsübersetzer überspringen soll, falls Sie eine solche Liste für Ihren Workflow hinzufügen.

Docusaurus Theme JSON​

pnpm write-translations extrahiert Docusaurus-Benutzeroberflächenzeichenketten nach documentation/i18n/en/. Der ai-i18n-tools translate-docs-Schritt (mit markdownOutput.style: "docusaurus") füllt übersetzte JSON-Dateien unterhalb jedes Gebietsschemas neben Markdown ein, gemäß ai-i18n-tools.config.json.

Problembehandlung​

  • OPENROUTER_API_KEY nicht festgelegt — exportieren Sie es oder fügen Sie es zu .env.local im Repository-Root hinzu.
  • Modell / Qualität — passen Sie openrouter.translationModels und verwandte Optionen in ai-i18n-tools.config.json an.
  • Glossar — bearbeiten Sie documentation/glossary-user.csv oder generieren Sie Benutzeroberflächenelemente neu und führen Sie Extraktion + Übersetzung erneut aus.

Hinzufügen einer neuen Sprache​

  1. Fügen Sie das Gebietsschema zu Docusaurus i18n.locales und localeConfigs in documentation/docusaurus.config.ts hinzu.
  2. Fügen Sie dasselbe Gebietsschema zu targetLocales in ai-i18n-tools.config.json hinzu (Repository-Root).
  3. Führen Sie pnpm i18n:generate-ui-languages im Root aus, danach pnpm i18n:extract / Übersetzungsbefehle nach Bedarf.