# gt-next: General Translation Next.js SDK: Pages Router 快速开始
URL: https://generaltranslation.com/zh/docs/next/tutorials/quickstart-pages-router.mdx
---
title: Pages Router 快速开始
description: 在 10 分钟内为你的 Next.js Pages Router 应用添加多语言支持
---

完成本指南后，你的 Next.js Pages Router 应用将能以多种语言显示内容，并提供一个可供用户切换的 语言切换器。

在 Pages Router 中，`gt-next` 通过 `getServerSideProps` 运行：每次收到请求时，服务器都会解析用户的区域设置，加载翻译快照，并将二者传递给 `_app.tsx` 中的 `<GTProvider>`，因此首次渲染时内容就已经是翻译后的。

**前提条件：**

* 一个使用 **Pages Router** 的 Next.js 应用
* Node.js 18+

<Callout type="info">
  **在使用 App Router？** 请改用 [Next.js 快速开始](/docs/next)——它使用服务器组件，不需要任何 `getServerSideProps` 配置。
</Callout>

***

## 第 1 步：安装软件包

`gt-next` 是为你的应用提供翻译功能的库。`gt` 是用于为生产环境准备翻译的 CLI 工具。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-next
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-next
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-next
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-next
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

***

## 第 2 步：配置 Next.js config

`gt-next` 使用名为 **`withGTConfig`** 的 Next.js 插件，在构建时完成国际化配置。请用它包装你现有的 Next.js config：

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';

const nextConfig = {};

export default withGTConfig(nextConfig);
```

这个插件会读取你的翻译设置，并在幕后把一切都串联起来。App Router 和 Pages Router 的配置完全一致，无需任何路由器专用标志。

***

## 第 3 步：创建翻译配置文件

在项目根目录中创建一个 **`gt.config.json`** 文件，用于告诉该库你支持哪些语言：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}
```

* **`defaultLocale`** — 你的应用编写所用的语言 (即源语言) 。
* **`locales`** — 你希望翻译成的语言。可从[支持的区域设置列表](/docs/platform/supported-locales)中任选。
* **`files.gt.output`** — CLI 保存翻译文件的位置。`[locale]` 会替换为各语言代码 (例如 `public/_gt/es.json`) 。

将 `public/_gt/` 添加到你的 **`.gitignore`** 中——这些文件是自动生成的，不是手写的：

```txt title=".gitignore"
public/_gt/
```

***

## 第 4 步：为本地翻译添加 load function

在项目根目录 (或 `src/` 目录) 中创建一个 **`loadTranslations`** 文件。这会告诉 `gt-next` 如何加载由 CLI 生成的翻译文件：

```ts title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`./public/_gt/${locale}.json`);
    return translations.default;
  } catch {
    return {};
  }
}
```

`withGTConfig` 会自动检测项目根目录或 `src/` 目录中的 `loadTranslations.[js|ts]` 文件——无需任何额外配置。

<Callout type="info">
  **为什么使用本地翻译？** 本地翻译会随应用一同打包，因此能够即时加载，无需依赖外部服务。更多详情及相关取舍，请参阅[本地翻译存储指南](/docs/next/guides/local-tx)。
</Callout>

***

## 第 5 步：包装页面中的 getServerSideProps

使用 **`withGTServerSideProps`** 包装每个页面的 `getServerSideProps`。对于每个请求，它都会确定用户的区域设置：如果设置了 `generaltranslation.locale` cookie，则从中获取；否则从 `Accept-Language` header 获取。然后加载该区域设置对应的翻译快照，并将两者一并注入页面属性中：

```tsx title="pages/index.tsx"
import type { GetServerSideProps } from 'next';
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps: GetServerSideProps = withGTServerSideProps(
  async (context) => {
    return {
      props: {
        // 你自己的属性
      },
    };
  }
);
```

如果某个页面本身不需要服务端属性，就直接不带参数调用它：

```tsx title="pages/about.tsx"
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps = withGTServerSideProps();
```

`withGTServerSideProps` 会将 `locale` 和 `translations` 添加到你的属性中 (以及一个内部使用的 `enableI18n` 标志) 。如果内部函数返回 `redirect` 或 `notFound`，它会直接原样返回结果，不会加载翻译内容。

***

## 第 6 步：将 GTProvider 添加到你的应用中

**`GTProvider`** 组件可让整个应用访问翻译内容。在 `_app.tsx` 中，从 `pageProps` 中取出注入的属性，并将其传给该 provider。**`WithGTServerSideProps`** 类型描述了这些注入属性的结构：

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import { GTProvider, WithGTServerSideProps } from 'gt-next';

export default function App({
  Component,
  pageProps,
}: AppProps<WithGTServerSideProps>) {
  const { locale, translations, ...restPageProps } = pageProps;

  return (
    <GTProvider locale={locale} translations={translations}>
      <Component {...restPageProps} />
    </GTProvider>
  );
}
```

由于区域设置和翻译会随服务器响应一同返回，因此首次渲染时就已是用户所用的语言——无需客户端加载状态。

***

## 第 7 步：将内容标记为可翻译

现在，用 **`<T>`** 组件包裹任何你想翻译的文本。`<T>` 代表 &quot;translate&quot;：

```tsx title="pages/index.tsx"
import { T } from 'gt-next';

export default function Home() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

你可以在 `<T>` 中包裹任意多或任意少的 JSX。其中的所有内容——文本、嵌套元素，甚至格式——都会作为一个整体进行翻译。

***

## 第 8 步：添加语言切换器

添加一个 **`<LocaleSelector>`**，让用户可以切换语言：

```tsx title="pages/index.tsx"
import { T, LocaleSelector } from 'gt-next';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

`LocaleSelector` 会渲染一个下拉菜单，菜单中的语言选项来自你的 `gt.config.json`。当用户选择一种语言时，`gt-next` 会将该选择保存到 `generaltranslation.locale` cookie 中，并重新加载页面，让服务器以新的区域设置重新渲染所有内容。

***

## 第 9 步：设置环境变量 (可选) 

要在开发环境中查看翻译效果，你需要 General Translation 提供的 API 密钥。有了它们，就能启用**按需翻译**——也就是在开发过程中，应用会实时翻译内容。

创建一个 **`.env.local`** 文件：

```bash title=".env.local"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

前往 [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) 获取免费密钥，或运行：

```bash
npx gt auth
```

<Callout type="warn">
  开发环境请使用以 `gtx-dev-` 开头的密钥。生产环境密钥 (`gtx-api-`) 仅用于 CI/CD。

  切勿将 `GT_API_KEY` 暴露给浏览器，也不要将其提交到版本控制中。
</Callout>

***

## 第 10 步：查看效果

启动开发服务器：

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

打开 [http://localhost:3000](http://localhost:3000)，然后通过语言下拉菜单切换语言。你应该会看到内容已被翻译。

<Callout type="info">
  在开发环境中，翻译是按需进行的——首次切换到某种新语言时，你可能会看到短暂的加载状态。在生产环境中，翻译会预先生成，因此会立即加载。
</Callout>

***

## 第 11 步：翻译字符串 (不只是 JSX) 

对于普通文本字符串——例如 `placeholder` 属性、`aria-label` 值或 `alt` 文本——请使用 **`useGT`** 钩子：

```tsx title="pages/contact.tsx"
import { useGT } from 'gt-next';

export default function ContactPage() {
  const gt = useGT();

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

***

## 步骤 12：部署到生产环境

在生产环境中，翻译会在构建时预先生成 (不会发起实时 API 调用) 。将 `translate` 命令添加到你的构建脚本中：

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && next build"
  }
}
```

在托管服务提供商 (Vercel、Netlify 等) 中设置 **生产环境** 变量：

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  生产密钥以 `gtx-api-` 开头 (不是 `gtx-dev-`) 。请前往 [dash.generaltranslation.com](https://dash.generaltranslation.com) 获取。切勿添加 `NEXT_PUBLIC_` 前缀。
</Callout>

就是这样——你的应用现已支持多语言。🎉

***

## 故障排查

<Accordions>
  <Accordion title="每个页面都需要使用 withGTServerSideProps 吗？">
    是的，`<GTProvider>` 需要 `locale` 和 `translations` 属性，而这些属性只会出现在 `getServerSideProps` 经过包装的页面上。对于不自行获取数据的页面，请导出无参数形式：

    ```tsx
    export const getServerSideProps = withGTServerSideProps();
    ```
  </Accordion>

  <Accordion title="可以改用 getStaticProps 吗？">
    不可以。解析区域设置需要用到每个请求的数据 (区域设置 cookie 和 `Accept-Language` header) ，而这些数据在静态生成期间不可用。`gt-next` 没有为 Pages Router 提供 `getStaticProps` 辅助函数。
  </Accordion>

  <Accordion title="使用 dropdown 时，语言没有切换">
    `gt-next` 会将用户的语言偏好存储在名为 `generaltranslation.locale` 的 cookie 中。如果你之前测试过其他语言，这个 cookie 可能会覆盖你的选择。请清除 cookie 后重试。

    * [Chrome](https://support.google.com/chrome/answer/95647)
    * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
    * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
  </Accordion>

  <Accordion title="开发环境下翻译速度很慢">
    这是正常现象。在开发环境中，翻译是按需进行的 (你的内容会通过 API 实时翻译) 。这种延迟**在生产环境中不会出现**——所有翻译都会由 `npx gt translate` 预先生成。
  </Accordion>
</Accordions>

***

## 后续步骤

* [**`<T>` 组件指南**](/docs/next/guides/t) — 了解变量、复数形式以及高级翻译模式
* [**字符串翻译指南**](/docs/next/guides/strings) — 深入了解 `useGT`
* [**变量组件**](/docs/next/guides/variables) — 使用 `<Var>`、`<Num>`、`<Currency>` 和 `<DateTime>` 处理动态内容
* [**复数处理**](/docs/next/api/components/plural) — 使用 `<Plural>` 组件处理复数形式
* [**部署到生产环境**](/docs/next/tutorials/quickdeploy) — CI/CD 设置、缓存和性能优化
* [**共享字符串**](/docs/next/guides/shared-strings) — 使用 `msg()` 翻译数组、配置对象和共享数据中的文本