mikaellolbatera159-stack/localizations

Inhalt in vorgegebene Sprachen lokalisieren

Eine Fertigkeit, die Inhalte in vorgegebene Sprachen lokalisiert.

Funktionsweise

Die Fertigkeit nimmt Eingabeinhalte und eine Liste von Zielsprachen entgegen. Anschließend übersetzt sie den Inhalt in jede angegebene Sprache und erstellt lokalisierte Versionen.

Inhaltsstruktur

.
└── docs/                         ← Workshop-Inhalte (Quelle + Sprachausgaben)
    ├── README.md                 ← Startseite (Quelle; slug: index)
    ├── <category>/               ← Englische Workshop-Kategorie
    │   ├── README.md             ← Kategorie-Startseite (Quelle; slug: <category>)
    │   └── <workshop>/
    │       ├── README.md         ← Workshop-Startseite (Quelle; slug: <category>/<workshop>)
    │       └── *.md
    ├── _images/              ← Gemeinsame Assets (nicht lokalisiert)
    └── <locale>/             ← Lokalisierte Ausgabe, direktes Kind von docs/
        ├── README.md         ← Sprach-Startseite (slug: <locale>)
        └── <category>/
            ├── README.md         ← Lokalisierte Kategorie-Startseite (slug: <locale>/<category>)
            └── <workshop>/
                ├── README.md     ← Lokalisierte Workshop-Startseite (slug: <locale>/<category>/<workshop>)
                └── *.md

Eingabeinhalte

Folgende Inhalte sind für die Lokalisierung vorgesehen:

• Alle englischen Markdown-Dateien unter docs/ und deren Unterverzeichnissen — die Site-Startseite (docs/README.md), Kategorie-Startseiten und Workshop-Lektionen (docs/<category>/<workshop>/**/*.md).

Behandle nicht _images/ (gemeinsame Assets) oder ein konfiguriertes Sprachstammverzeichnis als Quelleingabe.

Dateien, die sich bereits unter docs/<locale>/ befinden, sind Ausgaben, keine Eingaben — behandle konfigurierte Sprachstammverzeichnisse niemals als erneut zu lokalisierende Quellinhalte.

Zielsprachen

Die Zielsprachen werden im rules-Verzeichnis als Markdown-Dateien dieser Fertigkeit definiert (z. B. rules/ko-kr.md). Um zu bestimmen, welche Sprachen verarbeitet werden sollen, liste die Dateien in rules/ auf: Jede <locale>.md-Datei entspricht genau einer unterstützten Zielsprache. Jede Sprache hat ihre eigenen Regeln und Richtlinien für die Übersetzung, um sicherzustellen, dass der lokalisierte Inhalt für die Zielgruppe angemessen ist.

Sprachkennungen verwenden Kleinbuchstaben mit einem Bindestrich (z. B. ko-kr). Dies ist die kanonische Schreibweise sowohl für den Dateinamen der Regeln als auch für das Ausgabeverzeichnis in dieser Fertigkeit; halte sie konsistent.

Ausgabeinhalte

Alle lokalisierten Workshop-Inhalte werden direkt im content-Verzeichnis docs/ im Repository-Stammverzeichnis gespeichert, wobei jede Sprache ein eigenes Unterverzeichnis hat. Koreanische Inhalte werden beispielsweise in docs/ko-kr/ gespeichert.

Sprachverzeichnisse müssen direkte Kinder von docs/ sein, damit Starlight (konfiguriert in website/astro.config.mjs) sie erkennt und seinen Sprachauswahlschalter anzeigt. Füge kein Zwischenverzeichnis localizations/ hinzu.

Lokalisierungsprozess

Es gibt drei Fälle für die Lokalisierung. Um zu ermitteln, welcher Fall zutrifft, vergleiche den Quellbaum mit dem vorhandenen docs/<locale>/-Baum und verwende die Git-Historie der Quelldateien, um Änderungen zu erkennen:

• Original vorhanden, keine lokalisierte Version für die Sprache: Erstelle ein neues lokalisiertes Dokument.
• Sowohl Original als auch lokalisierte Version vorhanden: Vergleiche den Quellbaum mit docs/<locale>/ und führe git diff (oder git log) für die Quelldatei aus, um herauszufinden, was sich geändert hat, seit die lokalisierte Version zuletzt erstellt wurde. Aktualisiere nur die betroffenen Abschnitte des lokalisierten Dokuments; übersetze unveränderte Abschnitte nicht unnötig neu.
• Lokalisierte Version vorhanden, aber das Original wurde gelöscht: Lösche das verwaiste lokalisierte Dokument (und entferne nun leere Sprachunterverzeichnisse).

Der Prozess läuft in zwei Durchgängen ab. Zuerst wird der Inhalt analysiert, um Schlüsselphrasen und Kontext zu identifizieren. Dann führt der translator-Agent die erste Lokalisierung durch, gefolgt von einem Überprüfungs- und Verfeinerungsdurchgang durch den evaluator-Agenten, um Qualität und Konsistenz sicherzustellen.

Die „Agenten“ translator und evaluator sind Rollen/Personas, keine externen Tools. Falls keine dedizierten Unteragenten verfügbar sind, führe sie als sequenzielle Personas aus: Nimm zuerst die Rolle des Übersetzers ein, um den Entwurf zu erstellen, dann die Rolle des Evaluators, um diesen Entwurf anhand der Sprachregeln zu kritisieren und zu verfeinern. Wiederhole den Verfeinerungszyklus, bis die Kriterien des Evaluators erfüllt sind.

Erhaltung von Markdown und Formatierung

Unabhängig von der Sprache müssen die folgenden Elemente exakt erhalten und nicht übersetzt werden:

• YAML-Frontmatter-Schlüssel (übersetze nur Werte, wo angemessen, z. B. einen title). Ausnahme — der slug-Schlüssel auf Startseiten (README.md): Die Site routet jede Ordner-Startseite über ihren slug, daher muss eine lokalisierte Startseite einen sprachpräfixierten Slug anstelle des englischen tragen. Schreibe ihn um: Eine Sprachstammseite (docs/<locale>/README.md) verwendet slug: <locale>, eine lokalisierte Kategorie-Startseite verwendet slug: <locale>/<category> und eine lokalisierte Workshop-Startseite verwendet slug: <locale>/<category>/<workshop>. Kopiere niemals einen englischen Startseiten-Slug wörtlich in eine lokalisierte Datei, da dies mit der englischen Route kollidieren würde.
• Code-Blöcke und Inline-Code, einschließlich Variablen-, Funktions- und Befehlsnamen.
• URLs und externe Linkziele.
• HTML-Tags, Markdown-Struktur, Tabellen und Hinweis-Markierungen.

Übersetze menschliche Prosa, einschließlich Kommentaren innerhalb von Codeblöcken, wenn diese erklärend sind (gemäß den Sprachregeln). Behalte die Reihenfolge der Überschriften und die Dokumentstruktur stabil bei.

Überschriftanker folgen dem lokalisierten Text. Wenn eine Überschrift übersetzt wird, ändert sich ihr automatisch generierter Anker/Slug entsprechend – das ist beabsichtigt. Die Anforderung ist, dass dokumentinterne Ankerlinks weiterhin funktionieren: Wenn du eine Überschrift übersetzt, aktualisiere jeden Seitenlink, der darauf verweist (](#...)), auf den neuen Slug der lokalisierten Überschrift. Hinterlasse keinen Link, der auf den ursprünglichen englischen Slug zeigt, sobald die Überschrift übersetzt ist, und behalte keinen englischen Anker bei, der nicht mehr zu seiner Überschrift passt. Anker, die auf nicht lokalisierte Dateien (oder externe URLs) verweisen, behalten ihr ursprüngliches Ziel bei.

Bild- und Asset-Pfade zeigen auf die Original-Assets, es sei denn, ein lokalisiertes Asset existiert. Da lokalisierte Dateien unter docs/<locale>/ liegen, schreibe quellrelative Pfade nach Bedarf um, sodass sie weiterhin auf das gemeinsame Asset auflösen (z. B. verwendet eine Lektion unter docs/<locale>/real-world-development/app/2-foo.md ../../../_images/x.png, um docs/_images/ zu erreichen). Zeige nur auf ein lokalisiertes Asset, wenn ein entsprechendes übersetztes Bild tatsächlich im Sprachbaum existiert. In jedem Fall muss der Link auf eine reale Datei verweisen.

Übersetzer-Agent

Verwende den translator-Agenten, um die Lokalisierung durchzuführen. Er sollte die Regeln und Richtlinien befolgen, die für jedes Zielsprachendokument im rules-Verzeichnis definiert sind.

Evaluator-Agent

Verwende den evaluator-Agenten, um die Qualität des lokalisierten Inhalts zu bewerten. Der Evaluator prüft auf Genauigkeit, kulturelle Relevanz und Gesamtqualität, gemäß den Regeln und Richtlinien der Zielsprache im rules-Verzeichnis.

Der Evaluator bewertet das lokalisierte Dokument anhand der Evaluator-Bewertungsmatrix der Sprache (definiert in der rules/<locale>.md-Datei der Sprache). Die Matrix verwendet zwei Stufen: Stufe A – harte Fehlerkriterien, die eine Bewertung von 5 erfordern, und Stufe B – abgestufte Kriterien (1–5), die eine Bewertung von 4 oder 5 erfordern. Ein Dokument besteht nur, wenn jedes anwendbare Stufe-A-Kriterium eine 5 erreicht und jedes anwendbare Stufe-B-Kriterium ≥ 4 erreicht. Falls etwas zu kurz kommt, gib das Dokument mit spezifischen Anmerkungen an den Übersetzer zurück und wiederhole den Übersetzungs- → Evaluierungszyklus, bis es besteht, und eskaliere an einen Menschen nach Erreichen der Iterationsgrenze der Matrix.

Gebote und Verbote

• Tue die Lokalisierung nur für die Zielsprachen durchführen, die im rules-Verzeichnis definiert sind (eine <locale>.md-Datei pro unterstützter Sprache). Führe keine Lokalisierung für nicht unterstützte Sprachen durch.
• Tue Markdown-Struktur, Code, externe Link-/URL-Ziele und Frontmatter-Schlüssel exakt erhalten (siehe Erhaltung von Markdown und Formatierung).
• Tue Überschriftanker dem lokalisierten Überschriftentext folgen lassen und dokumentinterne Ankerlinks aktualisieren, damit sie den neuen Slugs entsprechen und weiterhin funktionieren (siehe Erhaltung von Markdown und Formatierung).
• Tue Bild- und Asset-Pfade auf die Original-Assets zeigen lassen (den relativen Pfad nach Bedarf umschreiben, damit er von docs/<locale>/ aus auflöst), es sei denn, ein entsprechendes lokalisiertes Asset existiert (siehe Erhaltung von Markdown und Formatierung).
• Tue das Quellverzeichnislayout unter docs/<locale>/ spiegeln.
• Tue nicht konfigurierte Sprachstammverzeichnisse als Quelleingabe behandeln.
• Tue nicht Inhalte umordnen oder umstrukturieren; behalte Überschriften und ihre Reihenfolge stabil bei.
• Tue nicht Code, Befehle oder Bezeichner übersetzen; übersetze nur erklärende Prosa und Code-Kommentare.