# gt-next: General Translation Next.js SDK: 概述
URL: https://generaltranslation.com/zh/docs/next/introduction.mdx
---
title: 概述
description: General Translation 的 Next.js SDK 概览
---
## 简介
General Translation Next.js SDK 是一个用于 Next.js 应用的开源国际化 (i18n) 库。
它提供了一套完善的工具，帮助你以简单且易于维护的方式为 Next.js 应用实现国际化，并与其他流行的 i18n 库保持功能对等。它基于 [React SDK](/docs/react) 构建，并额外提供了 Next.js 特有的功能。
该 SDK 无需依赖 General Translation 平台即可独立使用，其行为与其他 i18n 库类似。
不过，它也可以与我们的平台集成，以获得更多增强功能：
* 开发环境中的翻译热重载
* 自动 AI 翻译
* 与 General Translation 平台同步翻译
* 与我们的翻译 CDN 原生集成
* 在生产环境中对 React 组件进行 on-demand 翻译 (服务器端)
## 概念
关于 SDK，有 6 个需要理解的核心概念。
使用 [`withGTConfig`](/docs/next/api/config/with-gt-config) 初始化
[``](/docs/next/api/components/gtprovider) 组件
[``](/docs/next/api/components/t) 组件
[`useGT`](/docs/next/api/strings/use-gt) Hook
用于共享字符串的 [`msg`](/docs/next/api/strings/msg) 函数
(可选) [`useTranslations`](/docs/next/api/dictionary/use-translations) Hook
## 使用 `withGTConfig` 进行初始化
[`withGTConfig`](/docs/next/api/config/with-gt-config) 函数用于在你的 Next.js 应用中初始化 SDK。
将其添加到 `next.config.[js|ts]` 文件中，以配置 SDK：
```tsx title="next.config.ts"
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// 你的 next.config.ts 选项
};
export default withGTConfig(nextConfig, {
// 你的 GT 配置
});
```
更多信息，请参阅 [withGTConfig API 参考文档](/docs/next/api/config/with-gt-config)。
## `` 组件
[``](/docs/next/api/components/gtprovider) 组件为你的应用提供翻译上下文，包括当前语言以及相应的译文。
```tsx
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
**重要：** 该 Provider 应包裹整个应用，并尽量放在组件树的最上层，例如放在根布局中。
只有客户端功能才需要该 Provider。纯服务器端应用不需要它，但仍然可以包含它。
更多信息请参阅 [`GTProvider`](/docs/next/api/components/gtprovider) API 参考。
## `` 组件
[``](/docs/next/api/components/t) 组件是在应用中翻译内容的推荐方式。
它是一个 React 组件，可用于包裹任何 JSX 元素，并自动将元素内容渲染为受支持的语言。
我们建议尽可能使用 [``](/docs/next/api/components/t) 组件，因为它能为翻译提供最大的灵活性。
与字符串不同，[``](/docs/next/api/components/t) 组件还可用于翻译 HTML 内容，因此比字符串翻译更强大。
### 示例
```tsx
Hello, world!
```
```tsx
Here is an image
```
```tsx
Formatting can be done easily with the `` component.
{1000}
{new Date()}
{1000}
```
[``](/docs/next/api/components/t) 组件可与[变量组件](/docs/next/guides/variables) (如 [``](/docs/next/api/components/num)、[``](/docs/next/api/components/datetime) 和 [``](/docs/next/api/components/currency)) 配合使用，用于动态内容格式化。
请参阅 [`` 组件指南](/docs/next/guides/t)，了解 [``](/docs/next/api/components/t) 组件的不同用法。
## `useGT` Hook
[`useGT`](/docs/next/api/strings/use-gt) Hook 是一个 React Hook，用法与 [``](/docs/next/api/components/t) 组件类似，但需要做一些取舍。
该 Hook 会返回一个可用于翻译字符串的函数。
```tsx
const gt = useGT();
gt('Hello, world!');
```
与 [``](/docs/next/api/components/t) 组件相比，[`useGT`](/docs/next/api/strings/use-gt) Hook 能为你的代码库提供更高的灵活性。
例如，如果你的数据结构比较复杂，且包含嵌套的字符串，[``](/docs/next/api/components/t) 组件就没那么容易使用。
```tsx
const gt = useGT();
const data = {
title: gt('Hello, world!'),
description: gt('This is a description'),
};
```
请参阅[strings](/docs/next/guides/strings)指南，进一步了解[`useGT`](/docs/next/api/strings/use-gt) Hook。
## `msg` 函数
[`msg`](/docs/next/api/strings/msg) 函数用于标记需要翻译的字符串，这类字符串通常会在多个组件之间复用，或存储在设置对象中。
这对导航标签、表单消息等共享内容尤其有用，也适用于应用中会在多个位置重复出现的任何文本。
```tsx
// 标记字符串以供翻译
import { msg } from 'gt-next';
const navItems = [
{ label: msg('Home'), href: '/' },
{ label: msg('About'), href: '/about' },
{ label: msg('Contact'), href: '/contact' }
];
```
```tsx
// 解码并使用已标记的字符串
import { useMessages } from 'gt-next';
function Navigation() {
const m = useMessages();
return (
);
}
```
[`msg`](/docs/next/api/strings/msg) 函数会将字符串连同翻译元数据一起编码，而 [`useMessages`](/docs/next/api/strings/use-messages) (服务端组件中则使用 [`getMessages`](/docs/next/api/strings/get-messages)) 会对其进行解码。
对于需要在整个应用中保持翻译一致的共享内容，请使用 [`msg`](/docs/next/api/strings/msg)。对于组件特有的内容，优先使用 [``](/docs/next/api/components/t) 或 [`useGT`](/docs/next/api/strings/use-gt)。
参阅[共享字符串](/docs/next/guides/shared-strings)指南，详细了解 `msg` 函数。
## `useTranslations` Hook
[`useTranslations`](/docs/next/api/dictionary/use-translations) Hook 是一个 React Hook，会返回一个可用于获取指定键对应翻译的函数。
```tsx title="dictionary.ts"
const dictionary = {
hello: {
world: 'Hello, world!',
},
};
```
```tsx title="App.tsx"
const translate = useTranslations();
translate('hello.world');
```
这种行为与其他翻译库类似，例如 [`react-i18next`](https://react.i18next.com/) 和 [`next-intl`](https://next-intl-docs.vercel.app/)。
我们不建议你在应用程序中使用 [`useTranslations`](/docs/next/api/dictionary/use-translations) Hook。频繁使用 [`useTranslations`](/docs/next/api/dictionary/use-translations) Hook 会让你的代码库更难维护，
并带来大量技术债。
相反，我们建议使用 [``](/docs/next/api/components/t) 组件或 [`useGT`](/docs/next/api/strings/use-gt) Hook。
如果你正从其他 i18n 库迁移，[`useTranslations`](/docs/next/api/dictionary/use-translations) Hook 可以直接替换原有方案，也适合用来逐步迁移你的代码库。
请参阅[字典](/docs/next/guides/dictionaries)指南，进一步了解 [`useTranslations`](/docs/next/api/dictionary/use-translations) Hook。
如需更多信息，请参阅 [useTranslations API 参考](/docs/next/api/dictionary/use-translations)。
***
## 后续步骤
**查看实际效果：** 浏览展示各种 pattern 的[可运行示例应用](/docs/next/tutorials/examples)，或探索完整的[应用目录](https://app-catalog.generaltranslation.dev)。
* 了解如何使用 SDK 设置 Next.js 项目：[快速入门](/docs/next)
* 了解如何使用 [``](/docs/next/api/components/t) 组件翻译 JSX 内容：[JSX 翻译指南](/docs/next/guides/t)
* 了解如何使用 [`useGT`](/docs/next/api/strings/use-gt) Hook 翻译字符串：[字符串翻译指南](/docs/next/guides/strings)
* 了解如何使用 [`msg`](/docs/next/api/strings/msg) 函数实现共享字符串：[共享字符串指南](/docs/next/guides/shared-strings)