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

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

环境变量

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

.env.local

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

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

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

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。

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

测试你的应用

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

添加语言环境选择下拉菜单，使用<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 函数除外）。

获取生产环境 API key，前往 dash.generaltranslation.com。

生产环境密钥以 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"]
}

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

环境变量

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

.env.local

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

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

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

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。

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

测试你的应用

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

添加语言环境选择下拉菜单，使用<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 函数除外）。

获取生产环境 API key，前往 dash.generaltranslation.com。

生产环境密钥以 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"]
}

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

环境变量

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

.env.local

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

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

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

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。

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

测试你的应用

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

添加语言环境选择下拉菜单，使用<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 函数除外）。

获取生产环境 API key，前往 dash.generaltranslation.com。

生产环境密钥以 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 上加星标