translate-site

AI で多言語サイトを翻訳する

1 つのサイトで 2 種類の翻訳システムを併用できます。このスキルでは両方を扱います。

パート	内容	セクション
Rosey のロケール JSON（rosey/locales/{code}.json）	共通 UI と data-rosey が付与されたページテキスト（ナビゲーション、フッター、見出し、ボタン、パンくずリスト、および分割されていないページの本文全体）	パート 1
コンテンツコレクションのファイル（blog_fr/、content_fr/ など）	ロケールごとの本文コンテンツとフロントマター（タイトル、説明、代替テキスト、ページビルダーのテキスト）。SSG がロケールごとにネイティブにレンダリングします	パート 2

ほとんどの Rosey サイトではパート 1 だけが必要です。 パート 2 を使うのは、プロジェクトにロケールごとのコンテンツディレクトリが実際にある場合に限ります。具体的には、ディレクトリ分割方式（make-site-multilingual スキルのフェーズ 8）または Hugo の言語機能（Hugo のセットアップ A と B）です。Rosey サイトでは、ディレクトリ分割されたページに両方が必要です。本文はコンテンツコレクションのファイル（パート 2）から取得し、共通 UI はロケール JSON（パート 1）から取得します。Rosey を使わない Hugo サイト（セットアップ A）では、パート 2 だけが必要です。

このスキルは AI コーディングエージェント向けに書かれていますが、JSON を読み書きできる AI ツールならどれでも、この手順を利用できます。

使用するタイミング

• ロケールファイルに未翻訳のエントリーがある（意図的にそのままにしたエントリーではなく、value がまだ original と同じ）
• 原文の文字列が変更され、翻訳が古くなった
• 新しいロケールを一からまとめて翻訳する
• ロケールごとのコンテンツディレクトリ（blog_fr/、blog_de/）の本文やフロントマターを翻訳する

使用しないタイミング

• まだ翻訳先が存在しないサイト — rosey/locales/ もロケールごとのコンテンツディレクトリもありません。まず make-site-multilingual で設定してください。
• ビルドに新しいロケールを追加する場合 — これはパイプラインと設定の変更です。同じく make-site-multilingual を参照してください。
• 人間のチームや外部サービスが翻訳を提供する場合 — このスキルで扱うのは、AI でファイルを埋める場合に限られます。

目次

ファイル	内容
SKILL.md（このファイル）	該当するパートと、ファイル形式が AI 翻訳に適している理由
locale-files.md	パート 1。ほとんどのサイトではこれだけが必要です — rosey/locales/{code}.json
content-directories.md	パート 2 — ロケールごとのコンテンツディレクトリ。サイトがディレクトリ分割方式の場合のみ
scripts/README.md	両パートで使用する準備・マージスクリプト

Rosey ファイルが AI に最適な理由

Rosey のロケールファイルは、各エントリが予測可能な 3 つのフィールドで構成されたフラットな JSON です。そのため、エージェントにとって翻訳を効率的かつ安全に行える 3 つの特性があります。

1. 差分更新 — write-locales で新しいエントリを追加すると、value にはソースの原文が設定されます。value と original を比較するだけで未翻訳の箇所をすぐに特定でき、翻訳済みのエントリには手を加えません。差分比較も外部状態も追跡用データベースも不要です。
2. 決定的／冪等 — 同じ処理を 2 回実行しても、同じ出力が生成されます。既存の作業を再翻訳することはなく、git diff で確認できます。
3. 豊富なコンテキスト — キーにはテキストの表示場所（nav:about、index:hero:title、blog:recent-posts）が含まれているため、スクリーンショットがなくても短い文字列（「More」、「Back」、「Home」）の意味を判別できます。

データ形式そのものが状態管理を担います。JSON ファイルを読み込み、value === original のエントリを見つけて翻訳し、ファイルに書き込みます。例外は、ブランド名など、意図的に原文と同じままにするエントリです。merge-translation.mjs はそうしたエントリを rosey/translate-site-keep.json に記録し、再び翻訳対象として提示されないようにします。

学んだことと注意点

このセクションは随時更新されます。翻訳中に新しいパターン、問題、改善点に気づいた場合は、ここに追記する前にユーザーに確認してください。リポジトリの README の 主要な規約 → 生きたドキュメント を参照してください。