# gt-react: General Translation React SDK: 概览
URL: https://generaltranslation.com/zh/docs/react/introduction.mdx
---
title: 概览
description: General Translation React SDK 概览
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 中的模板。 */}


## 简介

General Translation React SDK 是一个面向 React 应用的开源国际化 (i18n) 库。

它提供了一整套全面的工具，帮助你以简单且易于维护的方式为 React 应用实现国际化，并在功能上与其他流行的 i18n 库保持一致。

该 SDK 可作为独立方案使用，无需依赖 General Translation 平台，其行为方式也与其他 i18n 库类似。

不过，它也可以与我们的平台集成，以获得更多增强功能：

* 开发时支持翻译热重载
* 自动 AI 翻译
* 与 General Translation 平台同步翻译
* 原生集成我们的翻译 CDN

## 概念

SDK 有 5 个需要理解的核心概念。

<Steps>
  <Step>
    [`<GTProvider>`](/docs/react/api/components/gtprovider) 组件
  </Step>

  <Step>
    [`<T>`](/docs/react/api/components/t) 组件
  </Step>

  <Step>
    [`useGT`](/docs/react/api/strings/use-gt) 钩子
  </Step>

  <Step>
    用于共享字符串的 [`msg`](/docs/react/api/strings/msg) 函数
  </Step>

  <Step>
     (可选) [`useTranslations`](/docs/react/api/dictionary/use-translations) 钩子
  </Step>
</Steps>

## `<GTProvider>` 组件

[`<GTProvider>`](/docs/react/api/components/gtprovider) 组件为你的应用提供翻译上下文，包括当前语言和对应的译文。

```tsx
import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* 您的应用内容 */}
      </div>
    </GTProvider>
  );
}
```

**重要：** 该 provider 应包裹整个应用，并尽量放在组件树中尽可能靠上的位置，例如根 App 组件中。

更多信息请参阅 [`GTProvider`](/docs/react/api/components/gtprovider) API 参考。


## `<T>` 组件

[`<T>`](/docs/react/api/components/t) 组件是在应用中翻译内容的推荐方式。

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

<Callout type="info">
  我们建议尽可能使用 [`<T>`](/docs/react/api/components/t) 组件，因为它能为翻译提供最大的灵活性。

  与字符串不同，[`<T>`](/docs/react/api/components/t) 组件还可用于翻译 HTML 内容，因此比字符串翻译强大得多。
</Callout>

### 示例

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

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

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

[`<T>`](/docs/react/api/components/t) 组件可与 [`<Num>`](/docs/react/api/components/num)、[`<DateTime>`](/docs/react/api/components/datetime) 和 [`<Currency>`](/docs/react/api/components/currency) 等[变量组件](/docs/react/guides/variables)配合使用，用于格式化动态内容。

请参阅 [`<T>` 组件指南](/docs/react/guides/t)，了解 [`<T>`](/docs/react/api/components/t) 组件的不同用法。


## `useGT` 钩子

[`useGT`](/docs/react/api/strings/use-gt) 钩子 是一个 React 钩子，用法与 [`<T>`](/docs/react/api/components/t) 组件类似，但也有一些取舍。

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

```tsx
const gt = useGT();

gt('Hello, world!');
```

与 [`<T>`](/docs/react/api/components/t) 组件相比，[`useGT`](/docs/react/api/strings/use-gt) 钩子 能让你的代码库更灵活。

例如，如果你有一个包含嵌套字符串的复杂数据结构，使用 [`<T>`](/docs/react/api/components/t) 组件就会更困难。

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

参阅[字符串](/docs/react/guides/strings)指南，进一步了解[`useGT`](/docs/react/api/strings/use-gt) 钩子。


## `msg` 函数

[`msg`](/docs/react/api/strings/msg) 函数用于标记需要翻译、且会在多个组件之间复用或存储在配置对象中的字符串。

这对于导航标签、表单消息等共享内容尤其有用，也适用于应用中会在多个位置重复出现的任何文本。

```tsx
// 标记字符串以供翻译
import { msg } from 'gt-react';

const navItems = [
  { label: msg('Home'), href: '/' },
  { label: msg('About'), href: '/about' },
  { label: msg('Contact'), href: '/contact' }
];
```

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

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

[`msg`](/docs/react/api/strings/msg) 函数会用翻译元数据对字符串进行编码，而 [`useMessages`](/docs/react/api/strings/use-messages) 则负责将其解码。

<Callout type="info">
  对于需要在整个应用中保持翻译一致的共享内容，请使用 [`msg`](/docs/react/api/strings/msg)。对于组件专用的内容，建议优先使用 [`<T>`](/docs/react/api/components/t) 或 [`useGT`](/docs/react/api/strings/use-gt)。
</Callout>

请参阅[共享字符串](/docs/react/guides/shared-strings)指南，进一步了解 `msg` 函数。


## `useTranslations` 钩子

[`useTranslations`](/docs/react/api/dictionary/use-translations) 是一个 React 钩子，会返回一个函数，用于获取给定键对应的翻译。

```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/)。

<Callout type="warn">
  我们不建议在应用中使用 [`useTranslations`](/docs/react/api/dictionary/use-translations) 钩子。频繁使用 [`useTranslations`](/docs/react/api/dictionary/use-translations) 钩子 会让你的代码库更难维护，
  并带来大量技术债务。

  我们建议改用 [`<T>`](/docs/react/api/components/t) 组件或 [`useGT`](/docs/react/api/strings/use-gt) 钩子。

  如果你正从其他 i18n 库迁移，[`useTranslations`](/docs/react/api/dictionary/use-translations) 钩子 是一个可直接替换的方案，也适合对代码库进行渐进式迁移。
</Callout>

请参阅 [dictionaries](/docs/react/guides/dictionaries) 指南，详细了解 [`useTranslations`](/docs/react/api/dictionary/use-translations) 钩子。

更多信息请参阅 [useTranslations API 参考](/docs/react/api/dictionary/use-translations)。

***


## 后续步骤

* 了解如何使用 SDK 设置 React 项目：[快速开始](/docs/react)
* 了解如何使用 [`<T>`](/docs/react/api/components/t) 组件翻译 JSX 内容：[JSX 翻译指南](/docs/react/guides/t)
* 了解如何使用 [`useGT`](/docs/react/api/strings/use-gt) 钩子翻译字符串：[字符串翻译指南](/docs/react/guides/strings)
* 了解如何使用 [`msg`](/docs/react/api/strings/msg) 函数处理共享字符串：[共享字符串指南](/docs/react/guides/shared-strings)