⚠️ SUPERSEDED (2026-06-07). Dieser Entwurf ist überholt und wird nicht umgesetzt. Maßgeblich ist: ../../../../docs/superpowers/specs/2026-06-07-english-com-localization-design.md (Projekt-Root). Abweichende Entscheidungen dort: language+translation_key-Spalten statt Übersetzungstabellen, eigene .com-Domain mit englischen Pfaden statt /en/-Subpfad, Per-Sprache-Build (SITE_LANG), kein EN-Audio. Nur zur Historie behalten.

Mehrsprachigkeit (DE → EN) — Design & Aufwandsplan

Datum: 2026-06-07 Stack: Quarkus-Backend (Panache/Postgres, OpenAI via LangChain4j) · VitePress-Frontend (SSG) · Vercel Entscheidungen: Start nur Englisch (Architektur erweiterbar) · kompletter Backlog übersetzen (mit Staffelung) · Plan jetzt, Umsetzung koordiniert mit Backend-Parallel-Agent.

Leitidee

Englisch entsteht durch KI-Übersetzung der bestehenden deutschen Inhalte (1:1-Zuordnung DE↔EN). Deutsch bleibt die kanonische Sprache; Englisch hängt als Übersetzung daran. Das englische Audio wird über die bestehende OpenAI-TTS-Pipeline aus dem übersetzten Text erzeugt (Stimme onyx ist mehrsprachig — kein neuer Provider).

Routing: eine Domain, Englisch unter /en/ (Googles Empfehlung; einfachstes hreflang, ein Search-Console-Account). .com als Marken-Schutz sichern und per 301 auf .de leiten.

---

Datenmodell (Backend)

Aktuell hat Article kein locale-Feld (verifiziert). Empfehlung: Übersetzungstabelle statt locale-Spalte — minimiert Eingriffe in die bestehende deutsche API und ist erweiterbar.

ArticleTranslation
  id
  article_id        FK -> Article (die deutsche Kanon-Zeile)
  locale            'en' (später 'es', 'fr', ...)
  slug              eigener englischer Slug (SEO)
  title, excerpt, content   übersetzt
  audio_url         eigene EN-MP3
  status            DRAFT/PUBLISHED (eigene Staffelung möglich)
  published_at      eigener Timestamp (Staffelung gegen Content-Farm-Signal)
  UNIQUE(article_id, locale), UNIQUE(slug, locale)

Analog: NewsTranslation, GlossaryTranslation, PersonTranslation. DE-Inhalte bleiben unverändert auf den Basistabellen → bestehende API/Build brechen nicht.

Übersetzungs-Pipeline (Backend)

• Neuer TranslationAgent (LangChain4j, wie die anderen Agenten): übersetzt title/excerpt/content markdown-erhaltend, mit konsistenter stoischer Terminologie (Glossar als Referenz, damit Fachbegriffe stabil bleiben).
• Englischer Slug aus dem EN-Titel generieren (nicht den deutschen Slug wiederverwenden).
• EN-Audio: bestehende AudioGenerationService auf den EN-Text → EN-MP3. Voice onyx (oder pro Locale konfigurierbar via TTS_VOICE_EN).
• Trigger:
  • Backlog (einmalig): Admin-getriggerter Batch-Job übersetzt alle 111 Artikel + News + Glossar + Personen. Rate-limit-/kosten-schonend gestaffelt.
  • Laufend: Hook in ArticlePipeline — nach DE-Veröffentlichung EN-Übersetzung + EN-Audio einreihen.

API (Backend)

• locale-Parameter: /api/articles?locale=en (Default de). Für den EN-Bereich nur Artikel mit vorhandener EN-Übersetzung ausliefern.
• Antwort enthält die Slug-Paarung (DE-Slug ↔ EN-Slug) für hreflang im Frontend.
• Analog news/glossary/persons.

Frontend (VitePress i18n)

• locales-Config: root = de, en = englische Oberfläche (setzt lang, Routing /en/).
• Dynamischer Content: Loader & [slug].paths.ts pro Locale (fetch mit ?locale=en), bauen /en/artikel/[slug] etc.
• hreflang (kritisch): buildPageHead erweitern um <link rel="alternate" hreflang="de|en|x-default"> je Übersetzungspaar. Selbst-referenzierende Canonicals pro Sprachversion.
• UI-Strings & statische Seiten auf EN: Nav, Footer, Buttons, Vue-Komponenten (SearchOverlay, BookmarkButton, ArticleFeedback, „Meine Liste"), und EN-Versionen von impressum/datenschutz/ueber-uns/ki-transparenz/benachrichtigungen.
• Pro-Locale-Artefakte: Sitemap (VitePress multi-locale), RSS, Suchindex, llms.txt, News-Sitemap — jeweils EN-Variante.

SEO

• hreflang-Cluster (de, en, x-default) auf jeder Seite.
• Eine Domain → ein Search-Console-Property; nur Sitemaps neu einreichen.
• Content-Farm-Risiko mindern (auch bei Komplett-Backlog): EN-Artikel mit gestaffelten published_at ausrollen statt 111× gleicher Minute; korrektes hreflang signalisiert „Übersetzung, kein Duplikat"; ki-transparenz deklariert KI-Einsatz (vorhanden).

Aufwand & Kosten (grob)

Bereich	Aufwand
Backend: Schema + Migration (4 Translation-Tabellen)	~2–3 Tage
Backend: TranslationAgent + Pipeline-Integration	~3–5 Tage
Backend: Backlog-Batch-Job (gestaffelt)	~1–2 Tage
Backend: API locale-Support	~2–3 Tage
Backend: EN-Audio-Verdrahtung	~1 Tag
Frontend: VitePress locales + Loader/paths pro Locale	~3–4 Tage
Frontend: UI-Strings + EN-.md-Seiten	~2–3 Tage
Frontend: hreflang + EN-RSS/Sitemap/llms	~2 Tage
Summe	~3–4 Wochen, backend-dominiert

Compute-Kosten: Backlog 111 Artikel × (~$0,02 Übersetzung + ~$0,09 Audio) ≈ ~$12 einmalig; laufend ~$0,11 pro Artikel/Tag. Vernachlässigbar.

Phasen (empfohlene Reihenfolge)

1. Backend-Fundament: Schema + Translation-Tabellen + API-locale-Support (ohne Inhalte).
2. Übersetzungs-Pipeline: TranslationAgent + EN-Audio; an einem Artikel verifizieren.
3. Backlog-Batch: alle Inhalte übersetzen (gestaffelte published_at).
4. Frontend-i18n: locales, Loader/paths, UI-Strings, EN-.md-Seiten.
5. SEO-Finish: hreflang, EN-Sitemap/RSS/llms, Search-Console-Sitemaps neu einreichen, .com sichern + 301 → .de.

Koordination

Phasen 1–3 liegen im Backend (Domäne des Parallel-Agenten, Professionalisierungs-Phase) — Kollisionsrisiko an Entities/Pipeline. Phasen 4–5 sind Frontend und kann ich übernehmen. Empfehlung: Backend-Schema/Agent mit dem Parallel-Agenten abstimmen, Frontend separat.

Bewusst NICHT

• Keine separate .com-Content-Domain (mehr Arbeit, SEO nicht besser als /en/).
• Keine Live-Maschinen­übersetzung im Browser (Qualität/SEO schlecht) — Übersetzung passiert serverseitig, einmal, und wird gespeichert.