hydrogen-markets-localization

Hydrogen マーケットとローカライズ

マーケットのローカライズは、エンドツーエンドの契約として実装またはレビューしてください。ルーティング、Shopify のコンテキスト、Weaverse のコンテンツ、ドキュメントのメタデータ、ナビゲーション、コマース、アカウント、SEO、本番環境の設定がすべて一致するまでは、ロケールの切り替えは完了していません。

ライブドキュメント

このスキルのフォルダー内で、以下を実行してください。ヘルパーは隣接する shopify-hydrogen スキルに含まれているため、パック全体がインストールされていれば ../shopify-hydrogen/scripts/ が存在します。

このスキルを単独でインストールした場合、そのフォルダーは存在せず、以下のコマンドは MODULE_NOT_FOUND で失敗します。ヘルパーを一度追加してください。

npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen

このスキルの references/ ファイルはオフライン時の代替手段として引き続き利用できます。 インストールしない場合は、そちらを使用してください。

フレームワークやプラットフォームの動作を変更する前に、現在の契約を確認してください。

node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "Hydrogen localization Shopify Markets i18n country language"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "Hydrogen Customer Account logout postLogoutRedirectUri"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "Hydrogen SEO canonical hreflang sitemap"
node ../shopify-hydrogen/scripts/search_weaverse_docs.mjs "localization Translation Manager locale"

リポジトリ内の参照資料は、オフライン時の代替手段としてのみ使用してください。このスキルの例から、現在の Shopify または Weaverse API を推測しないでください。

中核となる契約

• サポートするすべてのマーケットは、マーチャント固有の単一の許可リストから導出してください。他のストアフロントのマーケット一覧をコピーしないでください。
• 言語、国、パスプレフィックス、hreflang、方向、通貨、検証済みのプロバイダーまたはバンドル言語のオーバーライドを含む、正規の公開マーケット ID を1つに統一してください。
• 設定済みのロケールプレフィックスのみを受け入れてください。未サポートの xx-yy など、ロケール形式に見える独自のプレフィックスは拒否しつつ、通常の第1セグメントのスラッグは保持してください。
• SSR、ハイドレーション、リンク、フォーム、リダイレクト、React Router のデータリクエスト、カートの変更、アカウントフロー、ログアウト、チェックアウトで、選択されたマーケットを維持してください。
• 正規 URL と hreflang のエントリーは、案内対象のすべてのマーケットで同等であることが確認されたルートに限って出力してください。確証のない代替 URL は省略してください。
• Shopify Markets の有効化と読み戻しを、リリースの前提条件として扱ってください。アプリケーションの設定によって、利用できない Shopify マーケットを実在させることはできません。

手順

1. 編集前に追跡する

リクエストの全経路と、ロケール状態を使用するすべての箇所をマッピングしてください。

1. URL パーサーとルートツリー。
2. createHydrogenContext の Storefront i18n。
3. Weaverse クライアント／Storefront の i18n と loadPage({locale})。
4. ルートローダー、<html lang>、<html dir>。
5. リンクヘルパー、フォーム、サーバーリダイレクト、Storefront リダイレクト、.data ルート。
6. カートの作成／変更、購入者 ID、国セレクター、チェックアウトへのリダイレクト。
7. Customer Account のログイン、未認証時のリダイレクト、ログアウト URI。
8. 正規 URL、hreflang、サイトマップ、robots、CMS SEO の構成。
9. Translation Manager のペイロード、同梱翻訳、レガシー設定、Studio のデザインモードプレビュー。

古いルート、設定、ヘルパー、エイリアス、翻訳リーダーを削除する前に、呼び出し元と参照先を検索してください。すべての呼び出し元が正規の経路で処理されることを確認してから、レガシー経路を削除してください。

2. 単一のマーケットモデルを確立する

ルーティング、コンテキストの作成、セレクター、SEO、テストで共有する、変更不可の設定を1つ使用してください。空のプレフィックスを持つデフォルトマーケットを必ず1つだけ設定し、それ以外のプレフィックスは一貫した方法で正規化してください。コンポーネントごとに場当たり的に方向を導出するのではなく、RTL を明示的にモデル化してください。

根拠が必要とする場合は、公開ロケール ID とプロバイダー ID を分離してください。Shopify はプロバイダーの言語列挙値を必要とする一方で、Weaverse の翻訳検索には公開用の言語・国キーが必要な場合があります。それぞれの境界には、実際に使用する ID を渡してください。両方で動作するように、共有オブジェクトを変更しないでください。

パスヘルパーは冪等にし、セグメントを考慮してください。React Router のデータルートのサフィックスをロケールの一部として扱わずに処理してください。ユーザーフローで必要な場合は、クエリ文字列を保持してください。

マーケットを追加する場合は、まず正規の許可リストを変更し、2つ目のマーケットテーブルを追加せずに、派生するすべての利用箇所が更新されることを確認してください。翻訳バンドルを追加するのは、既存のバンドルでカバーされていない言語または文字体系に限ってください。ロケールに関する手動編集が2か所目に必要になるなら、それは設定を統合すべき兆候であり、通常のロールアウト手順ではありません。

3. アプリ全体でマーケットの状態を維持する

• サーバー描画時とハイドレーション時の lang と dir は、同じ解決済みマーケットから設定します。
• 内部リンクとアクション URL は、古いデフォルトのローダー値ではなく、現在の URL を基にローカライズします。
• マーケットに依存しない Shopify リダイレクトを解決する前にロケールを解除し、同一オリジンの遷移先は再度ローカライズします。外部へのリダイレクトは変更せずに維持します。現在のリダイレクトヘッダーを置き換え、書き換えた遷移先を元のヘッダーの横に追加しないでください。
• カートの作成時と、チェックアウトに進む可能性のあるすべての変更処理で、購入者 ID の国を同期します。
• クライアントから渡されたリダイレクト先は、先頭に / がちょうど 1 つ付いた、有効なアプリ相対パスの場合にのみ受け入れます。スキーム、プロトコル相対形式、バックスラッシュ、制御文字、解析エラーは拒否し、ローカライズされたカートのルートにフォールバックします。
• Customer Account のログアウト先はローカライズされたホームにします。必要なログアウト URI の許可リストを導出し、現在の Customer Account API 設定を読み戻してから、URI の登録または変更について所有者の明示的な承認を得ます。

4. SEO の正確性を保つ

現在のマーケット用の正規 URL を 1 つ作成し、CMS のメタデータによって 2 つ目が追加されないようにします。hreflang は、明示的な同等性ルールがある場合にのみ生成します。不変のルートは対象になり得ますが、ローカライズされたハンドル、未公開のリソース、確実性のない CMS ページは対象外です。フレームワークの x-default 形式が有効なマークアップになることを実際に確認し、ヘルパーのフラグで有効になると決めつけないでください。網羅性を高く見せるために、サイトマップの代替 URL を捏造しないでください。

5. 翻訳の優先順位を定義する

実際の参照元とテストを確認したうえで、各ソースが存在する場合は次の優先順位を適用します。

1. Studio のライブデザインモードによる上書き。
2. Translation Manager に保存された上書き。
3. 移行互換性のために保持されている、実際の従来型マーチャント設定。
4. バンドルされた／静的な翻訳。

各ソースは、次のルールに従って解決します。

• 真偽値ではなく、自身のプロパティの存在を確認します。
• 移行対象となる各設定について、これまでに出荷されたデフォルト値を記録します。保存済みの値がそのデフォルトのままの場合、マーチャントの意図が確認できたとはみなさず、次の優先順位に進みます。
• 継承された値と、スキーマの未保存デフォルト値は存在しないものとして扱います。
• 明示的に保存された空文字列は「この文言を消去する」という意味として扱い、次の優先順位に進まないようにします。
• バンドルされた文言と、マーチャントによる上書きの由来情報を分離します。
• すべての表示箇所が共通リーダーを使用するようになってから、従来型設定とバイパス用プロパティを削除します。

6. プラットフォーム設定を実証する

設定済みの各マーケットについて、本番環境の Shopify 境界を確認し、有効な国、言語、通貨を読み戻します。Shopify が暗黙にフォールバックする場合はリリースを中止します。また、次の点も確認します。

• Weaverse に、Translation Manager が使用する公開ロケールキーが渡されること。
• Translation Manager のテーマキー同期が最新で、公開済みの上書きが優先されること。
• ローカライズされた Customer Account のログアウト URI がすべて許可されていること。
• デモ／プロジェクトの同期、CI、デプロイ、本番ストアフロントの状態が、テスト済みのコミットに対応していること。

本番環境の検証は、デフォルトで読み取り専用にします。Shopify、Customer Account、Weaverse、カート、セッション、チェックアウトの状態を変更する前に、正確な環境、ID、スコープ、値を確認し、所有者から明示的な承認を得てください。専用のテスト用 ID を使用し、ローカライズの検証のために有料注文を行わないでください。

AI エージェントの実行手順

Weaverse Shopify Admin API プロキシは、スコープが限定された権限ブリッジです。使用する前に、現在マウントされているルートを確認してください。Builder の実装では、次の機能が公開されています。

• GraphQL の query または mutation と変数を指定する POST https://studio.weaverse.io/api/admin-graphql。
• shopify または content_api タイプのショップスコープトークンを使用する Authorization: Bearer <WEAVERSE_API_KEY>。agent_cli トークンは拒否されます。
• Shopify の操作は、接続済み Weaverse アプリのインストールと、マーチャントが Weaverse Dashboard → Settings → Shopify Admin API Proxy → Manage Scopes で付与したスコープに限定されます。
• プロキシの制限は、トークンあたり 1 時間に 1000 リクエスト、クエリタイムアウトは 15 秒です。

これは実際の Shopify Admin アクセスですが、すべての Shopify リソースに無条件でアクセスできるわけではありません。確認済みの操作に必要な最小限のスコープをリクエストしてください。Storefront API へのアクセスでストアフロントの実際の動作は確認できますが、Admin 権限の代わりにはなりません。

次の順序で実行してください。

1. 機能を確認します。 リポジトリのルートやスクリプト、マウント済みのツールを調べます。最新の Shopify／Weaverse の公式ドキュメントを取得します。読み取りと書き込みそれぞれについて、正確な GraphQL 操作または Admin UI の手順を記録します。mutation、フィールド、エンドポイント、対応機能を決して推測しないでください。現在の Shopify Admin GraphQL スキーマまたは公式ドキュメントで正確な操作を確認できるまでは、Markets の設定、有効な言語、国／通貨、Customer Account のログアウト URL を変更できると主張しないでください。
2. キーを安全に準備します。 WEAVERSE_API_KEY は、追跡対象外のサーバー専用環境ファイルにアクセス権限 0600 で保存するか、承認済みの認証情報バインディングを使用してください。クライアントコード、プロンプト、ドキュメント、URL、コマンド引数、ログには決して含めないでください。
3. ID とスコープを読み取ります。 確認済みのプロキシを通じて、影響のない最新スキーマの ID／ショップ情報の読み取りを実行し、変更前に付与済みアプリスコープを確認してください。ショップが異なる場合、必要最小限のスコープがない場合、トークンタイプが異なる場合、対象が曖昧な場合、レート制限に達した場合、またはタイムアウトした場合は、安全側に処理を停止してください。
4. レビュー済みの変更計画を作成します。 現在値と希望値、正確な対象 ID、確認済みの GraphQL 操作または Admin の手順、必要なスコープ、冪等性の条件、変更不要時の動作、ロールバック、公開の境界、正確な読み戻し方法を列挙します。外部への書き込みを行う直前に、毎回オーナーの明示的な承認を得てください。破壊的な変更や影響の大きい変更は別途明記してください。
5. 冪等性を保って変更します。 前提条件を再読み込みし、すでに正しい状態なら変更をスキップして、承認済みの差分だけを適用します。HTTP／プロキシエラー、GraphQL のトップレベルの errors、mutation ペイロードの userErrors を確認してください。いずれかがあれば、書き込みが成功したとは確認できていません。差異、フォールバック、一部のみの失敗、予期しない応答があれば停止してください。
6. 正確に読み戻します。 独立したクエリを使い、承認済みの各国、言語、通貨、マーケット、ロケールキー、確認済みのログアウト URL を計画と照合します。mutation が受理された応答だけを成功の証明として扱わないでください。
7. 公開を承認制にします。 読み戻し結果をすべて提示し、公開／デプロイについて明示的な承認を求めます。公開、デプロイ、マーケットの有効化は、それぞれ別個の重要な操作です。
8. 公開後に確認します。 承認済みのルートマトリクスを実行し、レンダリングされた lang／dir、ロケールを維持したナビゲーション、カートの購入者 ID、チェックアウトのマーケット／通貨、canonical／hreflang、サイトマップのポリシー、Translation Manager の出力、デプロイ済みリビジョンを確認します。証跡から機密性の高い URL／クエリ／セッション値を削除してください。

キー、必要最小限の Shopify スコープ、または確認済みの mutation が利用できない場合は、実行可能なコード変更と読み取り専用の確認をすべて完了し、該当する本番環境の設定が未確認であると明記して、検証チェックリストに正確な管理者向け引き継ぎ事項を記載してください。マーケットが有効である、またはエンドツーエンドのローカライズに成功したと決して主張しないでください。

検証

references/verification-checklist.md を読み、ストアフロントに該当するチェックのみを実行してください。対象を絞った回帰テストから始め、実際の開発サーバーと本番環境の境界をテストしてください。マーケットのリストと想定通貨は、各マーチャントに合わせてください。

関連スキル

• 最新の Hydrogen のコンテキスト、カート、SEO、サイトマップ API には、shopify-hydrogen を使用してください。
• Weaverse のクライアントおよびページ読み込み API には、weaverse-hydrogen を使用してください。
• ロケールごとの認証済みコンテンツの読み取りと書き込みには、weaverse-content-api を使用してください。この API のワークフローをここで再現しないでください。
• インポート時の defaultLocale またはページの割り当てを変更する必要がある場合は、generating-weaverse-project-json を使用してください。