概览

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

const nextConfig = {
  // 你的 next.config.ts 配置项
};

export default withGTConfig(nextConfig, {
  // 你的 GT 配置
});

更多信息请参见withGTConfig API 参考。

`<GTProvider>` 组件

<GTProvider> 组件为你的应用提供翻译上下文，包括当前语言及其对应的翻译。

import { GTProvider } from 'gt-next';

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

重要： 该 provider 应当包裹整个应用，并尽可能放在组件树的最高层级，例如根布局中。

该 provider 仅在客户端功能中是必需的。仅服务端的应用不需要它，但仍可包含。

参见 GTProvider API 参考了解更多信息。

`<T>` 组件

<T> 组件是为应用内容提供翻译的推荐方式。

它是一个 React 组件，可用于包裹任意 JSX 元素，并会自动将该元素的内容渲染为受支持的语言版本。

我们建议尽可能使用 <T> 组件，因为它在翻译上提供了最大的灵活性。

与字符串不同，<T> 组件可以翻译 HTML 内容，因此比基于字符串的翻译更强大。

示例

<T>
  <div>你好，世界！</div>
</T>

<T>
  <div>
    <h1> 这里有一张图片 </h1>
    <img src="https://example.com/image.png" alt="示例" />
  </div>
</T>

<T>
  使用 `<T>` 组件即可轻松完成格式化。
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

<T> 组件可与变量组件（例如 <Num>、<DateTime> 和 <Currency>）配合，用于动态内容的格式化。

请参阅 <T> 组件指南，了解 <T> 组件的多种用法。

`useGT` 钩子

useGT 是一个 React 钩子，使用方式与 <T> 组件类似，但各有取舍。

该钩子会返回一个用于翻译字符串的函数。

const t = useGT();

t('你好，世界！');

与 <T> 组件相比，useGT 钩子能让你的代码更灵活。

例如，如果你有一个包含嵌套字符串的复杂数据结构，那么使用 <T> 组件会更费劲。

const t = useGT();
const data = {
  title: t('你好，世界！'),
  description: t('这是一个描述'),
};

请参见字符串指南，了解更多有关useGT Hook 的信息。

`msg` 函数

msg 函数用于标记需要翻译的字符串，这些字符串可能会在多个组件中复用，或存放在配置对象中。

这对共享内容（例如导航标签、表单消息，或在应用中多处出现的任意文本）尤其有用。

// 标注待翻译的字符串
import { msg } from 'gt-next';

const navItems = [
  { label: msg('首页'), href: '/' },
  { label: msg('关于我们'), href: '/about' },
  { label: msg('联系我们'), href: '/contact' }
];

// 解码并使用已标记的字符串
import { useMessages } from 'gt-next';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

msg 函数为字符串编码翻译元数据，而 useMessages（服务器组件使用 getMessages）负责解码。

将 msg 用于需要在整个应用中保持一致翻译的共享内容。对于特定于组件的内容，优先使用 <T> 或 useGT。

请参阅共享字符串指南，了解更多关于 msg 函数的信息。

`useTranslations` 钩子

useTranslations 是一个 React 钩子，返回一个函数，用于按给定键检索对应的翻译。

dictionary.ts

const dictionary = {
  hello: {
    world: '你好，世界！',
  },
};

App.tsx

const translate = useTranslations();
translate('hello.world');

这种行为与其他翻译库类似，例如 react-i18next 和 next-intl。

我们不建议在你的应用中使用 useTranslations 钩子。频繁使用 useTranslations 钩子会让你的代码库更难维护，并会造成大量技术债务。

我们建议改用 <T> 组件或 useGT 钩子。

如果你正从其他 i18n 库迁移，useTranslations 钩子可以直接替换，便于逐步迁移你的代码库。

参见 dictionaries 指南，了解更多有关 useTranslations 钩子的内容。

参见 useTranslations API 参考以获取更多信息。

后续步骤

了解如何使用 SDK 配置你的 Next.js 项目：快速入门
了解如何使用 <T> 组件翻译 JSX 内容：JSX 翻译指南
了解如何使用 useGT 钩子翻译字符串：字符串翻译指南
了解如何使用 msg 函数处理共享字符串：共享字符串指南

介绍

General Translation 的 Next.js SDK 是一个面向 Next.js 应用的开源国际化（i18n）库。

该 SDK 可在不依赖 General Translation 平台的情况下独立使用，行为与其他 i18n 库相似。

同时，它也可与我们的平台集成，解锁增强功能：

开发环境中的翻译热重载
自动 AI 翻译
与 General Translation 平台同步翻译
与我们的翻译 CDN（内容分发网络）原生集成
在生产环境中于服务器端对 React 组件进行按需翻译

概念

理解该 SDK 的 6 个核心概念：

使用 withGTConfig 进行初始化

<GTProvider> 组件

<T> 组件

useGT 钩子

用于共享字符串的 msg 函数

（可选）useTranslations 钩子

使用 `withGTConfig` 初始化

withGTConfig 函数会在你的 Next.js 应用中初始化 SDK。

将它添加到你的 next.config.[js|ts] 文件以配置 SDK：

next.config.ts

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

const nextConfig = {
  // 你的 next.config.ts 配置项
};

export default withGTConfig(nextConfig, {
  // 你的 GT 配置
});

更多信息请参见withGTConfig API 参考。

`<GTProvider>` 组件

<GTProvider> 组件为你的应用提供翻译上下文，包括当前语言及其对应的翻译。

import { GTProvider } from 'gt-next';

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

重要： 该 provider 应当包裹整个应用，并尽可能放在组件树的最高层级，例如根布局中。

该 provider 仅在客户端功能中是必需的。仅服务端的应用不需要它，但仍可包含。

参见 GTProvider API 参考了解更多信息。

`<T>` 组件

<T> 组件是为应用内容提供翻译的推荐方式。

它是一个 React 组件，可用于包裹任意 JSX 元素，并会自动将该元素的内容渲染为受支持的语言版本。

我们建议尽可能使用 <T> 组件，因为它在翻译上提供了最大的灵活性。

与字符串不同，<T> 组件可以翻译 HTML 内容，因此比基于字符串的翻译更强大。

示例

<T>
  <div>你好，世界！</div>
</T>

<T>
  <div>
    <h1> 这里有一张图片 </h1>
    <img src="https://example.com/image.png" alt="示例" />
  </div>
</T>

<T>
  使用 `<T>` 组件即可轻松完成格式化。
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

<T> 组件可与变量组件（例如 <Num>、<DateTime> 和 <Currency>）配合，用于动态内容的格式化。

请参阅 <T> 组件指南，了解 <T> 组件的多种用法。

`useGT` 钩子

useGT 是一个 React 钩子，使用方式与 <T> 组件类似，但各有取舍。

该钩子会返回一个用于翻译字符串的函数。

const t = useGT();

t('你好，世界！');

与 <T> 组件相比，useGT 钩子能让你的代码更灵活。

例如，如果你有一个包含嵌套字符串的复杂数据结构，那么使用 <T> 组件会更费劲。

const t = useGT();
const data = {
  title: t('你好，世界！'),
  description: t('这是一个描述'),
};

请参见字符串指南，了解更多有关useGT Hook 的信息。

`msg` 函数

msg 函数用于标记需要翻译的字符串，这些字符串可能会在多个组件中复用，或存放在配置对象中。

这对共享内容（例如导航标签、表单消息，或在应用中多处出现的任意文本）尤其有用。

// 标注待翻译的字符串
import { msg } from 'gt-next';

const navItems = [
  { label: msg('首页'), href: '/' },
  { label: msg('关于我们'), href: '/about' },
  { label: msg('联系我们'), href: '/contact' }
];

// 解码并使用已标记的字符串
import { useMessages } from 'gt-next';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

msg 函数为字符串编码翻译元数据，而 useMessages（服务器组件使用 getMessages）负责解码。

将 msg 用于需要在整个应用中保持一致翻译的共享内容。对于特定于组件的内容，优先使用 <T> 或 useGT。

请参阅共享字符串指南，了解更多关于 msg 函数的信息。

`useTranslations` 钩子

useTranslations 是一个 React 钩子，返回一个函数，用于按给定键检索对应的翻译。

dictionary.ts

const dictionary = {
  hello: {
    world: '你好，世界！',
  },
};

App.tsx

const translate = useTranslations();
translate('hello.world');

这种行为与其他翻译库类似，例如 react-i18next 和 next-intl。

我们不建议在你的应用中使用 useTranslations 钩子。频繁使用 useTranslations 钩子会让你的代码库更难维护，并会造成大量技术债务。

我们建议改用 <T> 组件或 useGT 钩子。

如果你正从其他 i18n 库迁移，useTranslations 钩子可以直接替换，便于逐步迁移你的代码库。

参见 dictionaries 指南，了解更多有关 useTranslations 钩子的内容。

参见 useTranslations API 参考以获取更多信息。

后续步骤

了解如何使用 SDK 配置你的 Next.js 项目：快速入门
了解如何使用 <T> 组件翻译 JSX 内容：JSX 翻译指南
了解如何使用 useGT 钩子翻译字符串：字符串翻译指南
了解如何使用 msg 函数处理共享字符串：共享字符串指南

介绍

General Translation 的 Next.js SDK 是一个面向 Next.js 应用的开源国际化（i18n）库。

该 SDK 可在不依赖 General Translation 平台的情况下独立使用，行为与其他 i18n 库相似。

同时，它也可与我们的平台集成，解锁增强功能：

开发环境中的翻译热重载
自动 AI 翻译
与 General Translation 平台同步翻译
与我们的翻译 CDN（内容分发网络）原生集成
在生产环境中于服务器端对 React 组件进行按需翻译

概念

理解该 SDK 的 6 个核心概念：

使用 withGTConfig 进行初始化

<GTProvider> 组件

<T> 组件

useGT 钩子

用于共享字符串的 msg 函数

（可选）useTranslations 钩子

使用 `withGTConfig` 初始化

withGTConfig 函数会在你的 Next.js 应用中初始化 SDK。

将它添加到你的 next.config.[js|ts] 文件以配置 SDK：

next.config.ts

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

const nextConfig = {
  // 你的 next.config.ts 配置项
};

export default withGTConfig(nextConfig, {
  // 你的 GT 配置
});

更多信息请参见withGTConfig API 参考。

`<GTProvider>` 组件

<GTProvider> 组件为你的应用提供翻译上下文，包括当前语言及其对应的翻译。

import { GTProvider } from 'gt-next';

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

重要： 该 provider 应当包裹整个应用，并尽可能放在组件树的最高层级，例如根布局中。

该 provider 仅在客户端功能中是必需的。仅服务端的应用不需要它，但仍可包含。

参见 GTProvider API 参考了解更多信息。

`<T>` 组件

<T> 组件是为应用内容提供翻译的推荐方式。

它是一个 React 组件，可用于包裹任意 JSX 元素，并会自动将该元素的内容渲染为受支持的语言版本。

我们建议尽可能使用 <T> 组件，因为它在翻译上提供了最大的灵活性。

与字符串不同，<T> 组件可以翻译 HTML 内容，因此比基于字符串的翻译更强大。

示例

<T>
  <div>你好，世界！</div>
</T>

<T>
  <div>
    <h1> 这里有一张图片 </h1>
    <img src="https://example.com/image.png" alt="示例" />
  </div>
</T>

<T>
  使用 `<T>` 组件即可轻松完成格式化。
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

<T> 组件可与变量组件（例如 <Num>、<DateTime> 和 <Currency>）配合，用于动态内容的格式化。

请参阅 <T> 组件指南，了解 <T> 组件的多种用法。

`useGT` 钩子

useGT 是一个 React 钩子，使用方式与 <T> 组件类似，但各有取舍。

该钩子会返回一个用于翻译字符串的函数。

const t = useGT();

t('你好，世界！');

与 <T> 组件相比，useGT 钩子能让你的代码更灵活。

例如，如果你有一个包含嵌套字符串的复杂数据结构，那么使用 <T> 组件会更费劲。

const t = useGT();
const data = {
  title: t('你好，世界！'),
  description: t('这是一个描述'),
};

请参见字符串指南，了解更多有关useGT Hook 的信息。

`msg` 函数

msg 函数用于标记需要翻译的字符串，这些字符串可能会在多个组件中复用，或存放在配置对象中。

这对共享内容（例如导航标签、表单消息，或在应用中多处出现的任意文本）尤其有用。

// 标注待翻译的字符串
import { msg } from 'gt-next';

const navItems = [
  { label: msg('首页'), href: '/' },
  { label: msg('关于我们'), href: '/about' },
  { label: msg('联系我们'), href: '/contact' }
];

// 解码并使用已标记的字符串
import { useMessages } from 'gt-next';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

msg 函数为字符串编码翻译元数据，而 useMessages（服务器组件使用 getMessages）负责解码。

将 msg 用于需要在整个应用中保持一致翻译的共享内容。对于特定于组件的内容，优先使用 <T> 或 useGT。

请参阅共享字符串指南，了解更多关于 msg 函数的信息。

`useTranslations` 钩子

useTranslations 是一个 React 钩子，返回一个函数，用于按给定键检索对应的翻译。

dictionary.ts

const dictionary = {
  hello: {
    world: '你好，世界！',
  },
};

App.tsx

const translate = useTranslations();
translate('hello.world');

这种行为与其他翻译库类似，例如 react-i18next 和 next-intl。

我们不建议在你的应用中使用 useTranslations 钩子。频繁使用 useTranslations 钩子会让你的代码库更难维护，并会造成大量技术债务。

我们建议改用 <T> 组件或 useGT 钩子。

如果你正从其他 i18n 库迁移，useTranslations 钩子可以直接替换，便于逐步迁移你的代码库。

参见 dictionaries 指南，了解更多有关 useTranslations 钩子的内容。

参见 useTranslations API 参考以获取更多信息。

后续步骤

了解如何使用 SDK 配置你的 Next.js 项目：快速入门
了解如何使用 <T> 组件翻译 JSX 内容：JSX 翻译指南
了解如何使用 useGT 钩子翻译字符串：字符串翻译指南
了解如何使用 msg 函数处理共享字符串：共享字符串指南

概览

介绍

概念

使用 `withGTConfig` 初始化

`<GTProvider>` 组件

`<T>` 组件

示例

`useGT` 钩子

`msg` 函数

`useTranslations` 钩子

后续步骤

本页目录

概览

介绍

概念

使用 `withGTConfig` 初始化

`<GTProvider>` 组件

`<T>` 组件

示例

`useGT` 钩子

`msg` 函数

`useTranslations` 钩子

后续步骤

本页目录

概览

介绍

概念

使用 `withGTConfig` 初始化

`<GTProvider>` 组件

`<T>` 组件

示例

`useGT` 钩子

`msg` 函数

`useTranslations` 钩子

后续步骤

本页目录

在 GitHub 上加星标

在 GitHub 上加星标

概览

本页目录

概览

本页目录

概览

本页目录

GitHub在 GitHub 上加星标

GitHub在 GitHub 上加星标

在 GitHub 上加星标

在 GitHub 上加星标