# General Translation Integrations: Shopify Hydrogen のロケール処理
URL: https://generaltranslation.com/ja/docs/integrations/shopify/reference/locale-handling.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Shopify ストアフロントで、ストアフロントの文言、カタログコンテンツ、URL、マーケットのロケールを統一する方法。Shopify ストアフロントにおけるロケール処理のリファレンスです。

これらのルールは、React Router と Next.js のどちらを使う場合でも、すべての Hydrogen ストアフロントに適用されます。これにより、すべてのリクエストで `gt-react` または `gt-next`、Shopify の Storefront API の文脈、ルーティング、キャッシュのロケールが統一されます。

## 概要 [#overview]

| トピック                         | 説明                                             |
| ---------------------------- | ---------------------------------------------- |
| [ロケールコード](#locale-codes)     | ロケールリストを 1 つにまとめ、Shopify のコードに明示的に対応付けます。      |
| [ルーティング](#routing)           | 言語は URL で決まり、カノニカル URL はページごとに 1 つです。          |
| [言語とマーケット](#language-market) | 文言の言語とコマース上の国はそれぞれ独立した入力で、ロケールごとに組み合わせを指定できます。 |
| [キャッシュされたページ](#cached-pages) | 翻訳はビルドに含めて配信されます。                              |

## ロケールコード [#locale-codes]

ロケールは `gt.config.json` で一度だけ定義します。ルーティング、`<html lang>`、プロバイダー、言語切り替え機能、Shopify のクエリ文脈は、別のリストを用意せず、すべてこのリストから導出してください。

Shopify ストアフロントでは、1 つの言語に対して 3 種類のコードがあります。

* **General Translation のロケール**は、`fr` や `pt-BR` のような BCP 47 タグです ([ロケールコード](/docs/platform/core/guides/locale-codes)を参照) 。
* **Storefront API の `LanguageCode`** の値は、`FR` や `PT_BR` のような、アンダースコア区切りの大文字の列挙型です。これは `@inContext(language:)` に渡します。
* **Admin API のロケール**は、`fr` や `pt-BR` のようなショップのロケールコードです。これは `translationsRegister` に渡します。

各ロケールは明示的にマッピングしてください。`_` を `-` に置き換えるだけでもほとんどのコードには対応できますが、すべてではありません。

| Shopify `LanguageCode` | 言語              | General Translation ロケール |
| ---------------------- | --------------- | ------------------------ |
| `EN`                   | 英語              | `en`                     |
| `FR`                   | フランス語           | `fr`                     |
| `JA`                   | 日本語             | `ja`                     |
| `PT_BR`                | ポルトガル語 (ブラジル)   | `pt-BR`                  |
| `PT_PT`                | ポルトガル語 (ポルトガル)  | `pt-PT`                  |
| `ZH_CN`                | 中国語 (簡体字)       | `zh-CN` または `zh-Hans`    |
| `ZH_TW`                | 中国語 (繁体字)       | `zh-TW` または `zh-Hant`    |

`ZH_CN` と `ZH_TW` は、リージョンだけでなく文字体系も表します。`zh-TW` は台湾という地域も含意するのに対し、`zh-Hant` は地域を問わず繁体字中国語を指します。Shopify の各言語に対してロケールを 1 つ選び、`gt.config.json`、URL、`<html lang>` で一貫して使用してください。

<Callout type="info">
  **Hydrogen で予定されている機能:** ロケールヘルパーを提案するプルリクエストが現在オープンになっています。[Shopify/hydrogen#4009](https://github.com/Shopify/hydrogen/pull/4009) では、パス名またはドメインによるルーティングに対応したロケール定義 `defineShopifyI18n` と、`getSupportedLocales` などのヘルパーが追加されます。[Shopify/hydrogen#4325](https://github.com/Shopify/hydrogen/pull/4325) では、`LanguageCode` を有効な `<html lang>` タグに変換する `getHtmlLang` が追加されます (例: `PT_BR` → `pt-BR`、`ZH_TW` → `zh-Hant`) 。いずれもまだリリース済みの `@shopify/hydrogen` には含まれていないため、ロケールリストとマッピングは引き続き自前で管理してください。
</Callout>

タグは言語のみをもとに組み立ててください。カナダのマーケットでフランス語を閲覧している買い物客には、`fr-CA` ではなく `fr` が適用されます。`fr-CA` のようなロケールを別途追加するのは、そのロケール専用のコンテンツを管理する場合に限ってください。

## ルーティング [#routing]

### 言語は URL で決まる

ロケールはリクエストのパスまたはドメインから解決し、同じ値をプロバイダー、`<html lang>`、Shopify のクエリ文脈に渡します。クッキーや `Accept-Language` を手がかりにリダイレクトを促すことはできますが、同じ URL は常に同じ言語でレンダリングされます。そのため、キャッシュや検索エンジンからは 1 つの URL につき 1 つの言語として扱われます。

### ページごとにカノニカル URL を 1 つにする

デフォルトロケールはプレフィックスなしで配信し、その他のロケールは `/fr/products/hoodie` のようにプレフィックス付きで配信します。`/en/products/hoodie` のようにデフォルトロケールにプレフィックスが付いている場合や、不明なプレフィックスの場合は 404 を返します。ローカライズされたページでレンダリングされるリンクには、そのページのプレフィックスがそのまま付きます。

`createShopifyRequestContext` の `i18n.pathPrefix` で、プレフィックス (`/fr` など) を Hydrogen に渡します。デフォルトロケールの場合は空文字列を渡します。Hydrogen は、自身が返す商品バリアントのリダイレクトと標準ルートのリダイレクトに、このプレフィックスを付加します。

### ローカライズしないルート

Shopify やそのスクリプトが固定パスで呼び出すルートには、プレフィックスを付けないでください。具体的には、カートおよび予測検索 API のハンドラー、顧客アカウント認可のコールバック、その他の `/api` ルートが該当します。Vercel Shop テンプレートでは、`proxy.ts` によって、ロケールのリライトより先に Hydrogen の `handleShopifyRoutes` がこれらのリクエストに応答します ([Next.js の Shopify ストアフロントをローカライズする](/docs/integrations/shopify/guides/localizing-nextjs#routing)を参照) 。

ただし、カートや予測検索のリクエストにもページの言語を渡す必要があります。渡さない場合、Shopify はデフォルト言語のカタログテキストを返します。ページのロケールをクッキーに保存し、プレフィックスのないこれらのリクエストでのみ読み取るようにしたうえで、設定済みのロケール以外は受け付けないようにしてください ([Hydrogen のハンドラーをページの言語に合わせる](/docs/integrations/shopify/guides/localizing-react-router#handler-locale)を参照) 。

## 言語とマーケット [#language-market]

Storefront API の `@inContext` ディレクティブは、`language` と `country` を受け取ります。この 2 つはそれぞれ異なる役割を担います。

* **`language`** は、Shopify が返すカタログコンテンツをどの言語の翻訳にするかを決めます。ページのロケールに合わせて指定します。
* **`country`** はマーケットを選択し、価格、通貨、商品の販売可否を決定します。カートに対しては、カートに購入者情報 (buyer identity) が設定されるまでの間だけ適用され、`country` によって購入者情報が設定されることはありません。購入者の国は `cartCreate` または `cartBuyerIdentityUpdate` で設定してください。設定後は、`@inContext` の値と競合する場合でも購入者情報が優先されます。(Shopify の[カートの文脈に関するルール](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/in-context#cart-queries-and-mutations)を参照してください。)

両者の関係は、次のいずれかの方針から選びます。

* **すべての言語で 1 つのマーケットを使う。** すべてのロケールで同じ国を渡します。言語を切り替えても変わるのは文言とカタログのテキストだけで、価格やカートは変わりません。
* **言語ごとに 1 つのマーケットを使う。** フランス語ならフランス、日本語なら日本のように各ロケールを国に対応付け、その国をロケールの言語と一緒に渡します。これにより、言語ごとに対応するマーケットの価格と通貨が表示されます。カートは購入者の国の通貨を保持するため、言語が切り替わったときは `cartBuyerIdentityUpdate` でカートの購入者の `countryCode` を更新してください。([複数マーケットでの販売](/docs/integrations/shopify/guides/selling-in-markets)を参照してください。)

買い物客が言語とは別に国を選べるようにしたい場合は、代わりに専用の国セレクターを追加し、国が変更されたときに購入者情報を更新してください。

価格を換算したり、ロケールから通貨を推測したりしないでください。Shopify の金額は、Shopify が返す通貨コードを使って [`<Currency>`](/docs/react/reference/components/currency) または Hydrogen の `formatMoney` で書式設定してください。

## キャッシュされたページ [#cached-pages]

ページをキャッシュまたはプリレンダリングする場合は、ビルドにバンドルされたファイルから翻訳を読み込んでください。静的シェル内では実行時翻訳のリクエストを実行できません。Next.js で Cache Components を使用する場合は、カスタムの [`loadTranslations`](/docs/react/reference/functions/load-translations) が必須です ([Cache Components の使用](/docs/react/nextjs/cache-components)を参照) 。

Shopify に保存されたカタログの翻訳はビルドに含まれず、Storefront API のキャッシュ設定に従います。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.