readme-i18n

Überblick über die readme-i18n-Skill

Was readme-i18n leistet

readme-i18n ist eine fokussierte Skill, um aus einer einzelnen GitHub-typischen README.md ein wartbares mehrsprachiges README-Set zu machen. Es geht nicht um allgemeine App-Lokalisierung. Die Kernaufgabe besteht darin, die Quell-README zu übersetzen, Schwesterdateien wie README.zh.md zu erzeugen, Markdown- und Repo-Mechaniken zu erhalten und einen gemeinsamen Sprachumschalter in allen Varianten hinzuzufügen oder zu vereinheitlichen.

Für wen sich readme-i18n eignet

Diese Skill passt für Maintainer, Open-Source-Beitragende und AI-Agents, die an Repository-Dokumentation arbeiten, bei der das eigentliche Ziel nicht einfach „Text übersetzen“ ist, sondern „übersetzte README-Dateien ausliefern, die auf GitHub weiterhin korrekt funktionieren“. Wenn dir wichtig ist, dass Badges, Links, Code-Fences, Dateinamen und Sprachumschalter konsistent bleiben, ist readme-i18n ein besserer Ausgangspunkt als ein generischer Übersetzungsprompt.

Die eigentliche Aufgabe

Die meisten README-Übersetzungen scheitern nicht am Wortschatz, sondern an der Struktur. Nutzer brauchen einen Workflow, der:

• eine Datei als verbindliche Quelle behandelt
• die Abschnittsreihenfolge synchron hält
• Commands, Pfade, Code und Link-Mechaniken unverändert bewahrt
• jede Sprachvariante konsistent aktualisiert
• doppelte oder defekte Sprachumschalter vermeidet

Genau darin liegt der praktische Nutzen der readme-i18n-Skill.

Warum sich diese Skill von einem normalen Prompt unterscheidet

Der wichtigste Unterschied ist die Entscheidungslogik. Die Skill sagt dem Agenten, was exakt erhalten bleiben muss, wann einmalig um Klärung gebeten werden sollte, wie sich Konventionen aus vorhandenen Dateien ableiten lassen und wie ein Sprachumschalter direkt an Ort und Stelle aktualisiert wird, statt einen weiteren zu erzeugen. Die mitgelieferten Referenzen sind gerade für die Einführung besonders nützlich, weil sie das übliche Rätselraten rund um Platzierung des Selectors und Markdown-sichere Übersetzungen deutlich reduzieren.

So verwendest du die readme-i18n-Skill

readme-i18n im Installationskontext

Installiere die Skill aus dem Repository xixu-me/skills in einer beliebigen Skills-kompatiblen Umgebung, die du bereits nutzt. Wenn dein Setup direkte GitHub-Installationen unterstützt, ist das übliche Muster:

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

Wenn deine Umgebung Skills anders verwaltet, nutze die Repo-URL https://github.com/xixu-me/skills/tree/main/skills/readme-i18n als Quellreferenz und lade die Skill aus skills/readme-i18n.

Welche Dateien du vor dem ersten Einsatz lesen solltest

Für diese Skill ist der schnellste und signalstärkste Leseweg:

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

Diese Reihenfolge ist wichtig. SKILL.md erklärt den Workflow, die Selector-Referenz zeigt die erwartete Blockform und Platzierung, und die Preservation-Checkliste legt fest, was unverändert bleiben muss.

Welche Eingaben readme-i18n braucht

Die Skill funktioniert am besten, wenn du Folgendes mitgibst:

• Pfad zur Quell-README, meist README.md
• Quellsprache
• Zielsprache oder Zielsprachen
• ein Glossar oder Begriffe, die nicht übersetzt werden dürfen
• die vorhandene Dateinamenskonvention, falls das Repo READMEs bereits lokalisiert

Wenn du die Zielsprachen weglässt, ist die Skill darauf ausgelegt, zuerst vorhandene Übersetzungsdateien, Selector-Blöcke, Dateinamen, Issues oder Repo-Konventionen zu prüfen. Falls die Sprache danach immer noch nicht klar ist, sollte sie einmal nachfragen, statt Zielsprachen zu erfinden.

Wichtige Default-Annahmen vor dem Start

Die dokumentierten Defaults sind praxisnah und vor der Ausführung von readme-i18n gut zu kennen:

• die README.md im Root ist die verbindliche Quelle, sofern du nichts anderes angibst
• die Quellsprache wird als Englisch angenommen, wenn keine Mehrdeutigkeit besteht
• die Reihenfolge der Abschnitte sollte mit der Quelle übereinstimmen
• vorhandene mehrsprachige Benennungsschemata sollen beibehalten werden, statt ein neues zu erzwingen

Diese Defaults machen die Skill für bestehende Repos deutlich sicherer als eine unpräzise Übersetzungsanfrage.

So promptest du readme-i18n sinnvoll

Eine schwache Anfrage wäre: „Translate my README into Chinese.“

Ein stärkerer readme-i18n usage-Prompt ist:

• translate README.md from English to Simplified Chinese
• create README.zh.md
• preserve commands, paths, badge URLs, code fences, and relative links
• add a top language selector to both files
• keep heading order identical
• do not translate product name AcmeCLI or env vars
• follow any existing filename convention if found

Diese zusätzliche Präzision verbessert die Ausgabe direkt, weil sie zu den Erhaltungs- und Selector-Regeln der Skill passt.

Beispiel-Workflow für Translation

Ein praxisnaher readme-i18n for Translation-Workflow sieht so aus:

1. Die README bestimmen, die als verbindliche Quelle dient.
2. Prüfen, ob bereits übersetzte Varianten existieren.
3. Das Dateinamenschema des Repos und den aktuellen Selector-Stil erkennen.
4. Nur natürlichsprachliche Inhalte übersetzen.
5. Code, Commands, URLs und Dateipfade exakt beibehalten.
6. In jeder Variante einen Selector-Block oben hinzufügen oder vereinheitlichen.
7. Links, Formatierung und Konsistenz über alle Dateien hinweg prüfen.

Das ist das richtige mentale Modell: nicht „Text übersetzen“, sondern „eine README-Familie pflegen“.

So sollte der Sprachumschalter funktionieren

Die stärkste Begleitdatei dieser Skill ist die Selector-Referenz. Sie empfiehlt einen Selector-Block weit oben in jeder README-Variante, meist nach Titel und Badge-Cluster, mit stabilen Markern:

<!-- README-I18N:START -->
<!-- README-I18N:END -->

Diese Marker sind wichtig, weil spätere Durchläufe den Selector damit an Ort und Stelle aktualisieren können. Die aktuelle Sprache sollte hervorgehoben und nicht verlinkt sein; andere Sprachen sollten verlinkt werden. Die Sprachreihenfolge sollte in allen Varianten gleich bleiben.

Was exakt erhalten bleiben muss

Die Preservation-Checkliste ist der entscheidende Teil dieses readme-i18n guide für die Einführung. In der Praxis solltest du Folgendes nicht übersetzen:

• Inline-Code
• Fenced Code Blocks
• Commands, Flags, Env Vars, Pfade
• Badge-URLs und Query-Parameter
• Bildquellpfade
• Tabellenstruktur
• Raw-HTML-Mechaniken

Sichtbaren Fließtext solltest du übersetzen, aber die Mechaniken erhalten, die die README funktional machen.

Welche Repo-Konventionen readme-i18n respektiert

Wenn das Repo bereits ein anderes Benennungsschema als das Standardmuster nutzt:

• README.md
• README.zh.md
• README.es.md

dann sollte die Skill dieses Schema beibehalten. Das ist wichtig für Repos, die bereits teilweise lokalisiert sind, CI-Bezüge haben oder Erwartungen von Mitwirkenden an Dateinamen geknüpft haben.

Wo readme-i18n am meisten Zeit spart

Diese Skill ist besonders wertvoll, wenn einer dieser Einführungsblocker vorliegt:

• du musst mehrere lokalisierte README-Dateien synchron halten
• das Repo hat bereits einen unübersichtlichen oder doppelten Sprachumschalter
• frühere Übersetzungen haben Markdown oder Links beschädigt
• du willst Updates reproduzierbar machen statt einmaliger manueller Edits

Wenn du nur eine grobe private Übersetzung brauchst, um eine README zu verstehen, ist diese Skill wahrscheinlich prozesslastiger, als du es brauchst.

FAQ zur readme-i18n-Skill

Ist readme-i18n gut für Einsteiger?

Ja, wenn dein Ziel ausdrücklich README-Lokalisierung ist. Die Skill grenzt die Aufgabe auf klare Eingaben und Erhaltungsregeln ein, was einfacher ist, als einen eigenen Übersetzungsworkflow zu erfinden. Einsteiger sollten die Ausgabe trotzdem prüfen, besonders Link-Ziele, Überschriften und die Konsistenz des Selectors.

Wann sollte ich readme-i18n statt eines normalen Übersetzungsprompts verwenden?

Nutze readme-i18n, wenn die übersetzte README ins Repo committed werden soll. Ein normaler Prompt übersetzt leicht zu viel, verändert Codebeispiele, beschädigt Badge-Links oder vergisst die Navigation zwischen Dateien. Diese Skill ist die bessere Wahl, wenn Korrektheit der Ausgabe wichtiger ist als reine Geschwindigkeit.

Ist readme-i18n nur für GitHub-Repositories gedacht?

Die Skill ist auf GitHub-typische Repository-READMEs und Markdown-Konventionen optimiert. Sie kann auch auf anderen Git-gehosteten Plattformen helfen, aber ihre Annahmen passen am besten zu Open-Source-Repos auf Basis von README.md und weniger zu vollständigen Doku-Websites oder Produkt-Lokalisierungssystemen.

Unterstützt readme-i18n komplette Dokumentationssätze?

Nein. Das ist ein README-zentrierter Workflow. Wenn du i18n für Website, App oder eine vollständige Dokumentation brauchst, ist die readme-i18n skill zu eng gefasst. Ihre Stärke liegt darin, ein zentrales Repository-Landing-Dokument und seine lokalisierten Schwesterdateien konsistent zu halten.

Welche Sprachen kann ich verwenden?

Die Skill ist sprachagnostisch, solange du die Zielsprachen angibst oder das Repo sie bereits klar erkennen lässt. Sie vermeidet ausdrücklich, Zielsprachen zu erfinden, wenn das Repo dafür nicht genug Hinweise liefert.

Kann readme-i18n ein bestehendes mehrsprachiges README-Setup aktualisieren?

Ja, und genau das ist einer der besten Einsatzzwecke. Die Skill ist darauf ausgelegt, vorhandene Übersetzungsdateien und Selector-Blöcke zu prüfen, Benennungskonventionen beizubehalten und einen bestehenden Umschalter zu vereinheitlichen, statt einen zweiten hinzuzufügen.

Wann ist readme-i18n keine gute Wahl?

Lass sie weg, wenn:

• du nur eine informelle Leseübersetzung willst
• deine Dokumentation außerhalb der README liegt
• du Terminologiemanagement über einen großen Doku-Bestand brauchst
• dein Repo keine Sprachumschalter-Links in README-Dateien haben möchte

In solchen Fällen passt ein leichterer Prompt oder ein breiterer Doku-Lokalisierungsworkflow meist besser.

So verbesserst du die readme-i18n-Skill

Gib readme-i18n stärkere Quell-Constraints

Bessere Eingaben führen zu besseren README-Varianten. Gib möglichst an:

• den exakten Quell-Dateipfad
• die exakten Ziel-Locale(s)
• Begriffe, die niemals übersetzt werden dürfen
• bevorzugte Autonyme für Sprachnamen
• ob vorhandene Übersetzungsdateien überschrieben oder nur aktualisiert werden sollen

So reduzierst du den häufigsten Fehlerfall: inhaltlich korrekte Übersetzung, aber falsches Repo-Verhalten.

Gib ein Glossar für Namen und Fachbegriffe mit

Wenn deine README Produktnamen, CLI-Commands, Package-Namen oder domänenspezifische Terminologie enthält, führe sie explizit auf. readme-i18n versucht zwar bereits, Literale zu erhalten, aber ein kurzes Glossar verbessert die Konsistenz in Überschriften, Feature-Beschreibungen und Beispielen.

Sag der Skill, was sie nicht anfassen darf

Eine der besten Möglichkeiten, readme-i18n usage zu verbessern, ist das Setzen klarer Grenzen:

• keep all code blocks byte-for-byte identical
• preserve relative links
• do not rename files unless asked
• do not change badge targets
• do not reorder sections

Diese Anweisungen passen eng zur Preservation-Checkliste und verhindern „hilfreiche“, aber schädliche Änderungen.

Prüfe die Selector-Platzierung vor dem Commit

Ein häufiges Ausgabeproblem ist ein ungeschickt platzierter oder doppelter Sprachumschalter. Vergleiche den erzeugten Selector mit references/language-selector-reference.md und prüfe:

• pro Datei existiert nur ein Selector
• die Platzierung ist über alle Varianten hinweg konsistent
• die aktuelle Sprache ist fett gesetzt und nicht verlinkt
• die Links zeigen auf die tatsächlichen Schwesterdateien

Das ist ein kleiner Review-Schritt mit hoher Wirkung.

Prüfe lokalisierte Überschriften und Anchors

Übersetzte Überschriften können das Verhalten generierter Anchors auf Plattformen verändern, die Fragment-IDs aus dem Überschriftentext ableiten. Die Skill versucht, die Überschriftenhierarchie zu erhalten, trotzdem solltest du interne Überschriftenlinks nach der Übersetzung testen, besonders bei langen READMEs.

Arbeite von Quelländerungen aus, nicht mit Ad-hoc-Edits

Für die langfristige Pflege solltest du README.md als verbindliche Quelle beibehalten und readme-i18n nach Änderungen an der Quelle erneut ausführen, statt jede lokalisierte Datei unabhängig per Hand zu bearbeiten. So bleiben Abschnittsreihenfolge, Selector-Inhalte und Terminologie über die Zeit hinweg konsistent.

Nutze nach dem ersten Durchlauf einen Side-by-Side-Check

Nach dem ersten Durchlauf solltest du Quell- und Zieldateien vergleichen auf:

• gleiche Anzahl an Abschnitten
• gleiche Anzahl an Code Blocks
• gleiche Tabellen- und Listenstruktur
• gleiche Bilder und Badges
• funktionierende Selector-Links

So lassen sich strukturelle Regressionen schneller erkennen, als wenn du jeden Satz erneut liest.

Mach künftige Durchläufe besser mit expliziten Repo-Konventionen

Wenn dein Repo ein nicht standardmäßiges mehrsprachiges Muster hat, benenne es beim nächsten Aufruf von readme-i18n direkt im Prompt. Beispiele:

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

Die Skill wird deutlich verlässlicher, wenn Repo-Konventionen benannt statt nur aus dem Bestand abgeleitet werden.