概述

介绍

General Translation Next.js SDK 是一个用于 Next.js 的开源国际化 (i18n) 库。

它提供了一套工具来帮助您以简单且可维护的方式对 Next.js 应用程序进行国际化，具有与其他流行 i18n 库相同的功能特性。它基于 React SDK 构建，并提供了 Next.js 特有的额外功能。

Next.js SDK 可以在不使用 General Translation 平台的情况下使用，其行为与其他 i18n 库非常相似。

但是，它也与我们的平台集成，提供额外功能，例如：

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

概念

关于 SDK 有 5 个主要概念需要理解。

使用 withGTConfig 进行初始化

<GTProvider> 组件

<T> 组件

useGT hook

（可选）useTranslations hook

使用 `withGTConfig` 初始化

withGTConfig 函数是用于在 Next.js 应用程序中初始化 SDK 的函数。

它应该放置在您的 next.config.[js|ts] 文件中，用于配置 SDK。

next.config.ts

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

const nextConfig = {
  // Your next.config.ts options
};

export default withGTConfig(nextConfig, {
  // Your GT configuration
});

查看 withGTConfig API 参考了解更多信息。

`<GTProvider>` 组件

import { GTProvider } from 'gt-next';

<GTProvider> 组件是您需要添加到应用程序中的主要组件。

它用于为应用程序的其余部分提供上下文。

此上下文包括当前语言以及该语言的相关翻译。

只有在使用任何客户端功能时才需要提供程序。如果您只使用服务器端功能，则不需要提供程序，但仍可以包含它。

重要注意事项

提供程序应该包装您的整个应用程序。
理想情况下，它应该尽可能高地放置在组件树中，例如在您的根布局中。

有关更多信息，请参阅 GTProvider 页面。

`<T>` 组件

<T> 组件是在应用程序中翻译内容的推荐方式。

它是一个 React 组件，可以用来包装任何 JSX 元素，并会自动将元素的内容渲染为支持的语言。

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

与字符串不同，<T> 组件可以用来翻译 HTML 内容，这使得它比字符串翻译更加强大。

示例

<T>
  <div>Hello, world!</div>
</T>

<T>
  <div>
    <h1> Here is an image </h1>
    <img src="https://example.com/image.png" alt="Example" />
  </div>
</T>

<T>
  Formatting can be done easily with the `<T>` component.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency>{1000}</Currency>
</T>

查看组件指南了解使用 <T> 组件的不同方式。

查看 T API 参考了解 <T> 组件的 API。

`useGT` hook

useGT hook 是一个 React hook，可以类似于 <T> 组件使用，但有一些权衡。

该 hook 返回一个可用于翻译字符串的函数。

const translate = useGT();

translate('Hello, world!');

与 <T> 组件相比，useGT hook 在代码库中提供了更多的灵活性。

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

const t = useGT();
const data = {
  title: t('Hello, world!'),
  description: t('This is a description'),
};

查看字符串指南以了解更多关于 useGT hook 的信息。

查看 useGT API 参考获取更多信息。

`useTranslations` hook

useTranslations hook 是一个 React hook，它返回一个函数，该函数可用于检索给定键的翻译。

dictionary.ts

const dictionary = {
  hello: {
    world: 'Hello, world!',
  },
};

App.tsx

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

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

我们不建议在您的应用程序中使用 useTranslations hook。频繁使用 useTranslations hook 会使您的代码库更难维护，并会导致大量技术债务。

相反，我们建议使用 <T> 组件或 useGT hook。

如果您正在从另一个 i18n 库迁移，useTranslations hook 是一个直接替换，可以用于逐步迁移您的代码库。

查看 dictionaries 指南以了解更多关于 useTranslations hook 的信息。

查看 useTranslations API Reference 获取更多信息。

下一步

了解如何使用 SDK 设置您的 Next.js 项目：快速开始
了解如何使用 useGT hook 翻译字符串：翻译字符串
了解如何使用 <T> 组件翻译 JSX 内容：翻译 JSX

概述

在本页面