# General Translation React SDKs (gt-react, gt-next): useTranslations
URL: https://generaltranslation.com/zh/docs/react/reference/hooks/use-translations.mdx
---

title: useTranslations
description: 使用 General Translation gt-react 通过 id 从字典中查找字符串翻译。useTranslations 的 API 参考。

---

`useTranslations` 钩子通过 id 从[翻译字典](/docs/react/guides/translating-with-dictionaries)中查找字符串翻译。它是 [`<T>`](/docs/react/reference/components/t) 组件和 [`useGT`](/docs/react/reference/hooks/use-gt) 的字典替代方案。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。示例从 `gt-react` 导入；请改为从你所用框架对应的包中导入。*

## 概览 [#overview]

调用 `useTranslations` 获取查找函数，然后传入条目的 id。

```tsx
const t = useTranslations(); // 获取翻译函数
t('greeting.hello'); // 传入 id 获取翻译
```

*注意：在 `gt-react` 中，请在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 内调用 `useTranslations`，并为 provider 或初始化调用传入 dictionary。在 `gt-next` 中，它也可用于同步 Server components。如果你只使用 `<T>`，则无需使用它。*

## 工作方式 [#how-it-works]

* **基于 id 的查找。** 返回的函数会根据 id 在当前区域设置中解析对应的字典条目。变量会被插值，但不会被翻译。
* **根 id 前缀。** 传入 `rootId` 后，每次查找都会自动加上此前缀，便于在嵌套字典部分中使用。
* **嵌套对象。** 返回的函数带有 `.obj(id)` 方法，用于读取嵌套的字典对象，而不是单个字符串。
* **缺失的 id 会抛出错误。** 查找字典中不存在的 id 时，会抛出错误。

## 参数 [#parameters]

| 参数                   | 描述                   | 类型       | 可选 | 默认值 |
| -------------------- | -------------------- | -------- | -- | --- |
| [`rootId`](#root-id) | 应用于每个 lookup id 的前缀。 | `string` | 是  | —   |

### `rootId` [#root-id]

**类型** `string` · **可选**

一个可选前缀，会添加到所有 lookup id 前面，便于处理字典中的嵌套子集。

## 返回值 [#returns]

**类型** `(id: string, options?: DictionaryTranslationOptions) => string`

一个函数，返回给定 id 对应的翻译条目。它还提供 `.obj(id)` 方法，用于读取嵌套对象。

| 名称        | 描述         | 类型                                                                                           | 可选 |
| --------- | ---------- | -------------------------------------------------------------------------------------------- | -- |
| `id`      | 要解析的条目 id。 | `string`                                                                                     | 否  |
| `options` | 该条目的插值变量。  | [`DictionaryTranslationOptions`](/docs/react/reference/types/dictionary-translation-options) | 是  |

## 示例 [#examples]

```tsx title="dictionary.ts"
const dictionary = {
  greeting: 'Hello, Bob', // [!code highlight]
};
export default dictionary;
```

```tsx title="TranslateGreeting.tsx"
import { useTranslations } from 'gt-react';

export default function TranslateGreeting() {
  const t = useTranslations(); // [!code highlight]
  return <p>{t('greeting')}</p>; // [!code highlight]
}
```

```tsx title="dictionary.ts"
const dictionary = {
  greeting: 'Hello, {userName}!', // [!code highlight]
};
export default dictionary;
```

```tsx title="TranslateGreeting.tsx"
import { useTranslations } from 'gt-react';

export default function TranslateGreeting() {
  const t = useTranslations();
  const greetingAlice = t('greeting', { userName: 'Alice' }); // [!code highlight]
  return <p>{greetingAlice}</p>; // "Hello, Alice!"
}
```

```tsx title="UserDetails.tsx"
import { useTranslations } from 'gt-react';

// 字典：{ prefix1: { prefix2: { greeting: 'Hello, Bob' } } }
export default function UserDetails() {
  const t = useTranslations('prefix1.prefix2'); // [!code highlight]
  return <p>{t('greeting')}</p>; // 解析为 prefix1.prefix2.greeting
}
```

## 注意事项 [#notes]

* `useTranslations` 按 id 访问字典中的译文。
* 在异步 App Router 组件中，请改用 [`getTranslations`](/docs/react/nextjs/reference/functions/get-translations)。
* 在 `gt-react` 中，必须在提供可用字典的 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 内使用它。
* 有关设置和约定，请参阅[字典指南](/docs/react/guides/translating-with-dictionaries)。