readme-i18n

リポジトリの README.md をローカライズしながら、リポジトリのメカニクスを壊さないようにします。

デフォルトのジョブは翻訳 + 配線です：

• ソース・オブ・トゥルース README を読む
• README.zh.md のようなローカライズされた兄弟ファイルを作成する
• GitHub Flavored Markdown の構造とリポジトリ固有のトークンを保持する
• すべてのバリアントの上部付近に共有言語セレクタを追加または更新する

このスキルは多言語 README ワークフロー用であり、一般的なウェブサイト/アプリの i18n ではありません。

入力

利用可能な場合は、これらの入力を想定します：

• ソース README パス、デフォルトは README.md
• ソース言語、デフォルトは推測または英語
• 1 つ以上のターゲット言語
• オプション：用語集または翻訳禁止リスト
• オプション：リポジトリが異なる多言語命名パターンを既に使用している場合のファイル名オーバーライド

ターゲット言語が指定されていない場合は、既存の翻訳済みファイル、セレクタ、ファイル名、問題、または以前のリポジトリ慣例を検査します。それでもターゲット言語が不明な場合は、1 回質問します。ターゲット言語を発明してはいけません。

デフォルトと決定ルール

• ユーザーが明示的に別の指定をしない限り、ルートの README.md をソース・オブ・トゥルースとして扱います。
• ソース言語が曖昧な場合は、1 回質問します。それ以外の場合は英語と仮定します。
• セクションの順序をソース README と一致させます。ローカライズされた有効なアンカーを生成するために必要な場合のみ、小さな見出しの言葉遣いを調整します。
• リポジトリが既に別の確立されたパターンを使用していない限り、README.<bcp47-tag>.md という命名でローカライズされた兄弟ファイルを出力します。
• 既存の言語セレクタをその場で更新します。重複させないでください。
• 人間の言語コンテンツのみを翻訳します。
• プロジェクト名、パッケージ名、コマンド、CLI フラグ、オプション名、環境変数、URL、ファイルパス、インラインコード、コードフェンス、HTML 属性、およびバッジ/画像 URL を保持します。
• バッジの alt テキストまたは表示されるラベルは、変更がバッジ URL、クエリパラメータ、または画像ソースの変更を必要としない場合にのみ翻訳できます。
• 用語集または翻訳禁止リストが提供されている場合は、すべてのターゲット言語全体で一貫して適用します。

ワークフロー

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

• ソース README パスを確認します。デフォルトは README.md です。
• ファイルの内容とリポジトリのコンテキストからソース言語を特定します。
• リクエストまたは既存のリポジトリパターンからターゲット言語を決定します。
• 翻訳されないままにする必要がある用語集の用語、製品名、またはフレーズをメモします。

2. 翻訳前に Markdown 構造を監査する

ソース README をプローズではなく構造として 1 回読みます。references/preservation-checklist.md を開き、破損の可能性が最も高い要素をインベントリしします：

• 見出しと見出しレベル
• バッジ行、shields URL、画像リンク
• テーブルとアライメント行
• raw HTML ブロックとインライン HTML
• > [!NOTE] などの GitHub アラートまたは注釈
• コードフェンス、インラインコード、コマンド、および構成スニペット
• (#installation) のようなドキュメント内アンカー
• ファイル、ドキュメント、スクリーンショット、または他の README バリアントへの相対リンク

README に既にローカライズされた兄弟ファイルがある場合は、ファイル名またはセレクタスタイルを選択する前にそれらも検査します。

3. プローズレイヤーのみを翻訳する

翻訳する対象：

• 段落テキスト
• リストアイテムプローズ
• テーブルセルプローズ
• HTML ブロック内の表示テキスト
• 安全な場合の画像 alt テキスト
• セレクタラベルおよび他のユーザー向けラベル

翻訳しない対象：

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

疑わしい場合は、リテラルトークンを保持し、その代わりに周囲の文を翻訳します。

4. ローカライズされた README を書く際に構造を保持する

• ソースと同じ見出しの階層とセクションの順序を保ちます。
• ユーザーが明示的に例を書き直すよう求めない限り、同じ数のコードフェンスを保ちます。
• テーブルの形状、リストのネスト、HTML ラッパー、および Markdown コメントを保持します。
• ローカライズされた兄弟 README を指すために意図的にリンクが必要な場合を除き、相対リンクを保持します。

5. ローカライズされたアンカーとアンカー依存リンクを書き直す

翻訳された見出しが変わると、GitHub は異なる見出し ID を生成します。見出しを翻訳した後：

• その同じファイル内の (#...) リンクすべてを書き直し、そのファイルのローカライズされた見出しスラッグと一致するようにします
• ファイルが既にローカライズされた明示的な ID を使用していない限り、<a 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 が後で変更されたときは、ファイル全体を最初から再フォーマットするのではなく、変更されたプローズを diff してから、セレクタ、ファイル名、およびアンカーリンクを再度確認します。

プロンプト例

例 1

このREADMEを中国語に翻訳し、言語スイッチャーを追加します。バッジURL、コードフェンス、およびすべてのコマンドを完全にそのままにしておきます。

例 2

リポジトリを多言語対応にします。Spanish と Chinese の README バリアントを追加し、内部アンカーリンクを機能させ、セレクタをすべてのファイルに配線します。

例 3

既に README.zh.md があります。README.es.md を追加し、2番目のセレクタを追加するのではなく、既存のセレクタをその場で更新します。

よくある間違い

• フェンス付きコードブロックまたはインラインコードを翻訳する代わりに、その周囲のプローズのみを翻訳する
• 既存ブロックを更新するのではなく言語セレクタを複製する
• 見出しを翻訳しながら、同じファイルの (#...) リンクを書き直すのを忘れる
• 表示されたラベルを翻訳しようとしながらバッジ URL または画像ソースを変更する
• ソース README が権限である場合でも、ローカライズされた README のセクションを並び替える