Next.js 快速上手

先决条件： Next.js App Router，基础 JavaScript 知识

快速设置： 试试 npx gtx-cli@latest 进行自动配置。请查看设置向导或使用我们的AI 工具集成。

安装

安装 gt-next 与 gtx-cli 包：

npm i gt-next gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

配置

`withGTConfig`

withGTConfig 函数用于在你的 Next.js 应用中初始化 SDK。将它添加到你的 next.config.[js|ts] 文件：

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // 你现有的 Next.js 配置
};

export default withGTConfig(nextConfig, {
  // 其他 GT 的配置选项
});

`GTProvider`

GTProvider 组件为客户端组件提供翻译上下文。它负责管理 locale 状态与翻译，并启用 useGT 和 useTranslations 钩子。

将 GTProvider 添加到根布局（们）中：

app/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

在项目根目录创建一个 gt.config.json 文件：

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

为你的项目自定义 locale。查看支持的 locales以了解可用的 options。

环境变量

在开发环境下启用热重载时，将以下内容添加到 .env.local 文件：

.env.local

GT_API_KEY="你的开发 API 密钥"
GT_PROJECT_ID="你的项目 ID"

仅限开发环境： 不要在生产环境中设置 GT_API_KEY，它仅用于开发时的热重载。

在 dash.generaltranslation.com 获取免费的 API Keys，或运行：

npx gtx-cli auth

使用方法

现在你可以开始为内容做国际化了。主要有两种方式：

含有 `<T>` 的 JSX 内容

将 JSX 元素包裹起来，以使用 <T> 组件进行翻译：

import { T } from 'gt-next';

function Welcome() {
  return (
    <T>
      <h1>欢迎使用我们的应用！</h1>
    </T>
  );
}

对于动态内容，请使用变量组件，例如 <Var>：

import { T, Var } from 'gt-next';

function Greeting({ user }) {
  return (
    <T>
      <p>你好，<Var>{user.name}</Var>！</p>
    </T>
  );
}

更多信息请参见《使用 <T> 组件》指南。

使用 `useGT` 处理纯文本字符串

对于通过 useGT 钩子获取的属性、标签和纯文本：

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('请输入邮箱')}
      aria-label={t('邮箱输入框')}
    />
  );
}

对于服务端组件，请使用 getGT，而不要使用 useGT。

更多信息请参见字符串翻译指南。

测试你的应用

通过切换语言来测试翻译效果：

添加一个 locale 选择下拉菜单，使用 <LocaleSelector>：

import { LocaleSelector } from 'gt-next';

function App() {
  return <LocaleSelector />;
}

启动开发服务器：

npm run dev

yarn run dev

bun run dev

pnpm run dev

访问 localhost:3000，并通过 locale 选择下拉菜单切换语言。

在开发环境中，翻译按需进行（会有短暂的加载时间）。在生产环境中，内容均已预翻译。

疑难解答

部署

在生产环境中，你需要预先完成内容翻译，因为运行时翻译已被禁用（<Tx> 和 tx 函数除外）。

从 dash.generaltranslation.com 获取生产环境 API 密钥。

生产密钥以 gtx-api- 开头（不同于开发密钥，以 gtx-dev- 开头）。了解更多环境差异。
添加到你的 CI/CD 环境：
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
切勿为生产密钥添加 NEXT_PUBLIC_ 前缀——它们应仅用于服务端（server-side）。
运行 translate 命令以翻译你的内容：
```
npx gtx-cli translate
```
你可以使用 gt.config.json 文件配置 translate 命令的行为。

更多信息请参阅 CLI 工具参考指南。

更新你的构建脚本，在构建前执行翻译：

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

后续步骤

<T> 组件指南 - 深入讲解 <T> 组件与 JSX 翻译
字符串翻译指南 - 了解如何使用 useGT 和 getGT
变量组件 - 使用 <Var>、<Num> 等处理动态内容

先决条件： Next.js App Router，基础 JavaScript 知识

快速设置： 试试 npx gtx-cli@latest 进行自动配置。请查看设置向导或使用我们的AI 工具集成。

安装

安装 gt-next 与 gtx-cli 包：

npm i gt-next gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

配置

`withGTConfig`

withGTConfig 函数用于在你的 Next.js 应用中初始化 SDK。将它添加到你的 next.config.[js|ts] 文件：

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // 你现有的 Next.js 配置
};

export default withGTConfig(nextConfig, {
  // 其他 GT 的配置选项
});

`GTProvider`

GTProvider 组件为客户端组件提供翻译上下文。它负责管理 locale 状态与翻译，并启用 useGT 和 useTranslations 钩子。

将 GTProvider 添加到根布局（们）中：

app/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

在项目根目录创建一个 gt.config.json 文件：

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

为你的项目自定义 locale。查看支持的 locales以了解可用的 options。

环境变量

在开发环境下启用热重载时，将以下内容添加到 .env.local 文件：

.env.local

GT_API_KEY="你的开发 API 密钥"
GT_PROJECT_ID="你的项目 ID"

仅限开发环境： 不要在生产环境中设置 GT_API_KEY，它仅用于开发时的热重载。

在 dash.generaltranslation.com 获取免费的 API Keys，或运行：

npx gtx-cli auth

使用方法

现在你可以开始为内容做国际化了。主要有两种方式：

含有 `<T>` 的 JSX 内容

将 JSX 元素包裹起来，以使用 <T> 组件进行翻译：

import { T } from 'gt-next';

function Welcome() {
  return (
    <T>
      <h1>欢迎使用我们的应用！</h1>
    </T>
  );
}

对于动态内容，请使用变量组件，例如 <Var>：

import { T, Var } from 'gt-next';

function Greeting({ user }) {
  return (
    <T>
      <p>你好，<Var>{user.name}</Var>！</p>
    </T>
  );
}

更多信息请参见《使用 <T> 组件》指南。

使用 `useGT` 处理纯文本字符串

对于通过 useGT 钩子获取的属性、标签和纯文本：

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('请输入邮箱')}
      aria-label={t('邮箱输入框')}
    />
  );
}

对于服务端组件，请使用 getGT，而不要使用 useGT。

更多信息请参见字符串翻译指南。

测试你的应用

通过切换语言来测试翻译效果：

添加一个 locale 选择下拉菜单，使用 <LocaleSelector>：

import { LocaleSelector } from 'gt-next';

function App() {
  return <LocaleSelector />;
}

启动开发服务器：

npm run dev

yarn run dev

bun run dev

pnpm run dev

访问 localhost:3000，并通过 locale 选择下拉菜单切换语言。

在开发环境中，翻译按需进行（会有短暂的加载时间）。在生产环境中，内容均已预翻译。

疑难解答

部署

在生产环境中，你需要预先完成内容翻译，因为运行时翻译已被禁用（<Tx> 和 tx 函数除外）。

从 dash.generaltranslation.com 获取生产环境 API 密钥。

生产密钥以 gtx-api- 开头（不同于开发密钥，以 gtx-dev- 开头）。了解更多环境差异。
添加到你的 CI/CD 环境：
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
切勿为生产密钥添加 NEXT_PUBLIC_ 前缀——它们应仅用于服务端（server-side）。
运行 translate 命令以翻译你的内容：
```
npx gtx-cli translate
```
你可以使用 gt.config.json 文件配置 translate 命令的行为。

更多信息请参阅 CLI 工具参考指南。

更新你的构建脚本，在构建前执行翻译：

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

后续步骤

<T> 组件指南 - 深入讲解 <T> 组件与 JSX 翻译
字符串翻译指南 - 了解如何使用 useGT 和 getGT
变量组件 - 使用 <Var>、<Num> 等处理动态内容

先决条件： Next.js App Router，基础 JavaScript 知识

快速设置： 试试 npx gtx-cli@latest 进行自动配置。请查看设置向导或使用我们的AI 工具集成。

安装

安装 gt-next 与 gtx-cli 包：

npm i gt-next gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

配置

`withGTConfig`

withGTConfig 函数用于在你的 Next.js 应用中初始化 SDK。将它添加到你的 next.config.[js|ts] 文件：

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // 你现有的 Next.js 配置
};

export default withGTConfig(nextConfig, {
  // 其他 GT 的配置选项
});

`GTProvider`

GTProvider 组件为客户端组件提供翻译上下文。它负责管理 locale 状态与翻译，并启用 useGT 和 useTranslations 钩子。

将 GTProvider 添加到根布局（们）中：

app/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

在项目根目录创建一个 gt.config.json 文件：

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

为你的项目自定义 locale。查看支持的 locales以了解可用的 options。

环境变量

在开发环境下启用热重载时，将以下内容添加到 .env.local 文件：

.env.local

GT_API_KEY="你的开发 API 密钥"
GT_PROJECT_ID="你的项目 ID"

仅限开发环境： 不要在生产环境中设置 GT_API_KEY，它仅用于开发时的热重载。

在 dash.generaltranslation.com 获取免费的 API Keys，或运行：

npx gtx-cli auth

使用方法

现在你可以开始为内容做国际化了。主要有两种方式：

含有 `<T>` 的 JSX 内容

将 JSX 元素包裹起来，以使用 <T> 组件进行翻译：

import { T } from 'gt-next';

function Welcome() {
  return (
    <T>
      <h1>欢迎使用我们的应用！</h1>
    </T>
  );
}

对于动态内容，请使用变量组件，例如 <Var>：

import { T, Var } from 'gt-next';

function Greeting({ user }) {
  return (
    <T>
      <p>你好，<Var>{user.name}</Var>！</p>
    </T>
  );
}

更多信息请参见《使用 <T> 组件》指南。

使用 `useGT` 处理纯文本字符串

对于通过 useGT 钩子获取的属性、标签和纯文本：

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('请输入邮箱')}
      aria-label={t('邮箱输入框')}
    />
  );
}

对于服务端组件，请使用 getGT，而不要使用 useGT。

更多信息请参见字符串翻译指南。

测试你的应用

通过切换语言来测试翻译效果：

添加一个 locale 选择下拉菜单，使用 <LocaleSelector>：

import { LocaleSelector } from 'gt-next';

function App() {
  return <LocaleSelector />;
}

启动开发服务器：

npm run dev

yarn run dev

bun run dev

pnpm run dev

访问 localhost:3000，并通过 locale 选择下拉菜单切换语言。

在开发环境中，翻译按需进行（会有短暂的加载时间）。在生产环境中，内容均已预翻译。

疑难解答

部署

在生产环境中，你需要预先完成内容翻译，因为运行时翻译已被禁用（<Tx> 和 tx 函数除外）。

从 dash.generaltranslation.com 获取生产环境 API 密钥。

生产密钥以 gtx-api- 开头（不同于开发密钥，以 gtx-dev- 开头）。了解更多环境差异。
添加到你的 CI/CD 环境：
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
切勿为生产密钥添加 NEXT_PUBLIC_ 前缀——它们应仅用于服务端（server-side）。
运行 translate 命令以翻译你的内容：
```
npx gtx-cli translate
```
你可以使用 gt.config.json 文件配置 translate 命令的行为。

更多信息请参阅 CLI 工具参考指南。

更新你的构建脚本，在构建前执行翻译：

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

后续步骤

<T> 组件指南 - 深入讲解 <T> 组件与 JSX 翻译
字符串翻译指南 - 了解如何使用 useGT 和 getGT
变量组件 - 使用 <Var>、<Num> 等处理动态内容

Next.js 快速上手

如果我不想使用 General Translation 平台怎么办？

即使我更改了浏览器语言，我的应用语言仍未变化，该怎么办？

为什么在开发环境中加载语言很慢？

为什么有些翻译不准确？

如果我没有使用 General Translation 平台怎么办？

本页目录

Next.js 快速上手

如果我不想使用 General Translation 平台怎么办？

即使我更改了浏览器语言，我的应用语言仍未变化，该怎么办？

为什么在开发环境中加载语言很慢？

为什么有些翻译不准确？

如果我没有使用 General Translation 平台怎么办？

本页目录

Next.js 快速上手

如果我不想使用 General Translation 平台怎么办？

即使我更改了浏览器语言，我的应用语言仍未变化，该怎么办？

为什么在开发环境中加载语言很慢？

为什么有些翻译不准确？

如果我没有使用 General Translation 平台怎么办？

本页目录

GitHub在 GitHub 上加星标

GitHub在 GitHub 上加星标

在 GitHub 上加星标

在 GitHub 上加星标