概述

介绍

General Translation React SDK 是一个开源的 React 国际化（i18n）库。

它提供了一套工具，以简单且可维护的方式帮助您国际化您的 React 应用程序，功能与其他流行的 i18n 库相当。

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

然而，它还与我们的平台集成，提供额外的功能，例如：

开发环境中的翻译热重载
自动 AI 翻译
与 General Translation 平台同步翻译
与我们的翻译 CDN 原生集成

概念

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

<GTProvider> 组件

<T> 组件

useGT hook

（可选）useTranslations hook

`<GTProvider>` 组件

import { GTProvider } from 'gt-react';

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

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

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

重要注意事项

该 provider 应该包裹你的整个应用程序。
理想情况下，它应尽可能放在树的顶层，比如你的根组件中。

查看更多信息，请参阅 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>

请参阅翻译 JSX 指南，了解如何以不同方式使用 <T> 组件。

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

`useGT` 钩子

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

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

const translate = useGT();

translate('Hello, world!');

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

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

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

请参阅 strings 指南，了解更多关于 useGT 钩子的内容。

更多信息请参见 useGT API Reference。

`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。频繁使用该 hook 会使您的代码库更难维护，并会导致大量技术债务。

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

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

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

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

下一步

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

概述

在本页面