readme-i18n

readme-i18n スキルの概要

readme-i18n ができること

readme-i18n は、1 つの GitHub スタイルの README.md を、保守しやすい多言語 README セットへ変換することに特化したスキルです。一般的なアプリのローカライズ向けではありません。中核となる役割は、元の README を翻訳し、README.zh.md のような兄弟ファイルを作成し、Markdown とリポジトリ上の仕組みを壊さずに保ち、さらに全言語版で共通の言語セレクターを追加または正規化することです。

readme-i18n を使うべき人

このスキルは、メンテナー、オープンソース貢献者、そしてリポジトリのドキュメントを扱う AI エージェントに向いています。目的が単なる「文章の翻訳」ではなく、「GitHub 上でそのまま機能する翻訳済み README を公開する」ことである場合に特に適しています。バッジ、リンク、コードフェンス、ファイル名、言語切り替えの一貫性を重視するなら、readme-i18n は汎用的な翻訳プロンプトより良い出発点です。

本当に解決したい仕事

README 翻訳が失敗しやすいのは、語彙ではなく構造です。ユーザーが必要としているのは、次の条件を満たすワークフローです。

• 1 つのファイルを source-of-truth として扱う
• セクション順を揃えたままにする
• コマンド、パス、コード、リンクの仕組みを保持する
• すべての言語版を一貫して更新する
• 言語セレクターの重複や破損を避ける

これこそが readme-i18n skill の実用的な価値です。

通常のプロンプトと違う理由

このスキルの最大の違いは、判断ロジックにあります。何を厳密に保持すべきか、どのタイミングで一度だけ確認を入れるべきか、既存ファイルからどう慣例を推測するか、そして新しいセレクターを増やすのではなく既存のものをその場で更新する方法まで、エージェントに指示します。特に付属の参照資料は導入時に有用で、セレクターの配置や、翻訳しても安全な Markdown の扱いについて、ありがちな手探りを減らしてくれます。

readme-i18n スキルの使い方

readme-i18n のインストール前提

このスキルは、xixu-me/skills リポジトリから、すでに使っている Skills 対応環境へインストールします。環境が GitHub からの直接インストールに対応しているなら、一般的な形は次のとおりです。

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

環境によってスキル管理の方法が異なる場合は、https://github.com/xixu-me/skills/tree/main/skills/readme-i18n を参照元として使い、skills/readme-i18n から読み込んでください。

最初に読むべきファイル

このスキルを使う際、最短で要点をつかめる読み順は次のとおりです。

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

この順番には意味があります。SKILL.md で全体のワークフローを把握し、selector reference で想定されるブロック形状と配置を確認し、preservation checklist で「変更してはいけないもの」を押さえます。

readme-i18n に必要な入力

このスキルは、次の情報を与えると最も安定して動きます。

• source README のパス。通常は README.md
• ソース言語
• ターゲット言語またはターゲット言語群
• 用語集、または翻訳しない語
• すでに README ローカライズを行っているリポジトリなら、その既存ファイル名ルール

ターゲット言語を省略した場合、スキルはまず既存の翻訳ファイル、セレクター、ファイル名、issue、リポジトリ慣例を確認する設計です。それでも言語が特定できないなら、勝手にターゲットを決めず、一度だけ確認を返すべきです。

事前に知っておくとよいデフォルト動作

readme-i18n を実行する前に知っておきたい、実用的な既定値は次のとおりです。

• 指定がなければ、ルートの README.md を source-of-truth とみなす
• 曖昧でない限り、ソース言語は英語とみなす
• セクション順は元ファイルに揃える
• 既存の多言語ファイル命名規則があれば、新しい方式を押し付けずそれを維持する

これらの前提があるため、まっさらな翻訳依頼よりも、既存リポジトリに対して安全に使いやすくなっています。

readme-i18n にうまく指示する方法

弱い依頼は次のようなものです。「Translate my README into Chinese.」

より良い readme-i18n usage のプロンプトは、たとえば次のようになります。

• README.md を英語から簡体字中国語へ翻訳する
• README.zh.md を作成する
• コマンド、パス、badge URL、code fence、relative link は保持する
• 両方のファイルの先頭に言語セレクターを追加する
• 見出し順は完全に同じにする
• product name AcmeCLI と env var は翻訳しない
• 既存のファイル名ルールがあればそれに従う

ここまで具体的にすると、スキルの保持ルールやセレクタールールと噛み合うため、出力品質が直接上がります。

翻訳時の実践ワークフロー

実用的な readme-i18n for Translation の流れは次のとおりです。

1. source-of-truth となる README を特定する。
2. すでに翻訳版が存在するか確認する。
3. リポジトリのファイル名パターンと言語セレクターの現在の形式を検出する。
4. 人間向けの自然言語部分だけを翻訳する。
5. コード、コマンド、URL、ファイルパスはそのまま保持する。
6. 各バリアントの上部付近に、1 つの selector block を追加または正規化する。
7. リンク、書式、全ファイル間の整合性を確認する。

考え方として正しいのは、「テキストを翻訳する」ではなく、「README のファミリーを維持する」です。

言語セレクターのあるべき動き

このスキルでもっとも強力な補助資料は selector reference です。推奨されるのは、各 README バリアントの上部、通常はタイトルとバッジ群の直後あたりに、次の安定したマーカーを含む 1 つの selector block を置くことです。

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

このマーカーが重要なのは、将来の実行時にセレクターをその場で更新できるからです。現在の言語は強調表示し、リンクは付けません。その他の言語にはリンクを付けます。言語の並び順は、すべてのバリアントで統一してください。

必ずそのまま保持すべきもの

この readme-i18n guide で導入判断の鍵になるのが preservation checklist です。実運用では、次のものは翻訳しないでください。

• inline code
• fenced code blocks
• commands, flags, env vars, paths
• badge URLs and query params
• image source paths
• table structure
• raw HTML mechanics

目に見える説明文は翻訳して構いませんが、README を機能させている仕組みはそのまま残す必要があります。

readme-i18n が尊重する一般的なリポジトリ慣例

リポジトリがすでにデフォルト以外の命名規則を使っている場合、たとえば次のような形でも、

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

スキルはそのルールを維持すべきです。これは、すでに部分的なローカライズが進んでいるリポジトリや、CI 参照、コントリビューターの期待がファイル名に結び付いているケースで特に重要です。

readme-i18n が最も時間を節約できる場面

このスキルの価値が特に高いのは、次のような導入上のつまずきがあるときです。

• 複数のローカライズ README を同期した状態で維持したい
• リポジトリ内の言語切り替えが重複していたり乱れていたりする
• 過去の翻訳で Markdown やリンクが壊れたことがある
• 単発の手作業ではなく、繰り返し更新できる形にしたい

逆に、README の内容をざっくり私的に理解したいだけなら、このスキルは少し手順が多すぎるかもしれません。

readme-i18n スキル FAQ

readme-i18n は初心者にも向いている？

はい。目的が README のローカライズに絞られているなら、初心者にも使いやすい部類です。必要な入力と保持ルールが明確なので、自分で翻訳フローを組み立てるより進めやすくなります。ただし、リンク先、見出し、セレクターの整合性については、初心者でも最終出力を確認する必要があります。

通常の翻訳プロンプトではなく readme-i18n を使うべきなのはいつ？

翻訳した README を実際にリポジトリへコミットするなら、readme-i18n を使うべきです。通常のプロンプトは、翻訳しすぎたり、コード例を書き換えたり、badge link を壊したり、ファイル間ナビゲーションを忘れたりしがちです。速度よりも出力の正しさを優先したい場面で、このスキルは強みを発揮します。

readme-i18n は GitHub リポジトリ専用？

GitHub スタイルのリポジトリ README と Markdown 慣例に最適化されています。他の Git ホスティング環境でも役立つ可能性はありますが、前提はフル機能の docs サイトや製品ローカライズ基盤ではなく、README.md を中心としたオープンソースリポジトリに最も合っています。

readme-i18n はドキュメント一式全体に対応している？

いいえ。これは README に特化したワークフローです。Web サイト、アプリ、あるいはドキュメント一式全体の i18n が必要なら、readme-i18n skill では対象が狭すぎます。強みは、1 つのリポジトリの入口となるドキュメントと、その各言語版の整合性を保つことにあります。

どの言語に使える？

ターゲット言語を明示するか、あるいはリポジトリ側で十分に示されていれば、言語自体は問いません。このスキルは、根拠が足りないのにターゲット言語を勝手に作り出さないことを明確に重視しています。

既存の多言語 README 構成を readme-i18n で更新できる？

はい。むしろそれは、このスキルの最良のユースケースの 1 つです。既存の翻訳ファイルやセレクターを調べ、命名規則を維持しつつ、2 つ目のスイッチャーを増やすのではなく、既存の切り替えを正規化するよう設計されています。

readme-i18n が向かないのはどんなとき？

次のような場合は見送ったほうがよいでしょう。

• 気軽に読むための非公式な翻訳だけが欲しい
• ドキュメントの主戦場が README の外にある
• 大規模なドキュメント群全体で用語管理が必要
• リポジトリ方針として README に言語セレクターのリンクを置きたくない

こうしたケースでは、より軽いプロンプトか、README 以外も含む広いドキュメントローカライズの流れのほうが適しています。

readme-i18n スキルを改善する方法

readme-i18n により強いソース制約を与える

入力が具体的なほど、生成される README バリアントの品質は上がります。次の情報を含めてください。

• 正確なソースファイルパス
• 正確なターゲット locale
• 絶対に翻訳しない語
• 言語名の preferred autonyms
• 既存の翻訳ファイルを上書きするのか、更新だけにするのか

これにより、もっともよくある失敗、つまり「翻訳自体は正しいのにリポジトリ上の振る舞いが間違っている」という問題を減らせます。

名前や技術用語の glossary を渡す

README に product name、CLI command、package 名、またはドメイン固有の用語が含まれているなら、明示的に一覧化してください。readme-i18n はもともとリテラルの保持を重視しますが、短い glossary があるだけでも、見出し、機能説明、例の一貫性がかなり高まります。

触ってほしくない範囲を明言する

readme-i18n usage を改善する最善策の 1 つは、変更禁止の境界をはっきり伝えることです。

• すべての code block を byte-for-byte identical に保つ
• relative link を保持する
• 指示がない限りファイル名を変更しない
• badge のリンク先を変えない
• セクション順を並べ替えない

これらは preservation checklist と非常に相性がよく、「親切なつもりで有害な編集」を防げます。

コミット前に selector の配置を確認する

よくある出力上の問題は、言語切り替えの位置が不自然だったり、二重に入ってしまったりすることです。生成された selector を references/language-selector-reference.md と見比べ、次を確認してください。

• 各ファイルに selector が 1 つしかない
• 配置がすべてのバリアントで揃っている
• 現在の言語はリンクではなく太字になっている
• リンク先が実在する兄弟ファイル名を指している

小さな確認作業ですが、効果は大きいです。

ローカライズ後の見出しとアンカーを確認する

翻訳された見出しは、見出しテキストから fragment ID を生成するプラットフォームでは、anchor の挙動を変えることがあります。スキルは見出し階層の維持を目指しますが、翻訳後は内部リンク、とくに長い README での見出しリンクを実際に確認してください。

場当たり的な編集ではなく source 変更から反映する

長期運用では、README.md を source-of-truth として維持し、各ローカライズ版を個別に手で直し続けるのではなく、ソース更新を起点に readme-i18n を再実行するのが基本です。そうすることで、時間が経ってもセクション順、selector 内容、用語を揃えやすくなります。

初回実行後は左右比較で検証する

最初の生成後は、ソースとターゲットのファイルを並べて次を確認してください。

• セクション数が同じ
• code block 数が同じ
• table と list の構造が同じ
• image と badge が同じ
• selector のリンクが機能している

全文を読み返すより、こうした構造比較のほうが崩れを素早く見つけやすいです。

次回以降の実行ではリポジトリ慣例を明示する

リポジトリに標準的でない多言語パターンがあるなら、次に readme-i18n を呼び出すときはプロンプト内ではっきり指定してください。たとえば次のような形です。

• “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”

推測に任せるのではなく、リポジトリ慣例を名前付きで伝えたほうが、このスキルの信頼性は大きく上がります。