# General Translation Integrations: 快速入门
URL: https://generaltranslation.com/zh/docs/integrations/shopify/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 gt-react 或 gt-next 翻译无头 Shopify Hydrogen 店面的界面，并以相同语言展示其目录。

本地化的 Shopify 店面包含两层文本，分别在不同的地方进行翻译：

* **目录内容。** 商品、商品系列和页面由 Shopify 通过 Hydrogen (Shopify 与框架无关的店面 SDK) 提供。你可以使用 General Translation 翻译这些内容，将翻译结果存储到 Shopify 的译文中，再通过 Storefront API 读取。
* **店面文案。** 即代码中的导航、按钮、购物车提示等文本。这部分由对应框架的 General Translation SDK 负责翻译：React Router 使用 [`gt-react`](/docs/react/react-router-quickstart)，Next.js (包括 Vercel Shop 模板) 使用 [`gt-next`](/docs/react/nextjs-quickstart)。

每次请求时，两层文本读取的是同一个区域设置，因此法语页面会同时显示法语文案和法语商品标题。

*注意：此集成适用于基于 React Router 或 Next.js 并使用 Hydrogen 2026.10 的无头店面。使用 Liquid 构建的 Online Store 主题请改用 Shopify 官方的翻译应用。*

## 示例店面 [#examples]

[gt-shopify-vercel.vercel.app](https://gt-shopify-vercel.vercel.app) 是集成了 `gt-next` 的 Vercel Shop Next.js 模板。各区域设置通过路径前缀区分，默认区域设置不加前缀；所有页面和目录均已翻译为法语、日语、韩语和印度尼西亚语，每种语言都对应各自的 Shopify 市场和货币进行销售。该模板通过 CLI 将目录译文打包进应用包，而不是存储在 Shopify 中。

## 开始之前 [#before-start]

你需要：

* 一个使用 `@shopify/hydrogen` (基于 React Router 7 或 8) 或 Next.js App Router 的无头 Shopify 店面，例如 Vercel Shop。
* 一个[项目](/docs/platform/dashboard/get-started)，并安装 CLI 且已通过 [`gt login`](/docs/cli/reference/commands/login) 登录。
* 如需将目录译文存储在 Shopify 中，还需拥有 Shopify 后台 **Settings > Languages** 的访问权限。

## 快速入门 [#quickstart]

### 1. 统一定义区域设置

在 `gt.config.json` 中列出默认区域设置和目标语言区域。路由、`<html lang>`、提供者、语言切换器以及 Shopify 查询都会从这份列表中读取配置。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "ja"]
}
```

Shopify 使用 `LanguageCode` 值 (例如 `FR` 和 `PT_BR`) 来标识语言，因此请为每个区域设置显式维护一份与其 Shopify 代码的映射 (参见[区域设置代码](/docs/integrations/shopify/reference/locale-handling#locale-codes)) 。如果你将目录译文存储在 Shopify 中，还需要在 Shopify 后台的 **Settings &gt; Languages** 中添加并发布相同的语言。

### 2. 设置店面翻译

<Tabs items={['React Router', 'Next.js']}>
  <Tab value="React Router">
    请按照 [React Router 快速入门](/docs/react/react-router-quickstart)完成配置，然后在根中间件中将同一区域设置传入 Hydrogen 的请求上下文。 (参见[使用 React Router 本地化 Shopify Hydrogen](/docs/integrations/shopify/guides/localizing-react-router)。) 
  </Tab>

  <Tab value="Next.js">
    添加 `gt-next`，将店面路由移至 `app/[locale]` 下，并在 Shopify 的路由处理函数运行之后，将不带区域前缀的请求重写到默认区域设置。 (参见[本地化 Next.js Shopify 店面](/docs/integrations/shopify/guides/localizing-nextjs)。) 
  </Tab>
</Tabs>

### 3. 使用当前语言查询 Shopify

在返回目录内容的 Storefront API 查询中添加 `@inContext(language: $language)`。Hydrogen 的 Storefront 客户端会根据请求上下文中的 `i18n` 自动填充 `$language` 和 `$country`，因此无需在每个查询中单独传入。

```ts title="lib/queries.ts"
import {gql} from '@shopify/hydrogen';

export const PRODUCT_QUERY = gql(`
  query Product($handle: String!, $country: CountryCode, $language: LanguageCode)
  @inContext(country: $country, language: $language) {
    product(handle: $handle) {
      title
      description
    }
  }
`);
```

国家决定市场，而市场决定价格、货币和商品可用性。你可以让所有语言共用同一个国家，也可以让每种语言在各自的市场中销售，并在切换语言时转移购物车。 (参见[语言与市场](/docs/integrations/shopify/reference/locale-handling#language-market)) 。

对于尚未翻译的字段，Shopify 会返回源文本。要填充目录，请按照[使用 Admin API 翻译 Shopify 商品](/docs/integrations/shopify/guides/translating-products)中的步骤操作。

### 4. 生成译文

先将店面文案标记为待翻译，然后使用 [`npx gt translate`](/docs/cli/reference/commands/translate) 生成译文。请在构建之前运行该命令，并[将译文存储在本地](/docs/react/guides/storing-translations)，确保缓存页面和预渲染页面发布时已包含译文。

<Tabs items={['React Router', 'Next.js']}>
  <Tab value="React Router">
    ```json title="package.json"
    {
      "scripts": {
        "build": "npx gt translate && react-router build"
      }
    }
    ```
  </Tab>

  <Tab value="Next.js">
    ```json title="package.json"
    {
      "scripts": {
        "build": "npx gt translate && next build"
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **注意：** 如果希望改为在拉取请求中包裹并翻译新文案，请将代码仓库连接到 [Locadex](/docs/platform/locadex/quickstart)。
</Callout>

### 5. 检查本地化页面

启动店面，并请求某个目标区域设置下的页面。确认以下几点：

* `<html lang>`、店面文案和已翻译的商品标题均与该区域设置一致。
* 价格沿用 Shopify 返回的货币。
* 切换语言后，购物车、结账和账户路由仍能正常工作。

## 常见问题 [#faqs]

### Hydrogen 会自动翻译商品内容吗？

不会。Hydrogen 通过 Storefront API 读取 Shopify 中已有的翻译，本身并不生成翻译。你可以先用 General Translation 翻译目录字段，再将结果注册到 Shopify；也可以将翻译后的目录 JSON 打包进你的店面应用。 (参见[使用 Admin API 翻译 Shopify 商品](/docs/integrations/shopify/guides/translating-products)。)

### 切换语言会改变货币吗？

单靠切换语言不会。定价由 Shopify 的市场 (market) 和购物车的买家所在国家/地区决定，页面语言只决定显示哪种语言的译文。示例店面会明确地为每种语言对应一个市场，但你也可以让所有语言共用同一个市场，或单独提供一个国家/地区选择器。 (参见[语言与市场](/docs/integrations/shopify/reference/locale-handling#language-market)。)

## Next steps

- /docs/integrations/shopify/guides/localizing-react-router
- /docs/integrations/shopify/guides/localizing-nextjs
- /docs/integrations/shopify/guides/translating-products
- /docs/integrations/shopify/guides/selling-in-markets

## Sitemap

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