# gt-next: General Translation Next.js SDK: useTranslations
URL: https://generaltranslation.com/zh/docs/next/api/dictionary/use-translations.mdx
---
title: useTranslations
description: useTranslations Hook 的 API 参考
---

## 概述

`useTranslations` 用于从[翻译字典](/docs/next/guides/dictionaries)中获取字符串翻译。

它必须在由 [`<GTProvider>`](/docs/next/api/components/gtprovider) 包裹的组件内使用。

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

对于异步组件，请参阅 [`getTranslations`](/docs/next/api/dictionary/get-translations)。

<Callout>
  `getTranslations` 和 `useTranslations` 使用[字典](/docs/next/guides/dictionaries)来存储所有需要翻译的内容。
  这与使用 [`<T>` 组件](/docs/next/guides/t)进行翻译不同。
  如果你只打算使用 `<T>` 组件进行翻译，那么本文档不适用。
</Callout>


## 参考文档

### 参数

<TypeTable
  type={{
  "id?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
}}
/>

### 说明

| 属性   | 说明                             |
| ---- | ------------------------------ |
| `id` | 可选前缀，会加在所有翻译键之前。这在处理嵌套字典值时很有用。 |

### 返回值

一个翻译函数 `d`，给定 id 后，会返回对应条目的翻译结果

```jsx
(id: string, options?: DictionaryTranslationOptions) => string
```

| 名称         | 类型                                                                                    | 描述                 |
| ---------- | ------------------------------------------------------------------------------------- | ------------------ |
| `id`       | `string`                                                                              | 要翻译的条目的 id         |
| `options?` | [`DictionaryTranslationOptions`](/docs/next/api/types/dictionary-translation-options) | 用于自定义 `d` 行为的翻译选项。 |

***

## 示例

### 基本字典用法

字典中的每个条目都会被翻译。

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

当我们需要在客户端访问这些条目时，就调用 `useTranslations`。
它会返回一个函数，用于接收字典中某个翻译的键。

```jsx title="TranslateGreeting.jsx" copy
import { useTranslations } from 'gt-next';

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


### 使用变量 [#variables]

要传递值，你必须 (1) 指定一个标识符，以及 (2) 在调用 `d` 函数时引用该标识符。

在这个示例中，我们使用 `{}` 将变量传递给翻译内容。
在字典中，我们将标识符设为 `{userName}`。

```jsx title="dictionary.jsx" copy
// [!code word:userName]
const dictionary = {
  greeting: "Hello, {userName}!", // [!code highlight]
};
export default dictionary;
```

```jsx title="src/server/TranslateGreeting.jsx" copy
// [!code word:userName]
import { useTranslations } from 'gt-next';

export default async function TranslateGreeting() {
  const t = useTranslations();
  
  // 你好，Alice！
  const greetingAlice = t('greeting', { userName: "Alice" }); // [!code highlight]

  return (
    <p>
      {greetingAlice}
    </p>
  );
}
```


### 使用前缀

我们可以使用前缀，只翻译字典中的部分内容。

```jsx title="dictionary.jsx" copy
const dictionary = {
  prefix1: { // [!code highlight]
    prefix2: { // [!code highlight]
      greeting: "Hello, Bob",
    }
  }
};
export default dictionary;
```

由于我们在 `useTranslations` hook 中传入了值 `'prefix1.prefix2'`，所有键都会自动加上 `prefix1.prefix2` 前缀：

```jsx title="UserDetails.jsx" copy
import { useTranslations } from 'gt-next';

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

***


## 注意事项

* `useTranslations` 函数可让你在客户端访问字典翻译。
* `useTranslations` Hook 只能在由 [`<GTProvider>` 组件](/docs/next/api/components/gtprovider) 包裹的组件内使用。

## 后续步骤

* 关于服务端翻译，请参阅 [`getTranslations`](/docs/next/api/dictionary/get-translations)。
* 请参阅[字典参考](/docs/next/guides/dictionaries)，进一步了解如何使用字典。