Architektur
Architekturübersicht
Die Codebasis ist in vier Schichten organisiert. Verwenden Sie diesen Abschnitt für das mentale Modell; öffnen Sie den Quellbaum, wenn Sie Details auf Dateiebene benötigen.
Wie ein sync-Lauf zusammenpasst
sync (und die einzelnen Übersetzungsbefehle) führen aktivierte Funktionen der Reihe nach aus:
| Schritt | Befehl | Was er tut |
|---|---|---|
| 1 | extract → translate-ui | UI-Quellen scannen → strings.json aktualisieren → flaches Gebietsschema-JSON füllen (de.json, …) |
| 2 | translate-svg (optional) | SVG-Text unter config.svg übersetzen |
| 3 | translate-docs | Markdown-, MDX-, .astro-Seiten übersetzen; Docusaurus-Katalog-JSON; Nextra _meta / Wörterbuch .ts; VitePress-Themenkatalog |
| 4 | translate-json (optional) | Verschachtelte JSON-Blätter unter json[] übersetzen |
Jede Pipeline folgt demselben Kernzyklus: Segmente extrahieren → Syntax schützen → stapeln → Cache-Lookup oder LLM-Aufruf → Ausgabe schreiben. Gemeinsame Dienste in der Mitte – Konfiguration, Platzhalter, Cache, Glossar, LlmClient – werden unter Gemeinsame Infrastruktur beschrieben.
Modulzuordnung
| Schicht | Ordner | Rolle |
|---|---|---|
| Einstieg | src/cli/ | CLI-Befehle: init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, … |
| Pipelines | src/extractors/ | Segmentextraktion aus JS/TS, HTML-Markern, Markdown, JSON, SVG, .astro |
src/processors/ | Platzhalterschutz, Batching, Validierung, Link-Umschreibung | |
| Gemeinsam | src/core/ | Konfiguration, Typen, SQLite-Cache, Prompts, Ausgabepfade, Gebietsschema-Dienstprogramme |
src/api/ | LlmClient – anbieterunabhängiger Chat-Client (Vercel AI SDK) mit Modell-Fallback | |
src/glossary/ | Laden von Glossaren, Terminhinweise und optionale Projektkontextdateien für Prompts | |
src/utils/ | Logger, Hashing, Ignore-Parser, Tabellen mit Anzeigebreite, .env-Loader | |
| Ihre App-Laufzeit | src/runtime/ | i18next-Helfer und Anzeige-Dienstprogramme – exportiert als 'ai-i18n-tools/runtime' (Laufzeit-Helfer) |
| Tool-UI (Dogfooding) | src/i18n/, src/dashboard-app/, src/server/ | Lokalisiert die eigene CLI und das Übersetzungs-Dashboard dieses Pakets — getrennt von Ihrem Projektinhalt (Selbstlokalisierung) |
Alles, was für die programmatische Nutzung vorgesehen ist, wird aus src/index.ts re-exportiert (Programmatische API).
Pipeline-Zusammenfassungen
| Pipeline | Abschnitt | Eingabe → Ausgabe |
|---|---|---|
| UI-Strings | Interna der UI-Strings | Quelldateien → strings.json → flache {locale}.json |
| Dokumente | Interna der Dokumente | Markdown / MDX / .astro / Docusaurus JSON → Dateien pro Gebietsschema unter docs[].outputDir |
| JSON-Bundles | JSON-Interna | Verschachteltes JSON unter json[] → JSON-Dateien pro Gebietsschema |
| SVG | Interna der Dokumente – Extraktoren | SVG-Dateien unter config.svg → übersetzte SVG-Kopien |
Interna der UI-Strings
| Schritt | Komponente | Ergebnis |
|---|---|---|
| 1 | Quelldateien (JS/TS; optional .astro / .html) | Dateien auf der Festplatte |
| 2 | UIStringExtractor (Babel via ui-string-babel.ts) | Segmente, die durch MD5-Hashs identifiziert werden |
| 3 | strings.json | Masterkatalog: { hash: { source, translated, models?, locations? } } |
| 4 | LlmClient.translateUIBatch() | JSON-Array von Quell-Strings → Übersetzungen (+ Modell-ID pro Batch) |
| 5 | de.json, pt-BR.json, … | Flache Zuordnungen: Quell-String → Übersetzung (keine Modellmetadaten) |
UIStringExtractor
extractUiCallsFromFileContent in ui-string-babel.ts findet t("literal")- und i18n.t("literal")-Aufrufe. JS- und TS-Dateien werden mit @babel/parser (Modulquellcode, TypeScript und JSX) geparst. Für .astro-Quellen (wenn in ui.uiExtractor.extensions aufgeführt) parst dieselbe Funktion Frontmatter- und Vorlagen-{expression}-Blöcke und wendet dieselben funcNames-Regeln an. Funktionsnamen und Dateierweiterungen sind über ui.uiExtractor konfigurierbar (ui.reactExtractor ist ein unterstützter Alias). extract führt auch zusätzliche Eingaben in denselben Katalog zusammen: das Projekt-package.json description, wenn includePackageDescription aktiviert ist (Standard), und jedes englishName aus dem gebündelten UI-Sprachen-Masterkatalog (erstellt aus sourceLocale + targetLocales), wenn includeUiLanguageEnglishNames true ist (bereits im Quellcode gefundene Zeichenketten behalten Vorrang; liest languagesManifestPath nicht). extract generiert auch ui-languages.json unter languagesManifestPath neu. Segment-Hashs sind die ersten 8 Hex-Zeichen des MD5-Hashs der gekürzten Quellzeichenkette – diese werden zu den Schlüsseln in strings.json.
Für .html / .htm-Quellen (wenn in ui.uiExtractor.extensions aufgeführt) leitet extract die Datei stattdessen durch html-i18n-marks.ts, das data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label-Marker-Attribute scannt (konfigurierbar über ui.uiExtractor.htmlI18nAttributes). Ein einfacher Marker entnimmt seinen Quelltext dem eigenen textContent oder Attribut des Elements; ein Marker mit Wert (data-i18n="Key") verwendet den Wert. data-i18n-locale-src und data-i18n-locale-href sind für die Browser-Laufzeitumgebung reserviert und werden niemals extrahiert. Dasselbe Modul steuert den mark-html-Befehl, der die einfachen Marker automatisch einfügt (einschließlich alt und aria-label) und niemals die Locale-URL-Marker einfügt. HTML-Dateien erreichen niemals den Babel-Durchlauf. Generiertes Locale-HTML unter einem Dokumentations-outputDir wird von diesem Scan ausgeschlossen.
Einfache Astro SSG-Sites können i18next überspringen: Laden Sie flache {locale}.json zur Build-Zeit und lösen Sie t('source text') nach Quelltextschlüssel auf. Die Ausgangssprache ist sourceLocale und kann jede Sprache sein (siehe examples/astro-website/src/i18n/t.ts und UI-Strings – Astro-Website).
Reine HTML-Apps folgen demselben Katalogmodell mit Marker-Attributen anstelle von t()-Aufrufen — siehe HTML zur Übersetzung markieren. Das gebrauchsfertige Skript ist ai-i18n-tools/html-runtime/i18n.js.
Statisches HTML, das zu einer Datei pro Locale werden soll, ist eine Dokumenten-Pipeline (HtmlTemplateExtractor innerhalb von translate-docs), nicht dieser Katalog. Siehe HTML-Seiten.
strings.json
Der Master-Katalog hat folgende Struktur:
{
"a1b2c3d4": {
"source": "The English string",
"translated": {
"de": "Der deutsche Text",
"pt-BR": "O texto em português"
},
"models": {
"de": "anthropic/claude-3.5-haiku",
"pt-BR": "openai/gpt-4o"
},
"locations": [{ "file": "src/app/page.tsx", "line": 51 }]
}
}models (optional) – pro Gebietsschema, welches Modell diese Übersetzung nach dem letzten erfolgreichen translate-ui-Lauf für dieses Gebietsschema erstellt hat (oder user-edited, wenn der Text vom Übersetzungs-Dashboard gespeichert wurde). locations (optional) – wo extract die Zeichenfolge gefunden hat (Scanner + Paketbeschreibungszeile; gebündelte Master-englishName-Zeichenfolgen können locations weglassen).
extract fügt neue Schlüssel hinzu und bewahrt vorhandene translated / models-Daten für Schlüssel, die noch im Scan vorhanden sind (Scanner-Literale, optionale Beschreibung, optionaler gebündelter Master-englishName). translate-ui füllt fehlende translated-Einträge, aktualisiert models für die Gebietsschemata, die es übersetzt, und schreibt flache Gebietsschema-Dateien.
ui-languages.json Manifest – JSON-Array von { code, label, englishName, direction } (BCP-47 code, UI label, Referenz englishName, "ltr" oder "rtl"). Verwenden Sie generate-ui-languages oder extract, um eine Projektdatei aus sourceLocale + targetLocales und dem gebündelten Master-data/ui-languages-complete.json zu erstellen.
Flache Lokalisierungsdateien
Jede Zielsprache erhält eine flache JSON-Datei (de.json), die Quelltext → Übersetzung abbildet (ohne models-Feld):
{
"The English string": "Der deutsche Text",
"Save": "Speichern"
}i18next lädt diese als Ressourcenbündel und sucht Übersetzungen über den Quelltext (Key-as-Default-Modell).
UI-Übersetzungsanweisungen
buildUIPromptMessages erstellt System- und Benutzernachrichten, die:
- Quellsprache und Zielsprache identifizieren (anhand des Anzeigenamens von
localeDisplayNamesoderui-languages.json). - Eine Skript-Direktive voranstellen, wenn das Ziel-Gebietsschema ein erwartetes Schriftsystem hat (explizites BCP-47-Skript oder eine Sprachstandardeinstellung wie
hi→ Devanagari,ar→ Arabisch,ja→ japanische Kana/Kanji). - Ein JSON-Array von Zeichenfolgen senden und ein JSON-Array von Übersetzungen zurückfordern.
- Glossar-Hinweise einbeziehen, falls verfügbar.
LlmClient.translateUIBatch versucht jedes Modell der Reihe nach und greift bei Analyse-, Netzwerk- oder Skriptfehlern zurück (einschließlich romanisiertem/lateinischem Fallback für Lokalisierungen mit nativer Schrift). Die CLI erstellt diese Liste pro Ziellokalisierung aus localeModels, optional uiModels und translationModels (siehe KI-Modelle).
Interna der Dokumente
| Schritt | Komponente | Ergebnis |
|---|---|---|
| 1 | Markdown / MDX / JSON / .astro-Dateien (translate-docs) | Quelldateien |
| 2 | MarkdownExtractor / JsonExtractor / AstroTemplateExtractor | segments[] – typisierte Segmente mit Hash + Inhalt |
| 3 | PlaceholderHandler | Geschützter Text – HTML, Admonitionen, Anker, MDX, URLs, Inline-Code, Hervorhebung als Token maskiert |
| 4 | splitTranslatableIntoBatches | batches[] – gruppiert nach Anzahl + Zeichenlimit |
| 5 | TranslationCache-Suche | Cache-Treffer → überspringen; Miss → LlmClient.translateDocumentBatch |
| 6 | PlaceholderHandler.restoreAfterTranslation | Endgültiger Text – Platzhalter wiederhergestellt |
| 7 | resolveDocumentationOutputPath | Ausgabedatei – Docusaurus-Layout oder flaches Layout |
Extraktoren
Alle Extraktoren erweitern BaseExtractor und implementieren extract(content, filepath): Segment[].
MarkdownExtractor– teilt Markdown in typisierte Segmente auf:frontmatter,heading,paragraph,code,admonition. YAML-Frontmatter wird als nicht übersetzbar klassifiziert (slug,idund andere Routing-Schlüssel bleiben stabil). Top-Level-export ...-Blöcke (z. B. React-Komponentendefinitionen) werden als nicht übersetzbareother-Segmente neben der bestehendenimport ...-Behandlung klassifiziert. Mehrzeilige Blöcke, die mit einem großen JSX-Tag beginnen (z. B. ein<Tabs>-Block), werden als übersetzbare Absätze klassifiziert. Nicht übersetzbare Segmente (Codeblöcke, reines HTML) werden wortgetreu beibehalten.AstroTemplateExtractor– Parsen und Ersetzen für.astro-Marketingseiten (translate-docsübertranslateAstroFileindoc-translate.ts). Extrahiert benutzerseitige HTML-Textknoten und übersetzbare Attribute (alt,title,aria-label,placeholder) sowie String-Literale innerhalb von Template-{expression}-Blöcken, wenn sie benutzerseitig sind. Überspringt Frontmatter-TypeScript,<script>,<style>, geschützte Attribut-/Schlüsselwerte und Literale innerhalb vont('…'). Die Wiederzusammenstellung passt relative Importe an, wenn die Ausgabepfade tiefer sind (z. B.src/pages/de/index.astro). Siehe Astro-Website-Seiten.JsonExtractor– extrahiert String-Werte aus Docusaurus-JSON-Label-Dateien (Docusaurus-UI-Kataloge, nicht MDX-Body).SvgExtractor– extrahiert<text>,<title>und<desc>-Inhalte aus SVG (wird vontranslate-svgfür Dateien unterconfig.svgverwendet, nicht vontranslate-docs).html-i18n-marks.ts– ein fokussierter HTML-Tag-Scanner, der vonextractfür.html/.htm-Quellen und vommark-html-Befehl verwendet wird.collectHtmlI18nStrings/collectHtmlI18nLocationslesendata-i18n*-Markerattribute (einfacher Marker → ElementtextContent/title/placeholder; gewerteter Marker → der Wert), undmarkHtmlContentfügt einfache Marker in Leaf-Text- / Titel- / Platzhalterelemente ein (idempotent, beachtetdata-i18n-ignore, überspringt Code-ähnliche und gemischte Inhaltselemente). Der gemeinsamenormalizeI18nText-Helfer hält Build-Zeit-Schlüssel identisch mit der Browser-Laufzeit.
Astro-Hybrid-Websites (UI + Seiten-HTML)
Einfache Astro-Apps aktivieren oft sowohl UI-Strings als auch Dokumente in einer Konfiguration (Referenz: examples/astro-website/):
| Ebene | Mechanismus | Ausgabe |
|---|---|---|
| Template-HTML | AstroTemplateExtractor + translate-docs | Pro-Gebietsschema .astro unter docs[].outputDir |
Frontmatter / t('…') | ui-string-babel.ts + extract + translate-ui | Flaches public/locales/{locale}.json (Ausgangssprachen-String als Schlüssel; sourceLocale kann jede Sprache sein) |
Der Befehl sync führt die aktivierten Schritte der Reihe nach aus: extrahieren dann translate-ui (wenn features.translateUIStrings) → optional translate-svg → translate-docs → optional translate-json (es sei denn, übersprungen mit --no-ui, --no-svg, --no-docs oder --no-json). Die Init-Vorlage ui-astro-website erstellt nur UI-Strings; fügen Sie docs[] und features.translateDocs für Seiten-HTML hinzu.
Einfügen von Überschrift-Ankern (write-heading-ids CLI)
Der Befehl write-heading-ids ist ein lokaler, nicht-LLM Vorbereitungsprozessor für Markdown-Dokumentation. Implementierung: src/cli/write-heading-ids.ts steuert die Dateierkennung; src/markdown/write-heading-ids-core.ts analysiert die Zeilen und fügt Anker ein.
Es erfordert eine gültige Konfiguration mit mindestens einem docs[]-Block. Für jeden Block werden .md- / .mdx-Dateien unter contentPaths gesammelt, die .translate-ignore-Regeln des Projekts angewendet (gleiche Idee wie bei der Dokumentübersetzung) und optional auf einen Unterbaum mit --path / --file beschränkt. Jede Datei wird mit applyHeadingAnchorsToMarkdown transformiert: Für jede flache ATX-Überschrift (# … bis ###### …) außerhalb von Codeblöcken werden vorhandene Überschriften-IDs jeglicher Form durch den ausgewählten Stil ersetzt. HTML-Stile schreiben <a id="slug"></a> in die Zeile über einer suffixfreien Überschrift; --slug-style mdx-comment schreibt {/* #slug */} in die Überschriftenzeile (und entfernt einen vorangehenden HTML-Anker). Slugs stammen immer aus dem aktuellen Überschriftentext. --remove entfernt HTML-Anker, klassische {#id}-Suffixe und MDX-Kommentar-IDs, ohne neue zu schreiben. Slug-Algorithmen entsprechen gängigen Ökosystemen – github (Standard), bitbucket, gitlab, pymdown (optionale Unicode-Normalisierungs- / Prozentkodierungs-Flags), azure-devops sowie mdx-comment (GitHub-Slug + MDX-Kommentarausgabe) –, sodass Anker-IDs mit vorhandenen Tools (doctoc, PyMdown, Docusaurus usw.) konsistent bleiben. --dry-run meldet potenzielle Bearbeitungen, ohne zu schreiben.
Nach dem Quell-Pass positioniert derselbe Befehl diese englischen IDs auf dem vorhandenen übersetzten Markdown jedes Gebietsschemas neu (resolveTranslatedOutputPath). Übersetzte Titel werden niemals neu geslugt; eine Überschrift-Mitte {#id} / {/* #id */} wird zurück an das Suffix (oder den HTML-Anker) verschoben, das der ausgewählte Stil erwartet. Fehlende Gebietsschema-Dateien werden übersprungen.
Dieser Befehl wird nicht innerhalb von translate-docs oder sync ausgeführt; führen Sie ihn explizit aus, wenn Sie stabile Fragment-IDs in den Quelldateien vor der Übersetzung oder Veröffentlichung benötigen.
Platzhalter-Schutz
Vor der Übersetzung wird empfindliche Syntax durch undurchsichtige Token ersetzt, um LLM-Beschädigungen zu verhindern. Die Ersetzung erfolgt in dieser Reihenfolge (die Wiederherstellung erfolgt umgekehrt):
- Codeblöcke mit Begrenzern (drei oder mehr Backticks oder Tilden, einschließlich eines längeren Begrenzers, der einen kürzeren umschließt) – der gesamte Begrenzer, einschließlich des Info-Strings, wird durch
{{CDF_N}}ersetzt und in der Reihenfolge der anderen strukturellen Token beibehalten. Dadurch werden Beispiele in Containern wie::: code-groupoder::: tipan ihrer Position gehalten. Info-Strings von Begrenzern (VitePress-Tab-Beschriftungen) bleiben in der Ausgangssprache. Ein nicht geschlossener Öffner wird als Text belassen, damit ein späterer Container-Schließer nicht verschluckt wird. - Suffixe für Überschriften-IDs (klassisches
{#id}/ MDX{/* #id */}am Ende einer ATX-Überschrift) – werden vollständig aus der Zeile entfernt und nicht an das Modell gesendet. Nach der Wiederherstellung werden sie wieder an das Ende der entsprechenden Überschrift angeheftet, sodass Docusaurus weiterhin eine gültige ID erkennt. Kommentare in der Mitte von Überschriften bleiben im Text und werden von den späteren MDX- /{#…}-Schichten verarbeitet. Überschriften innerhalb eines maskierten Begrenzers werden nicht entfernt. - HTML-Tags und -Kommentare (
<strong>,<!-- ... -->usw.) – HTML-Tags in Kleinbuchstaben aus einer bekannten Zulassungsliste werden durch{{HTM_N}}-Token ersetzt. JSX-Tags in Großbuchstaben (<Highlight>,<Tabs>,</Tab>) werden separat von der MDX-Schicht (Schritt 6) verarbeitet. - Admonition-Marker (
:::note,:::) – nur das Direktivenpräfix in der Eröffnungszeile wird durch{{ADM_OPEN_N}}ersetzt; jeder Titel in derselben Zeile wird dem Modell zur Übersetzung überlassen. Wird mit dem exakten Originaltext wiederhergestellt. - Dokumentenanker (HTML
<a id="…">, übrig gebliebenes Docusaurus-{#…}in der Mitte einer Überschrift) – werden wörtlich beibehalten. - Nur-MDX-Konstrukte (
src/processors/mdx-placeholders.ts):- MDX-Kommentare (
{/* … */}, einschließlich eines{/* #my-id */}in der Mitte einer Überschrift, das kein Zeilenende-Suffix war) werden durch{{MDX_N}}ersetzt. - JSX-Tags in Großbuchstaben (
<Highlight>,<Tabs>,<TabItem>,<TOCInline />,</Highlight>) – werden als{{MDX_N}}beibehalten, wobei übersetzbare String-Attribute (label,tooltip,aria-label) in{{JXA_N}}innerhalb des Tags umgeschrieben werden, es sei denn, der Attributname erscheint indocs[].protectAttributes;label:innerhalb von<Tabs values={[ { label: '…' } ]}>-Objektliteralen (überspringbar überdocs[].protectKeys) und<TabItem value="…">(wenn keinlabel-Attribut vorhanden ist, wobei Slug-ähnliche Werte in Kleinbuchstaben übersprungen werden) werden ebenfalls extrahiert. An das Segment als||JXA_N: …||-Zeilen angehängt und durchrestoreMdxwieder zusammengeführt. - MDX-Ausdrücke in geschweiften Klammern (
{frontMatter.title},style={{…}}) – tiefenbewusster Abgleich, ersetzt durch{{MDX_N}}.
- MDX-Kommentare (
- Markdown-URLs (
](url),src="…") – werden nach der Übersetzung aus einer Map wiederhergestellt. - Inline-Code-Abschnitte (
`code`) und fett formatierter Inline-Code (**code**) – bleiben erhalten. - Markdown-Hervorhebung (optional, automatisch für CJK/RTL-Gebietsschemata aktiviert) – Hervorhebungsbegrenzer werden maskiert.
Nachdem das Modell eine Antwort zurückgegeben hat, stellt translate-docs die Maps wieder her und validiert das Segment: Dieselbe Multimenge von Token in doppelten geschweiften Klammern muss vorhanden sein, strukturelle Token ({{HTM_N}}, Admonition-Marker, {{CDF_N}}) müssen ihre geordnete Teilsequenz beibehalten (Inhalts-Token wie {{ILC_N}} / {{URL_N}} / {{SE}} können sich mit der Wortstellung verschieben), wiederhergestellte Arten von HTML-Tags müssen mit der ungeschützten Quelle übereinstimmen und jeder übrig gebliebene Bezeichner in doppelten geschweiften Klammern muss bereits in der Quelle vorhanden gewesen sein (sodass erfundene Token fehlschlagen). Der Dokumenten-Prompt fordert die Modelle außerdem auf, jedes Token einmal zu kopieren, die Reihenfolge der strukturellen Token beizubehalten und keine neuen Wrapper in doppelten geschweiften Klammern zu erfinden; mechanische Prüfungen bleiben maßgebend.
Der gemeinsame Attribut-/Schlüsselschutz für Astro-Templates und MDX JSX wird in src/processors/expression-attribute-protection.ts implementiert und pro Block durch docs[].protectAttributes und docs[].protectKeys gesteuert (siehe protectAttributes / protectKeys).
Cache (TranslationCache)
SQLite-Datenbank (über node:sqlite) speichert Datensätze, die über (source_hash, locale) mit translated_text, model, filepath, last_hit_at und verwandten Feldern verknüpft sind. Der Hash ist die ersten 16 Hex-Zeichen des SHA-256-Hashs des normalisierten Inhalts (Leerzeichen zusammengefasst).
Bei jedem Durchlauf werden Segmente nach Hash × Locale nachgeschlagen. Nur Cache-Fehler gehen an das LLM. Nach der Übersetzung wird last_hit_at für Segmentzeilen im aktuellen Übersetzungsbereich, die nicht getroffen wurden, zurückgesetzt. Erfolgreiche Cache-Treffer während der Dokumentübersetzung löschen veraltete translation_failures-Zeilen für dieses Segment.
cleanup führt zuerst sync --force-update aus, dann:
- entfernt veraltete Segmentzeilen (null
last_hit_at/ leerer Dateipfad); - bereinigt
file_tracking-Schlüssel, wenn der aufgelöste Quellpfad auf der Festplatte fehlt (doc-block:…,json-block:…,svg-files:…usw.); - entfernt Übersetzungszeilen, deren Metadaten-Dateipfad auf eine fehlende Datei verweist;
- bereinigt verwaiste
translation_failures-Zeilen; - bereinigt verwaiste
markdown_source_issues-Zeilen, deren aufgelöster Quellpfad auf der Festplatte fehlt; - löscht Cache-Zeilen für Lokalisierungen, die in der Konfiguration fehlen (
sourceLocale, Stamm-targetLocalesund alle pro-Blockdocs[]/json[]targetLocales; nur SQLite — verwenden Siepurge-locale, um generierte Dateien zu löschen).
Es sichert cache.db nicht, es sei denn, --backup <path> wird übergeben, was zuerst ein Backup in diesen Pfad schreibt.
Abgerechnete Modellaufrufe (akzeptierte Übersetzungen und verworfene Wiederholungen) werden in api_calls gespeichert. Nach einem Befehl, der Aufrufe aufgezeichnet hat, werden Detailzeilen, die älter als sieben UTC-Kalendertage sind, in monatliche api_totals überführt. usage und die Dashboardansicht Nutzung und Kosten führen beide Tabellen zusammen. Siehe Nutzung und Kosten.
Glossar-Context-Hinweise und glossary.contextFiles werden mit einem Fingerabdruck versehen (prompt_context_hash) und in die Benutzeroberfläche, Dokumente, JSON, SVG und Korrekturaufforderungen eingefügt. Eine Änderung dieser Richtlinie invalidiert übereinstimmende gecachte Segmente und Dateiverfolgungszeilen beim nächsten Durchlauf. Dashboard-user-edited-Cache-Zeilen bleiben erhalten. Das Ändern nur einer bevorzugten Glossarübersetzung in einer nicht erzwungenen Zeile lässt den bestehenden Cache intakt, bis --force / --force-update. Eine Force-Zeile verfehlt den Cache nur für Segmente, deren Quelle diesen Begriff enthält, wenn der gespeicherte Text die erzwungene Übersetzung noch nicht enthält, und das Überspringen unveränderter Dateien wird für eine Datei abgelehnt, deren Ausgabe es noch immer nicht enthält. Lassen Sie Context in dieser Zeile leer; ein Kontext-Hinweis aktualisiert dennoch das gesamte Gebietsschema. Markdown lehnt auch ein übersetztes Segment ab, das ein zitiertes Benutzeroberflächen-Label von zwei bis fünf Wörtern (Katalogschlüssel oder ein vorab festgelegtes Label-förmiges Präfix) weglässt. Eine Zitierung ist fettgedruckt, Inline-Code, eine Überschrift oder eine Zeile, die nur dieses Label enthält. Die Großschreibung von Titeln innerhalb eines Satzes ist ein Hinweis, damit die Übersetzung flektiert werden kann (Hindi Cursor account kann zu कर्सर खाते werden, anstatt der Wörterbuchform कर्सर खाता). Ein Label mit einem einzigen Inhaltswort wie Sign in bleibt ein Hinweis. Die Prüfung ignoriert die Groß-/Kleinschreibung in der Übersetzung, sodass ein kleingeschriebenes Label im Satz immer noch zählt, wenn die Quelle es zitiert. Gewöhnliche Prosa, die dieselben Wörter verwendet, kann sie flektieren. Ein vorab festgelegtes Präfix muss ein großgeschriebenes Label sein, dessen gemeinsame Übersetzung eine kurze Phrase ohne Platzhalter ist; Satzstämme werden nicht vorab festgelegt. Diese Prüfung versucht das nächste Modell erneut und teilt das Segment nicht.
Der Befehl translate-docs verwendet auch die Dateiverfolgung, sodass unveränderte Quellen mit vorhandenen, aktuellen Ausgaben die Arbeit vollständig überspringen können. --check-cache öffnet Gebietsschemas mit einem erwarteten Schriftsystem erneut, sodass zwischengespeicherte Segmente neu validiert werden; --force-update führt die Dateiverarbeitung für jedes Gebietsschema erneut aus, während der Segment-Cache weiterhin verwendet wird; --force löscht die Dateiverfolgung und umgeht das Lesen des Segment-Caches für die API-Übersetzung. Wenn die für ein Markdown-Segment versuchten Modelle die AST-Validierung fehlschlagen, kann translate-docs das Segment schrittweise aufteilen und kleinere Teile erneut versuchen (docs[].segmentSplitting.qualityRetrySplit, standardmäßig aktiviert). Derselbe Qualitätsfehler dreimal beendet diese Modellliste vorzeitig. Siehe Dokumente — Cache-Verhalten und Flags für die vollständige Flag-Tabelle.
Batch-Prompt-Format: translate-docs --prompt-format wählt XML (<seg> / <t>) oder JSON-Array-/Objektformen nur für LlmClient.translateDocumentBatch; Extraktion, Platzhalter und Validierung bleiben unverändert. Siehe Batch-Prompt-Format.
Auflösung des Ausgabepfads
resolveDocumentationOutputPath(config, cwd, locale, relPath, kind) ordnet einen quellbezogenen Pfad dem Ausgabepfad zu:
nested-Stil (Standard):{outputDir}/{locale}/{relPath}für Markdown.doc-system-Stil: UnterdocsRootverwenden die Ausgaben{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}; Pfade außerhalb vondocsRootgreifen auf das verschachtelte Layout zurück. Aliase:docusaurus(StandardlocaleSubpath= Docusaurus-Plugin-Pfad),astro-starlight(Standard leerlocaleSubpath),vitepress(wiedoc-systemmit leeremlocaleSubpath; behält die BCP-47-Ordnergroß-/Kleinschreibung bei).flat-Stil:{outputDir}/{stem}.{locale}{extension}. WennflatPreserveRelativeDirauftruegesetzt ist, bleiben die Quellunterverzeichnisse unteroutputDirerhalten.- Benutzerdefiniertes
pathTemplate: jedes Markdown-Layout, das{outputDir},{locale},{LOCALE},{relPath},{stem},{basename},{extension},{docsRoot},{relativeToDocsRoot}verwendet. - Benutzerdefinierter
jsonPathTemplate: separates benutzerdefiniertes Layout für JSON-Beschriftungsdateien, unter Verwendung derselben Platzhalter. linkRewriteDocsRoothilft dem Umschreiber flacher Links, korrekte Präfixe zu berechnen, wenn die übersetzte Ausgabe nicht im standardmäßigen Projektstamm verwurzelt ist.
Umsetzung flacher Links
Wenn docsOutput.style === "flat", werden übersetzte Markdown-Dateien neben der Quelle mit Lokalisierungssuffixen platziert. Relative Links zwischen Seiten werden so umgeschrieben, dass [Guide](./guide.md) in readme.de.md auf guide.de.md verweist. Kontrolliert durch rewriteRelativeLinks (automatisch aktiviert für flachen Stil ohne benutzerdefiniertes pathTemplate). Der gleiche Durchlauf fügt vor postProcessing.regexAdjustments einen pro Datei-Präfix für nicht-Markdown-Asset-URLs hinzu — siehe Flacher Link-Umschreiber.
JSON-Interna
| Schritt | Komponente | Ergebnis |
|---|---|---|
| 1 | json[].contentPaths | Dateien aufgelöst (Datei, Verzeichnis oder Glob) |
| 2 | NestedJsonExtractor | String-Blätter ausgewählt durch keyPolicy (Punktpfade + Minimatch) |
| 3 | PlaceholderHandler + Batch + TranslationCache | Cache-Treffer → überspringen; Miss → LlmClient.translateDocumentBatch (gemeinsame SQLite) |
| 4 | NestedJsonExtractor.reassemble | Ausgabedatei über expandJsonBlockOutputPath(outputPathTemplate) |
NestedJsonExtractor(src/extractors/nested-json-extractor.ts) durchläuft beliebig verschachteltes JSON und gibt ein Segment pro übersetzbarem String-Blatt aus.keyPolicy.mode(allowlist,denylistoderboth) filtert Pfade mit Minimatch auf Punktnotation (einfache Namen wieslugstimmen mit dem letzten Schlüssel-Segment überein).- Die Cache-Dateiverfolgung verwendet
json-block:{blockIndex}:{projectRelPath}infile_tracking(gleichescacheDirwie Docs und SVG). - Nicht für Docusaurus
write-translations-Kataloge ({ message, description }-Form) – diese verwenden Dokumente (docs[].docusaurusCatalogDir+JsonExtractorinnerhalb vontranslate-docs). - Nicht für
t()-UI-Strings – UI-Strings (strings.json+ flache Bundles). - CLI:
translate-json; Orchestrierung insrc/cli/translate-json-run.ts. Init-Vorlage:ui-json-bundles.
Gemeinsame Infrastruktur
LlmClient
Anbieterunabhängiger Chat-Client, der auf dem Vercel AI SDK (ai + @ai-sdk/openai-compatible) basiert. Er ermittelt den aktiven Anbieter aus provider / providers, erstellt einen OpenAI-kompatiblen Client (createOpenAICompatible) für die baseUrl + API-Schlüssel des jeweiligen Anbieters und leitet alle Aufrufe über generateText. OpenRouterClient bleibt als veralteter Alias erhalten. Wichtige Verhaltensweisen:
- Modell-Fallback: versucht jedes Modell in der aufgelösten Liste der Reihe nach; greift bei Anforderungs- oder Analysefehlern auf ein anderes Modell zurück. Jedes Ziellokal erhält seine eigene aufgelöste Kette:
localeModels(locale)zuerst, wenn konfiguriert, dannuiModels(nur UI-Pipelines), danntranslationModels. Dokument-, JSON- und SVG-Übersetzung erstellen einen pro-lokalen Client mit der Nicht-UI-Kette. Der Befehlbench-modelserstellt stattdessen einen einzelnen Modell-Client pro konfigurierter ID (Vereinigung vontranslationModels,uiModelsundlocaleModels;translationModels: [id], kein Fallback), damit er jedes Modell unabhängig zeitlich erfassen und bepreisen kann. - Anfrage-Timeout:
requestTimeout(Sekunden) oderrequestTimeoutMsbeim aktiven Anbieter, andernfalls dieselben Schlüssel oben in der Konfiguration (Standard 120 Sekunden), bricht jede Anfrage überAbortSignal.timeoutab. Derselbe Wert gilt fürGET /models, wenn die CLI die Modellliste eines Anbieters fürcheck-models(jeder Anbieter) lädt. Der optionale Pre-Flight-Filter, der unbekannte Modell-IDs verwirft, läuft nur, wenn der aktive Anbieter OpenRouter ist. - OpenRouter-Extras (nur wenn
openrouteraktiv ist): Durchsatz-Routing über das Anforderungsfeldproviderund die HeaderHTTP-Referer/X-Title. Die Token-Nutzung wird für jeden Anbieter gemeldet. OpenRouter und Cheaper Inference geben auch einen abgerechneten USD-Betrag zurück (usage.cost; Cheaper Inference greift aufcheaper_inference.billing.billed_cost_usdzurück). Wenn der Anbieter diesen Betrag weglässt, werden die USD-Kosten ausproviders.<name>.modelPricingberechnet, dann dem anbieterweiten Standardwertpricing, dann dem Listenpreis für Eingabe und Ausgabe von models.dev, und in der Zeileapi_callsgespeichert. Ein vom Anbieter gemeldeter Preis (einschließlich0) wird niemals ersetzt. Unbekannte Kosten bleiben ungesetzt. Die Preisgestaltung eines Aufrufs liest nur den models.dev-Ausschnitt von<cacheDir>/benchmark-scores.json; es lädt weder languagebench noch die Arena-Datei herunter. - Debug-Traffic-Log: wenn
debugTrafficFilePathgesetzt ist, werden Anforderungs- und Antwort-JSON an eine Datei angehängt (programmatisch). Die CLI--debug-failedschreibtFAILED-TRANSLATION-Dateien untercacheDirmit dem System-/Benutzer-Prompt, der rohen Assistentenantwort und Validierungsfehlern für fehlgeschlagene UI-, Dokument-, JSON- und SVG-Übersetzungsprüfungsversuche. Anbieter-API-/Leer-Body-Fehler werden auf der Konsole ausgegeben, anstatt eine reine Prompt-Datei zu speichern.
suggest-models und die Dashboard-Registerkarte Modelle rufen das LLM nicht auf. Sie bewerten den Chat-Katalog des aktiven Anbieters mit einem Qualitätsindex aus languagebench ChrF und LMArena Arena Score. Der Preis ist ein gemischter 3:1-Preis pro Million Token in USD (Katalog, dann models.dev, dann languagebench). --quality sortiert nach Index; --price durchläuft die Qualität-Preis-Pareto-Front. Sie ersetzen optional providers.<name>.translationModels. Aggregate befinden sich in <cacheDir>/benchmark-scores.json. Siehe KI-Modelle und suggest-models.
Laden der Konfiguration
loadI18nConfigFromFile(configPath, cwd)-Pipeline:
ai-i18n-tools.config.json(JSON) lesen und parsen.mergeWithDefaults– tiefes Zusammenführen mitdefaultI18nConfigPartialund Zusammenführen allerdocs[].sourceFiles-Einträge incontentPaths.expandTargetLocalesFileReferenceInRawInput–targetLocalesin ein Array umwandeln und pfadähnliche Einträge ablehnen (müssen BCP-47-Codes sein, kein Pfad zuui-languages.json);languagesManifestPathist standardmäßig{ui.flatOutputDir}/ui-languages.jsonwährendmergeWithDefaults.expandDocumentationTargetLocalesInRawInput– dasselbe für jedendocs[].targetLocales-Eintrag.expandJsonTargetLocalesInRawInput– dasselbe für jedenjson[].targetLocales-Eintrag.parseI18nConfig– Zod-Validierung +validateI18nBusinessRules.applyProviderOverrideToRawInput– wenn-P/--providerüber die CLI übergeben wird.applyEnvOverrides– wendetOPENROUTER_BASE_URL,OLLAMA_BASE_URL,I18N_SOURCE_LOCALEundI18N_TARGET_LOCALESan, wenn gesetzt (API-Schlüssel werden separat pro Anbieter innerhalb vonLlmClientaufgelöst).augmentConfigWithUiLanguagesMaster– Manifest-Anzeigenamen aus dem gebündelten Masterkatalog anhängen.assertEffectiveLocalesInUiLanguagesMaster– Gebietsschema-Codes bei Bedarf gegen den Masterkatalog validieren.
init erstellt Starter-Konfigurationen aus initConfigTemplates: ui-markdown (UI-Strings plus einen flachen README-Block), docs-markdown (nur README und Markdown), ui-docusaurus, ui-starlight, ui-vitepress (VitePress-Dokumentation + vitepressThemeCatalog), ui-nextra (Nextra-Dokumentation + nextraDictionaryPath), ui-astro-website (einfache Astro-UI; fügen Sie docs[] für .astro-Seitenübersetzung hinzu), ui-json-bundles (nur JSON json[]), ui-python, ui-python-gettext, ui-python-django und ui-python-flask. --with-readme fügt denselben README-Block an jede Vorlage an, die nicht bereits README.md auflistet, und schaltet translateDocs ein. Siehe UI-Strings — Initialisieren, Fügen Sie i18n zu Ihren README- und Markdown-Dokumenten hinzu und Python-Anwendungen.
Protokollierung (Logger)
Logger unterstützt die Stufen debug, info, warn, error mit ANSI-Farbgebung. Der ausführliche Modus (-v) aktiviert debug. Wenn logFilePath gesetzt ist, werden Log-Zeilen zusätzlich in diese Datei geschrieben.
Selbstlokalisierung (Tool-UI)
Das Tool lokalisiert seine eigene Benutzeroberfläche — CLI-Hilfe, häufige Protokoll-/Zusammenfassungs-/Fehlermeldungen und das Übersetzungs-Dashboard — getrennt von den Inhalten, die es für Sie übersetzt.
- Gebietsschema-Auflösung (
resolveUiLocaleinsrc/core/ui-locale.ts): wählt das UI-Gebietsschema aus-L/--ui-lang>AI_I18N_LANG> Konfigurations-uiLanguage> Host-Betriebssystem-Gebietsschema (Intl.DateTimeFormat().resolvedOptions().locale). Der Kandidat wird normalisiert und exakt oder nach der nächstgelegenen Variante mit dem ausgelieferten Bundle-Set abgeglichen (z. B.pt-PT→pt-BR,en-US→en-GB), wobei auf das Quellgebietsschema (en-GB) zurückgegriffen wird. Die CLI löst einmal auf, bevor die Hilfe erstellt wird (Pre-Parse-Argv-Scan), und erneut nach dem Laden der Konfiguration, damituiLanguageangewendet wird (das Flag und die Umgebungsvariable haben weiterhin Vorrang). - Laufzeit (
src/i18n/index.ts): ein minimalest(source, vars)mit{{name}}-Interpolation, indiziert durch die englische Quellzeichenfolge gegen flache pro-Gebietsschema-Bundles insrc/i18n/locales/<code>.json(beim Build nachdist/i18n/localeskopiert). Fehlende Schlüssel oder Bundles geben den Quelltext zurück. Dies ist dasselbe Schlüssel-als-Standard-Modell wie bei UI-Strings — es gibt keinen Hash-Lookup. - Dashboard: der Server stellt
GET /api/ui-i18nbereit, das{ locale, dir, bundle }für das aufgelöste UI-Gebietsschema zurückgibt; das Frontend setzt<html lang>/dirund lokalisiert statisches Markup überdata-i18n*-Attribute. - Dogfooding: die Bundles werden von
pnpm i18n:self(sync-ui --ui-block src/i18n/strings.json) erstellt, das denui-Block der CLI und des Dashboards inai-i18n-tools.config.jsonextrahiert und übersetzt. Katalogschlüssel stammen vont()-Aufrufen übersrc/cli/undsrc/i18n/sowie dendata-i18n*-Markierungen des Dashboards insrc/dashboard-app/index.html.
Erweiterungspunkte
Benutzerdefinierte Funktionsnamen (UI-Extraktion)
Fügen Sie nicht standardmäßige Übersetzungsfunktionsnamen über die Konfiguration hinzu:
{
"ui": {
"uiExtractor": {
"funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
"extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
"htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
}
}
}(ui.reactExtractor ist ein vollständig unterstützter Alias für ui.uiExtractor.)
Fügen Sie .html / .htm zu extensions hinzu, um HTML-Markerattribute während extract zu scannen. ui.uiExtractor.htmlI18nAttributes ist optional und standardmäßig ["data-i18n", "data-i18n-title", "data-i18n-placeholder"]; data-i18n wird dem Element textContent zugeordnet und data-i18n-<attr> wird dem Wert des Attributs zugeordnet (z. B. data-i18n-aria-label).
Benutzerdefinierte Extraktoren
Implementieren Sie ContentExtractor aus dem Paket:
import { BaseExtractor, type Segment } from 'ai-i18n-tools';
class MyExtractor extends BaseExtractor {
readonly name = 'my-format';
canHandle(filepath: string) { return filepath.endsWith('.myext'); }
extract(content: string, filepath: string): Segment[] { /* … */ }
reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}Registrieren Sie benutzerdefinierte Extraktoren, indem Sie die öffentlichen Extraktor-Klassen erweitern, die von 'ai-i18n-tools' exportiert werden (zum Beispiel die Unterklasse MarkdownExtractor). Die CLI verbindet interne Extraktoren intern; es gibt keinen unterstützten tiefen Import von doc-translate.ts.
Benutzerdefinierte Ausgabepfade
Verwenden Sie docsOutput.pathTemplate für jedes Datei-Layout:
{
"docs": [
{
"docsOutput": {
"pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
}
}
]
}Quellbaum
Vollständiges src/-Layout (Dateiebene-Referenz)
src/
├── index.ts Public API re-exports
│
├── cli/
│ ├── index.ts CLI entry point (commander)
│ ├── extract-strings.ts `extract` command implementation
│ ├── mark-html.ts `mark-html` command (insert bare `data-i18n*` markers into HTML)
│ ├── translate-ui-strings.ts `translate-ui` command implementation
│ ├── doc-translate.ts `translate-docs` command (documentation files only)
│ ├── translate-json-run.ts `translate-json` command (`json[]` nested locale bundles)
│ ├── translate-svg.ts `translate-svg` command (SVG files from `config.svg`)
│ ├── write-heading-ids.ts `write-heading-ids` command (markdown heading anchors)
│ ├── bench-models.ts `bench-models` command (per-model translate latency/token/cost benchmark)
│ ├── helpers.ts Shared CLI utilities
│ └── file-utils.ts File collection helpers
│
├── markdown/
│ └── write-heading-ids-core.ts Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│ ├── types.ts Zod schemas + TypeScript types for all config shapes
│ ├── config.ts Config loading, merging, validation, init templates
│ ├── cache.ts SQLite translation cache (node:sqlite)
│ ├── prompt-builder.ts LLM prompt construction for docs and UI strings
│ ├── output-paths.ts Docusaurus / flat output path resolution
│ ├── ui-languages.ts ui-languages.json loading and locale resolution
│ ├── ui-locale.ts Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│ ├── locale-utils.ts BCP-47 normalisation, locale list parsing, script/Han-variant validation
│ └── errors.ts Typed error classes
│
├── extractors/
│ ├── base-extractor.ts Abstract base class for all extractors
│ ├── ui-string-extractor.ts JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│ ├── ui-string-babel.ts Babel `t()` discovery (`extractUiCallsFromFileContent`)
│ ├── ui-string-locations.ts Source locations for extracted UI strings
│ ├── html-i18n-marks.ts HTML `data-i18n*` marker scanner + `mark-html` annotator
│ ├── classify-segment.ts Heuristic segment type classification
│ ├── markdown-extractor.ts Markdown / MDX segment extraction
│ ├── markdown-segment-split.ts Optional segment splitting for long markdown blocks
│ ├── frontmatter-fields.ts Selective YAML front matter field translation
│ ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│ ├── json-extractor.ts Docusaurus catalog JSON extraction (`translate-docs`)
│ ├── nested-json-extractor.ts Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│ └── svg-extractor.ts SVG text extraction
│
├── processors/
│ ├── placeholder-handler.ts Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│ ├── expression-attribute-protection.ts Shared protected attribute/key lists (Astro + MDX JSX)
│ ├── url-placeholders.ts Markdown URL protection/restore
│ ├── admonition-placeholders.ts Docusaurus admonition protection/restore
│ ├── anchor-placeholders.ts HTML anchor / heading ID protection/restore
│ ├── html-tag-placeholders.ts Lowercase HTML tag / comment protection ({{HTM_N}})
│ ├── placeholder-integrity.ts Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│ ├── mdx-placeholders.ts MDX comments, JSX tags, brace expressions, JSX attribute extraction
│ ├── batch-processor.ts Segment → batch grouping (count + char limits)
│ ├── validator.ts Post-translation structural checks
│ └── flat-link-rewrite.ts Relative link rewriting for flat output
│
├── api/
│ ├── llm-client.ts LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│ └── provider-models-catalog.ts Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│ ├── glossary.ts Glossary loading (CSV + auto-build from strings.json)
│ ├── matcher.ts Term hint extraction for prompts
│ └── translation-context.ts contextFiles loader and guidance fingerprints
│
├── runtime/
│ ├── index.ts Runtime re-exports
│ ├── template.ts interpolateTemplate, flipUiArrowsForRtl
│ ├── ui-language-display.ts getUILanguageLabel, getUILanguageLabelNative
│ └── i18next-helpers.ts RTL detection, i18next setup factories
│
├── i18n/ Self-localisation runtime for the tool's own UI
│ ├── index.ts t(source, vars) + bundle/manifest loaders (keyed by English source string)
│ └── locales/ Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│ ├── index.html Translation Dashboard static UI (HTML/CSS/JS)
│ ├── app.js
│ └── styles.css
│
├── server/
│ └── translation-dashboard.ts Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
├── logger.ts Leveled logger with ANSI support
├── hash.ts Segment hash (SHA-256 first 16 hex)
├── table.ts Display-width aware table rendering (CJK/emoji column alignment)
├── load-dotenv.ts Load `.env` / `.env.local` beside the config when no API key is set
└── ignore-parser.ts .translate-ignore file parser