GitHub

前置条件： Next.js App Router、基础 JavaScript 知识

安装

安装 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

快速开始： 试试 npx gtx-cli@latest 自动完成配置。参阅设置向导或使用我们的AI 工具集成。

配置

`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"]
}

为你的项目自定义 locales。有关可用选项，请参阅支持的 locales。

环境变量

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

.env.local

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

仅限开发环境： 请勿在生产环境中设置 GT_API_KEY —— 它仅用于开发阶段的热重载。

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

npx gtx-cli auth

用法

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

使用 `<T>` 的 JSX 内容

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

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。

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

测试你的应用

通过切换语言来验证翻译效果：

添加语言选择下拉菜单，使用 <LocaleSelector>：

import { LocaleSelector } from 'gt-next';

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

启动开发服务器：

npm run dev

yarn run dev

bun run dev

pnpm run dev

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

开发环境下，翻译为按需加载（会有短暂的加载时间）；生产环境下，内容已预先翻译完成。

疑难解答

部署

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

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

生产环境的密钥以 gtx-api- 开头（不同于开发环境密钥，它以 gtx-dev- 开头）。了解更多环境差异。
添加到你的 CI/CD 环境：
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
生产密钥切勿加上 NEXT_PUBLIC_ 前缀——它们应仅用于服务端。
运行 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 知识

安装

安装 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

快速开始： 试试 npx gtx-cli@latest 自动完成配置。参阅设置向导或使用我们的AI 工具集成。

配置

`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"]
}

为你的项目自定义 locales。有关可用选项，请参阅支持的 locales。

环境变量

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

.env.local

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

仅限开发环境： 请勿在生产环境中设置 GT_API_KEY —— 它仅用于开发阶段的热重载。

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

npx gtx-cli auth

用法

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

使用 `<T>` 的 JSX 内容

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

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。

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

测试你的应用

通过切换语言来验证翻译效果：

添加语言选择下拉菜单，使用 <LocaleSelector>：

import { LocaleSelector } from 'gt-next';

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

启动开发服务器：

npm run dev

yarn run dev

bun run dev

pnpm run dev

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

开发环境下，翻译为按需加载（会有短暂的加载时间）；生产环境下，内容已预先翻译完成。

疑难解答

部署

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

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

生产环境的密钥以 gtx-api- 开头（不同于开发环境密钥，它以 gtx-dev- 开头）。了解更多环境差异。
添加到你的 CI/CD 环境：
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
生产密钥切勿加上 NEXT_PUBLIC_ 前缀——它们应仅用于服务端。
运行 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 知识

安装

安装 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

快速开始： 试试 npx gtx-cli@latest 自动完成配置。参阅设置向导或使用我们的AI 工具集成。

配置

`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"]
}

为你的项目自定义 locales。有关可用选项，请参阅支持的 locales。

环境变量

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

.env.local

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

仅限开发环境： 请勿在生产环境中设置 GT_API_KEY —— 它仅用于开发阶段的热重载。

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

npx gtx-cli auth

用法

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

使用 `<T>` 的 JSX 内容

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

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。

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

测试你的应用

通过切换语言来验证翻译效果：

添加语言选择下拉菜单，使用 <LocaleSelector>：

import { LocaleSelector } from 'gt-next';

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

启动开发服务器：

npm run dev

yarn run dev

bun run dev

pnpm run dev

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

开发环境下，翻译为按需加载（会有短暂的加载时间）；生产环境下，内容已预先翻译完成。

疑难解答

部署

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

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

生产环境的密钥以 gtx-api- 开头（不同于开发环境密钥，它以 gtx-dev- 开头）。了解更多环境差异。
添加到你的 CI/CD 环境：
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
生产密钥切勿加上 NEXT_PUBLIC_ 前缀——它们应仅用于服务端。
运行 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 上加星