# General Translation Integrations: Shopify Hydrogen 区域设置处理
URL: https://generaltranslation.com/zh/docs/integrations/shopify/reference/locale-handling.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Shopify 店面如何让店面文案、目录内容、URL 和市场统一使用同一区域设置。Shopify 店面区域设置处理参考。

以下规则适用于所有 Hydrogen 店面，无论基于 React Router 还是 Next.js。这些规则可确保在每个请求中，`gt-react` 或 `gt-next`、Shopify Storefront API 上下文、路由和缓存都使用同一区域设置。

## 概览 [#overview]

| 主题                        | 说明                               |
| ------------------------- | -------------------------------- |
| [区域设置代码](#locale-codes)   | 统一使用一份区域设置列表，并显式映射到 Shopify 代码。  |
| [路由](#routing)            | 由 URL 决定语言，每个页面只有一个规范网址。         |
| [语言与市场](#language-market) | 文案语言和商业国家/地区是两个独立的输入，可按区域设置分别组合。 |
| [缓存页面](#cached-pages)     | 译文随构建一同发布。                       |

## 区域设置代码 [#locale-codes]

区域设置只需在 `gt.config.json` 中定义一次。路由、`<html lang>`、提供者、语言切换器以及 Shopify 查询上下文都应基于这份列表生成，而不是另外维护一份。

在 Shopify 店面中，每种语言都对应三种代码：

* **General Translation 区域设置**是 BCP 47 标签，例如 `fr` 或 `pt-BR`。 (参见[区域设置代码](/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 语言选定一个区域设置，并在 `gt.config.json`、URL 和 `<html lang>` 中统一使用。

<Callout type="info">
  **Hydrogen 即将支持：**&#x4E00;些尚未合并的拉取请求提议添加区域设置辅助函数。[Shopify/hydrogen#4009](https://github.com/Shopify/hydrogen/pull/4009) 新增了 `defineShopifyI18n` (一种支持路径名或域名路由的区域设置定义) 以及 `getSupportedLocales` 等辅助函数。[Shopify/hydrogen#4325](https://github.com/Shopify/hydrogen/pull/4325) 新增了 `getHtmlLang`，可将 `LanguageCode` 转换为有效的 `<html lang>` 标签，例如将 `PT_BR` 转换为 `pt-BR`，将 `ZH_TW` 转换为 `zh-Hant`。两者目前都未包含在已发布的 `@shopify/hydrogen` 版本中，因此请继续自行维护区域设置列表和映射。
</Callout>

标签只根据语言生成。在加拿大市场浏览法语内容的购物者得到的是 `fr`，而不是 `fr-CA`。只有当你为 `fr-CA` 等区域设置单独维护文案时，才需要另行添加该区域设置。

## 路由 [#routing]

### 由 URL 决定语言

从请求路径或域名中解析区域设置，并将同一个值传给提供者、`<html lang>` 以及 Shopify 的查询上下文。cookie 或 `Accept-Language` 可以作为重定向的参考，但同一个 URL 始终渲染同一种语言，这样缓存和搜索引擎看到的每个 URL 都只对应一种语言。

### 每个页面只有一个规范网址

默认区域设置不加前缀，其他区域设置则放在前缀下，例如 `/fr/products/hoodie`。带前缀的默认区域设置 (例如 `/en/products/hoodie`) 和未知前缀均返回 404。本地化页面上渲染的链接会保留该页面的前缀。

在 `createShopifyRequestContext` 中通过 `i18n.pathPrefix` 将前缀传给 Hydrogen，例如 `/fr`；默认区域设置则传入空字符串。Hydrogen 返回商品变体重定向和标准路由重定向时，会自动加上该前缀。

### 非本地化路由

Shopify 或其脚本会以固定路径调用某些路由，这些路由不要添加前缀，包括购物车和预测搜索 API 处理函数、客户账户授权回调，以及其他 `/api` 路由。在 Vercel Shop 模板中，`proxy.ts` 会让 Hydrogen 的 `handleShopifyRoutes` 先于任何区域设置重写来响应这些请求。 (参见[本地化 Next.js Shopify 店面](/docs/integrations/shopify/guides/localizing-nextjs#routing)。) 

购物车和预测搜索请求仍需使用页面的语言，否则 Shopify 会返回默认语言的目录文本。请将页面的区域设置记录在 cookie 中，仅在处理这些无前缀请求时读取，并且只接受已配置的区域设置。 (参见[让 Hydrogen 的处理函数使用页面语言](/docs/integrations/shopify/guides/localizing-react-router#handler-locale)。)

## 语言与市场 [#language-market]

Storefront API 的 `@inContext` 指令接受 `language` 和 `country` 两个参数，二者各司其职：

* **`language`** 决定 Shopify 返回目录内容的哪个语言版本，它跟随页面的区域设置。
* **`country`** 决定市场，而市场决定价格、货币和商品可售情况。对于购物车，它仅在购物车尚未设置买家身份时生效，且永远不会自动设置买家身份。请通过 `cartCreate` 或 `cartBuyerIdentityUpdate` 设置买家所在国家/地区；此后，若与 `@inContext` 的值冲突，以买家身份为准。 (参见 Shopify 的[购物车上下文规则](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/in-context#cart-queries-and-mutations)。) 

根据需要选择二者的对应关系：

* **所有语言共用一个市场。** 为每个区域设置传入相同的国家/地区。切换语言只会改变文案和目录文本，不会影响价格或购物车。
* **每种语言对应一个市场。** 将每个区域设置映射到一个国家/地区，例如法语对应法国、日语对应日本，并将该国家/地区与对应的语言一起传入。这样，每种语言都会显示其所属市场的价格和货币。切换语言时，请使用 `cartBuyerIdentityUpdate` 更新购物车买家的 `countryCode`，因为购物车始终使用买家所在国家/地区的货币。 (参见[在多个市场销售](/docs/integrations/shopify/guides/selling-in-markets)。) 

如果希望购物者能独立于语言选择国家/地区，请另行添加一个国家/地区选择器，并在选择变化时更新买家身份。

切勿换算价格，也不要根据区域设置推断货币。请使用 Shopify 返回的货币代码，通过 [`<Currency>`](/docs/react/reference/components/currency) 或 Hydrogen 的 `formatMoney` 格式化 Shopify 金额。

## 缓存页面 [#cached-pages]

当页面被缓存或预渲染时，请从随构建打包的文件中加载译文。运行时翻译请求无法在静态外壳中执行。在启用了缓存组件的 Next.js 中，必须提供自定义的 [`loadTranslations`](/docs/react/reference/functions/load-translations) (参见[使用缓存组件](/docs/react/nextjs/cache-components)) 。

存储在 Shopify 中的目录译文不属于构建产物，而是遵循你的 Storefront API 缓存设置。

## Sitemap

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