readme-i18n

リポジトリの仕組みを壊さずに、リポジトリの README.md をローカライズします。

既定の作業は翻訳と反映です。

• ソースとなる README を読みます
• README.zh.md のようなローカライズ版のファイルを作成します
• GitHub Flavored Markdown の構造と、リポジトリ固有のトークンを維持します
• すべての翻訳版の上部付近に、共通の言語セレクターを追加または更新します

このスキルは、多言語 README のワークフローを対象としたもので、一般的なウェブサイトやアプリの i18n を対象としていません。

入力

次の入力がある場合は、それを使用します。

• ソース README のパス。既定値は README.md
• ソース言語。既定値は推定、または英語
• 1 つ以上の対象言語
• 用語集、または翻訳しない用語のリスト（任意）
• リポジトリですでに異なる多言語命名パターンが使われている場合の、任意のファイル名指定

対象言語が指定されていない場合は、既存の翻訳済みファイル、セレクター、ファイル名、Issue、または過去のリポジトリの慣例を確認します。それでも対象言語が不明な場合は、一度だけ質問します。対象言語を勝手に決めてはいけません。

既定値と判断ルール

• ユーザーが明示的に別の指定をしない限り、ルートの README.md をソースとして扱います。
• ソース言語が曖昧な場合は、一度だけ質問します。それ以外の場合は英語とみなします。
• セクションの順序はソース README に合わせます。有効なローカライズ済みアンカーを作成するために必要な場合に限り、見出しの表現をわずかに調整します。
• リポジトリに既存の確立された命名パターンがあり、それを維持すべき場合を除き、README.<bcp47-tag>.md という命名規則でローカライズ版を出力します。
• 既存の言語セレクターはその場で更新します。重複して追加してはいけません。
• 人間の言語で書かれた内容だけを翻訳します。
• プロジェクト名、パッケージ名、コマンド、CLI フラグ、オプション名、環境変数、URL、ファイルパス、インラインコード、コードフェンス、HTML 属性、バッジや画像の URL は維持します。
• バッジの代替テキストや表示ラベルは、変更によってバッジの URL、クエリパラメーター、画像ソースを変更する必要がない場合に限り翻訳できます。
• 用語集や翻訳しない用語のリストが提示された場合は、すべての対象言語で一貫して適用します。

ワークフロー

1. ソース README と言語を確認する

• ソース README のパスを確認します。既定値は README.md です。
• ファイルの内容とリポジトリの状況から、ソース言語を特定します。
• リクエスト、または既存のリポジトリのパターンから対象言語を決定します。
• 翻訳せずに残す必要がある用語集の用語、製品名、フレーズを確認します。

2. 翻訳前に Markdown の構造を確認する

ソース README を一度、文章ではなく構造として読みます。references/preservation-checklist.md を開き、崩れやすい要素を洗い出します。

• 見出しと見出しレベル
• バッジ行、shields の URL、画像リンク
• 表と配置行
• 生の HTML ブロックとインライン HTML
• > [!NOTE] のような GitHub アラートや注意書き
• コードフェンス、インラインコード、コマンド、設定スニペット
• (#installation) のような文書内アンカー
• ファイル、ドキュメント、スクリーンショット、その他の README 版への相対リンク

README に既存のローカライズ版がある場合は、ファイル名やセレクターの形式を決める前に、それらも確認します。

3. 文章のレイヤーだけを翻訳する

翻訳する内容：

• 段落のテキスト
• リスト項目の文章
• 表のセルの文章
• HTML ブロック内の表示テキスト
• 安全に変更できる場合の画像の代替テキスト
• セレクターのラベルや、その他のユーザー向けラベル

翻訳しない内容：

• フェンス付きコードブロック
• インラインコードスパン
• シェルコマンド
• --help のようなフラグ
• OPENAI_API_KEY のような環境変数
• URL
• ファイルパス
• リポジトリ、パッケージ、プロジェクトの識別子
• バッジや画像の URL

判断に迷う場合は、リテラルトークンをそのまま残し、周囲の文章を翻訳します。

4. ローカライズ版 README の構成を維持して作成する

• ソースと同じ見出し階層とセクション順を維持します。
• ユーザーが例の書き換えを明示的に求めている場合を除き、コードフェンスの数を維持します。
• 表の形、リストの入れ子構造、HTML のラッパー、Markdown コメントを維持します。
• 相対リンクは、リンク先をローカライズ版の README にする必要がある場合を除き、そのまま維持します。

5. ローカライズしたアンカーと、アンカーに依存するリンクを書き換える

見出しを翻訳すると、GitHub が生成する見出し ID も変わります。見出しを翻訳した後は、次の作業を行います。

• 同じファイル内のすべての (#...) リンクを、ローカライズした見出しのスラッグに合わせて書き換えます。
• <a id="..."> などの明示的なアンカーは、そのファイルですでにローカライズされた ID が使われている場合を除き、維持します。
• ドキュメント内のアンカーリンクの参照先が、既存の見出しまたは明示的なアンカーであることを確認します。

リンク切れを防ぐため、見出しの文言は必要に応じて少し調整してください。セクション順はソース README に合わせてください。

6. リポジトリの命名パターンに従って関連ファイルを作成する

既定では、次のような関連ファイル名を使います。

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

リポジトリですでに別の多言語命名パターンが使われている場合は、既定のパターンを無理に適用せず、一貫して既存のパターンを使います。

7. 言語セレクターを挿入または更新する

セレクターを編集する前に、references/language-selector-reference.md を開きます。

配置：

• セレクターはファイルの先頭付近に配置します。
• README がタイトル、バッジ、ヒーロー画像、または短い導入文から始まる場合は、その冒頭部分の直後に配置します。

動作：

• 既存のセレクターブロックがある場合は、その場で更新します。
• 新しいセレクターを追加する場合は、後続の実行で確実に更新できるよう、参照ファイルにある標準のマーカーコメントを使います。
• 現在の言語を強調し、他の言語版にリンクします。
• すべての README で、セレクターの順序とラベルを統一します。

8. 最終確認

完了前に、次の点を確認します。

• ローカライズ版ファイルの名前が、選択した命名パターンに従っていること
• すべての README バリアントにセレクターブロックがちょうど 1 つ含まれていること
• コードフェンスの数が維持されていること
• 意図的にローカライズした場合を除き、バッジや画像の URL、相対ファイルリンクが元の参照先を維持していること
• すべての (#...) リンクが、それぞれのファイル内で有効な参照先を示していること
• ローカライズ版 README の構成がソースと同じになっていること

出力

次のものを作成します。

• 対象言語ごとに 1 つのローカライズ版 README
• すべての README バリアントで更新したセレクターブロック
• 作成または更新したファイル、前提とした内容、翻訳せずに残した用語についての簡潔な説明

メンテナンスに関する注意

ユーザーから別途指示がない限り、README.md を正本として維持します。後でソース README が変更された場合は、変更された文章を差分に基づいて各ローカライズ版に反映し、ファイル全体を最初から再整形するのではなく、セレクター、ファイル名、アンカーリンクを再確認します。

プロンプトの例

例 1

この README を中国語に翻訳し、言語切り替えを追加してください。バッジ URL、コードフェンス、すべてのコマンドはそのままにしてください。

例 2

リポジトリを多言語対応にしてください。スペイン語と中国語の README を追加し、内部アンカーリンクが機能するようにして、すべてのファイルにセレクターを組み込んでください。

例 3

README.zh.md はすでにあります。README.es.md を追加し、セレクターを重複して追加せず、既存のセレクターをその場で更新してください。

よくある間違い

• フェンスで囲まれたコードブロックやインラインコードまで翻訳し、周囲の文章だけを翻訳しない
• 既存の言語セレクターを更新せず、重複して追加する
• 見出しを翻訳した後、同じファイル内の (#...) リンクを書き換え忘れる
• 表示ラベルを翻訳する際に、バッジ URL や画像ソースを変更する
• ソース README が基準であるにもかかわらず、ローカライズ版 README のセクション順を変更する