mikaellolbatera159-stack/localizations

コンテンツを指定されたロケールにローカライズする

指定されたロケールにコンテンツをローカライズするスキルです。

動作の仕組み

このスキルは、入力コンテンツとターゲットロケールのリストを受け取ります。その後、コンテンツを各指定ロケールに翻訳し、ローカライズされたバージョンを提供します。

コンテンツ構造

.
└── docs/                         ← ワークショップコンテンツ（ソース + ロケール出力）
    ├── README.md                 ← ランディングページ（ソース; slug: index）
    ├── <category>/               ← 英語のワークショップカテゴリ
    │   ├── README.md             ← カテゴリランディング（ソース; slug: <category>）
    │   └── <workshop>/
    │       ├── README.md         ← ワークショップランディング（ソース; slug: <category>/<workshop>）
    │       └── *.md
    ├── _images/              ← 共有アセット（ローカライズ対象外）
    └── <locale>/             ← ローカライズされた出力、docs/の直下
        ├── README.md         ← ロケールランディング（slug: <locale>）
        └── <category>/
            ├── README.md         ← ローカライズされたカテゴリランディング（slug: <locale>/<category>）
            └── <workshop>/
                ├── README.md     ← ローカライズされたワークショップランディング（slug: <locale>/<category>/<workshop>）
                └── *.md

入力コンテンツ

ローカライズ対象となるコンテンツは以下の通りです：

• docs/ およびそのサブディレクトリ 内のすべての英語Markdownファイル ― サイトランディング（docs/README.md）、カテゴリランディング、ワークショップレッスン（docs/<category>/<workshop>/**/*.md）。

_images/（共有アセット）や設定済みのロケールルートディレクトリをソース入力として扱わないでください。

docs/<locale>/ 以下にあるファイルは出力であり、入力ではありません。設定済みのロケールルートディレクトリを再度ローカライズするソースコンテンツとして決して扱わないでください。

ターゲットロケール

ターゲットロケールは、このスキルの rules ディレクトリにMarkdownファイルとして定義されます（例：rules/ko-kr.md）。処理するロケールを決定するには、rules/ 内のファイルを一覧表示します。各 <locale>.md ファイルは、サポートされている1つのターゲットロケールに対応します。 各ロケールには独自の翻訳ルールとガイドラインがあり、ローカライズされたコンテンツが対象読者に適したものになるようにします。

ロケール識別子は小文字とハイフンを使用します（例：ko-kr）。これは、このスキルにおけるルールファイル名と出力ディレクトリの両方で標準的な表記です。一貫性を保ってください。

出力コンテンツ

ローカライズされたすべてのワークショップコンテンツは、リポジトリルートの docs/ コンテンツディレクトリの直下に、各ロケールのサブディレクトリとして格納されます。例えば、韓国語のコンテンツは docs/ko-kr/ に格納されます。

ロケールディレクトリは docs/ の直接の子でなければなりません。これにより、Starlight（website/astro.config.mjs で設定）が認識し、言語セレクタを表示できるようになります。中間の localizations/ ディレクトリを追加しないでください。

ローカライズプロセス

ローカライズには3つのケースがあります。該当するケースを検出するには、ソースツリーと既存の docs/<locale>/ ツリーを比較し、ソースファイルのgit履歴を使用して変更を検出します：

• オリジナルが存在し、そのロケールのローカライズ版が存在しない： 新しいローカライズドキュメントを作成します。
• オリジナルとローカライズ版の両方が存在する： ソースツリーを docs/<locale>/ と比較し、ソースファイルに対して git diff（または git log）を実行して、最後にローカライズ版が作成されてから何が変更されたかを確認します。ローカライズドキュメントの影響を受けるセクションのみを更新し、変更のないセクションを不必要に再翻訳しないでください。
• ローカライズ版は存在するが、オリジナルが削除された： 孤立したローカライズドキュメントを削除します（そして空になったロケールサブディレクトリを整理します）。

プロセスは2つのパスで実行されます。最初に、コンテンツを分析して重要なフレーズとコンテキストを特定します。次に、translatorエージェントが初期ローカライズを実行し、続けてevaluatorエージェントが品質と一貫性を確保するためのレビューと改善のパスを実行します。

translatorとevaluatorの「エージェント」はロール/ペルソナであり、外部ツールではありません。専用のサブエージェントが利用できない場合は、順次ペルソナとして実行します。最初に翻訳者のロールを採用してドラフトを作成し、次に評価者のロールを採用してロケールルールに対してそのドラフトを批評・洗練します。評価者の基準を満たすまで、この改善ループを繰り返します。

Markdownとフォーマットの保持

ロケールに関係なく、以下は正確に保持し、翻訳してはいけません：

• YAMLフロントマターのキー（値は適切な場合にのみ翻訳します。例：title）。例外 — ランディングページ（README.md）の slug キー： サイトは各フォルダランディングをその slug でルーティングするため、ローカライズされたランディングは英語のスラッグではなくロケールプレフィックス付きのスラッグを持つ必要があります。次のように書き換えます：ロケールルート（docs/<locale>/README.md）は slug: <locale> を使用し、ローカライズされたカテゴリランディングは slug: <locale>/<category> を使用し、ローカライズされたワークショップランディングは slug: <locale>/<category>/<workshop> を使用します。英語のランディングスラッグをそのままローカライズファイルにコピーしないでください。英語のルートと衝突するためです。
• フェンスコードとインラインコード（変数名、関数名、コマンド名を含む）。
• URLと外部リンクターゲット。
• HTMLタグ、Markdown構造、テーブル、注意喚起マーカー。

人間が読む散文、およびコードブロック内の説明的なコメントは翻訳します（ロケールルールに従います）。見出しの順序とドキュメント構造は安定に保ちます。

見出しアンカーはローカライズされたテキストに従います。 見出しが翻訳されると、その自動生成アンカー/スラッグもそれに伴って変更されます。これは意図された動作です。要件は、同一ドキュメント内のアンカーリンクが解決され続けることです：見出しを翻訳するたびに、その見出しをターゲットにしているページ内リンク（](#...)）を、ローカライズされた見出しの新しいスラッグに更新します。見出しが翻訳された後、リンクを元の英語スラッグのままにしておかないでください。また、見出しと一致しなくなった英語のアンカーを保持しないでください。ローカライズされていないファイル（または外部URL）を指すアンカーは、元のターゲットを保持します。

画像とアセットのパスは、ローカライズされたアセットが存在しない限り、元のアセットを指します。 ローカライズされたファイルは docs/<locale>/ の下にあるため、ソース相対パスは必要に応じて書き換え、共有アセットに解決されるようにします（例：docs/<locale>/real-world-development/app/2-foo.md にあるレッスンは ../../../_images/x.png を使用して docs/_images/ に到達します）。対応する翻訳済み画像がロケールツリー下に実際に存在する場合にのみ、ローカライズされたアセットを指します。いずれにせよ、リンクは実在するファイルに解決されなければなりません。

翻訳者エージェント

translatorエージェントを使用してローカライズを実行します。rules ディレクトリの各ターゲットロケールドキュメントに定義されたルールとガイドラインに従う必要があります。

評価者エージェント

evaluatorエージェントを使用して、ローカライズされたコンテンツの品質を評価します。評価者は、rules ディレクトリのターゲットロケールに定義されたルールとガイドラインに従い、正確性、文化的関連性、全体的な品質をチェックします。

評価者は、ロケールの評価者スコアリングルーブリック（rules/<locale>.md に定義）に対してローカライズドキュメントをスコアリングします。ルーブリックは2つの層を使用します：Tier A はハードフェイル基準で、必ずスコア5を獲得しなければなりません。Tier B は段階的評価基準（1〜5）で、スコア4または5を獲得しなければなりません。ドキュメントは、該当するすべてのTier A基準がスコア5を獲得し、該当するすべてのTier B基準がスコア≥4を獲得した場合にのみ合格します。基準を満たさない場合は、具体的な指摘とともにドキュメントを翻訳者に戻し、ルーブリックの反復制限に達するまで翻訳→評価ループを再実行し、その後人間にエスカレーションします。

すべきこと／してはいけないこと

• すべきこと： rules ディレクトリに定義されたターゲットロケール（サポートされているロケールごとに1つの <locale>.md ファイル）に対してのみローカライズを実行します。サポートされていないロケールへのローカライズは行わないでください。
• すべきこと： Markdown構造、コード、外部リンク/URLターゲット、およびフロントマターキーを正確に保持します（Markdownとフォーマットの保持を参照）。
• すべきこと： 見出しアンカーをローカライズされた見出しテキストに従わせ、同一ドキュメント内のアンカーリンクを新しいスラッグに更新して解決され続けるようにします（Markdownとフォーマットの保持を参照）。
• すべきこと： 画像とアセットのパスを元のアセットに向けます（docs/<locale>/ から解決するように相対パスを必要に応じて書き換えます）。ただし、対応するローカライズされたアセットが存在する場合はその限りではありません（Markdownとフォーマットの保持を参照）。
• すべきこと： docs/<locale>/ の下にソースディレクトリのレイアウトをミラーリングします。
• してはいけないこと： 設定済みのロケールルートディレクトリをソース入力として扱わないでください。
• してはいけないこと： コンテンツの順序を変更したり、構造を再編成したりしないでください。見出しとその順序は安定に保ちます。
• してはいけないこと： コード、コマンド、識別子を翻訳しないでください。説明的な散文とコードコメントのみを翻訳します。