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

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


## 简介

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

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

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

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

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

## 概念

关于 SDK，有 5 个需要了解的核心概念。

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

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

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

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

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

## `<GTProvider>` 组件

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

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

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

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

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


## `<T>` 组件

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

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

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

  与字符串不同，[`<T>`](/docs/react-native/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-native/api/components/t) 组件可与 [`<Num>`](/docs/react-native/api/components/num)、[`<DateTime>`](/docs/react-native/api/components/datetime) 和 [`<Currency>`](/docs/react-native/api/components/currency) 等[变量组件](/docs/react-native/guides/variables)配合使用，用于动态内容格式化。

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


## `useGT` 钩子

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

该 钩子会返回一个可用于翻译文本的函数。

```tsx
const gt = useGT();

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

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

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

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

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


## `msg` 函数

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

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

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

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

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

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-native/api/strings/msg) 函数会将字符串编码为附带翻译元数据的内容，而 [`useMessages`](/docs/react-native/api/strings/use-messages) 则负责将其解码。

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

要了解更多信息，请参阅 [共享字符串](/docs/react-native/guides/shared-strings) 指南中的 `msg` 函数说明。


## `useTranslations` 钩子

[`useTranslations`](/docs/react-native/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-native/api/dictionary/use-translations) 钩子。频繁使用 [`useTranslations`](/docs/react-native/api/dictionary/use-translations) 钩子会使代码库更难维护，
  并带来大量技术债务。

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

  如果你正从其他 i18n 库迁移，[`useTranslations`](/docs/react-native/api/dictionary/use-translations) 钩子是一个可直接替换的方案，可用于逐步迁移代码库。
</Callout>

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

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

***


## 后续步骤

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