# @magic-translate/react 中文文档

规范地址：https://npmcn.com/package/%40magic-translate/react/

版本：1\.18\.0
npm 元数据更新时间：2026-11-01T19:03:07.438Z
中文译文更新时间：2026-11-01T19:22:04.332Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40magic-translate/react
原文对照：https://npmcn.com/package/%40magic-translate/react/?lang=original
项目主页：https://magictranslate.io/docs/react
源码仓库：https://github.com/magic-translate/magic-translate

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：990 kB，43 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.22\.1
- 运行依赖：3 个
- peer 依赖：react \>=17，react-dom \>=17
- 首次发布：2022-12-21T19:46:02.093Z
- 最新版本发布：2026-11-01T19:03:07.273Z
- 已发布版本数：25（近 12 个月 5 个）

## 中文简介

用于React的ai驱动i18n。将文本包装进去，它就会自动翻译，不需要翻译键或JSON语言文件。

## 安装

```sh
npm install @magic-translate/react
```

也可以使用：`pnpm add @magic-translate/react`、`yarn add @magic-translate/react`、`bun add @magic-translate/react`

## README

# @magic-translate /反应

[![NPM](https://img.shields.io/npm/v/@magic-translate/react.svg)](https://www.npmjs.com/package/@magic-translate/react) [![npm](https://img.shields.io/npm/dm/@magic-translate/react.svg)](https://www.npmjs.com/package/@magic-translate/react)

React客户端 [神奇的翻译](https://magictranslate.io/)，人工智能驱动的i18n 没有翻译键或语言文件。把你的组件写在一个里面 语言，把文字包起来 `<T>`， Magic Translate可以即时翻译。

```tsx
<button>
  <T>Create chord chart</T>
</button>
```

否 `t('editor.toolbar.create')`,没有 `en.json` / `de.json` 保持同步，并且 添加一种语言是一行。翻译被缓存，并且可以被编辑 把仪表盘交上来。

需要React 17或更新版本。用于使用Next.js或React进行服务器端渲染 服务器组件，使用 [`@magic-translate/react-ssr`](https://www.npmjs.com/package/@magic-translate/react-ssr).

完整的文档: [magictranslate.io / docs /反应](https://magictranslate.io/docs/react)

## 安装

```bash
npm install --save @magic-translate/react
```

或用纱线：

```bash
yarn add @magic-translate/react
```

## 设置

把你的应用包裹起来 `MagicTranslateProvider`． 您可以免费获得API密钥 [magictranslate.io](https://magictranslate.io/).

```tsx
// main.tsx
import { createRoot } from 'react-dom/client';
import { MagicTranslateProvider } from '@magic-translate/react';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <MagicTranslateProvider apiKey="YOUR_API_KEY" language="de">
    <App />
  </MagicTranslateProvider>
);
```

## 使用

### `<T>` 组件

将任何文本（包括纯HTML）包装在 `<T>`． 显示原始内容 直到它的翻译加载完成。

```tsx
import { T } from '@magic-translate/react';

export const Welcome = ({ name }: { name: string }) => (
  <>
    <h1>
      <T>Welcome to our shop</T>
    </h1>
    <p>
      <T>
        Click <a href="/sale">here</a> to see <b>today's</b> deals.
      </T>
    </p>
    <p>
      <T>Hello {name}</T>
    </p>
  </>
);
```

内容一旦发生变化，就会被重新翻译，例如当 `name` 上面示例中的更改。

同时请求的所有翻译都被发送到API 请求和翻译被缓存，因此您可以使用尽可能多的 `<T>` 组件 随你便。

只允许使用文本和纯HTML元素 `<T>`． 反应组件 不是，因为它们无法在翻译中存活； `<T>` 如果找到就抛出 一个。而是在组件内部进行翻译，或者将翻译后的字符串向下传递 作为道具。

### `useTranslate`

使用 `useTranslate` （或其别名） `useT`)用于普通字符串，例如属性， 或者组件不适合的地方：

```tsx
import { useTranslate } from '@magic-translate/react';

export const Search = () => {
  const t = useTranslate();

  return <input placeholder={t('Search products')} />;
};
```

`t` 返回原始文本，直到翻译加载完成 组件一旦完成就会重新渲染。

### 变量

将更改的值（如名称或计数）包装在 `v()`． 周围的文字 它们被翻译成模板， `You have {0} unread messages`, 缓存，无论它显示多少不同的值。价值观本身 永远不会被发送到API。

```tsx
import { T, v } from '@magic-translate/react';

<T>
  Hello {v(user.name)}, you have {v(count)} unread messages
</T>;
```

占位符按顺序编号，翻译可以将它们移动到 语言需要它们的地方。 `v()` 也可以容纳一个React组件，比如 作为链接。

与 `t`，使用带标签的模板。每一个 `${}` Value的处理方式相同：

```tsx
const t = useTranslate();

t`You have ${count} unread messages`;
```

没有 `v()`，一个值被翻译为文本的一部分，因此每个值都不同 价值是一种新的翻译。

### 每个翻译选项

组件和 `t` 可以覆盖目标语言和形式：

```tsx
<T lang="fr" formality="formal">How are you?</T>

<input placeholder={t('Your name', { lang: 'fr', formality: 'formal' })} />
```

### 切换语言

`useLanguageSwitcher` 读取并更改当前语言。每一个 `<T>` 组件和 `t` 呼叫自动更新。

```tsx
import { useLanguageSwitcher } from '@magic-translate/react';

export const LanguageSwitcher = () => {
  const { currentLanguage, setLanguage } = useLanguageSwitcher();

  return (
    <select
      value={currentLanguage}
      onChange={(e) => setLanguage(e.target.value as typeof currentLanguage)}
    >
      <option value="en">English</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  );
};
```

## 配置

`MagicTranslateProvider` 接受:

| 道具 | 描述 |
| --- | --- |
| `apiKey` | 必需的。您的Magic Translate API密钥。 |
| `language` | 必需的。语言内容被翻译成，例如。 `'de'`. |
| `sourceLanguage` | 编写组件所用的语言。默认自动检测；只有在自动检测给出错误结果时才设置它。 |
| `formality` | `'formal'` 或者 `'informal'`． 并非所有语言都支持。每次翻译都可以重写。 |
| `debug` | 将请求记录到控制台。 |

## 其他框架

-   [`@magic-translate/react-ssr`](https://www.npmjs.com/package/@magic-translate/react-ssr)： Next.js应用路由器和React服务器组件
-   [`@magic-translate/vue`](https://www.npmjs.com/package/@magic-translate/vue)： Vue 3和next
-   [`@magic-translate/angular`](https://www.npmjs.com/package/@magic-translate/angular):角
-   [`@magic-translate/js`](https://www.npmjs.com/package/@magic-translate/js)：任何网站，只有一个脚本标签

## 许可证

麻省理工学院© [i42 GmbH是一家](https://i42.ch/)

## 常见问题

### @magic-translate/react 是什么？

用于React的ai驱动i18n。将文本包装进去，它就会自动翻译，不需要翻译键或JSON语言文件。

### 如何安装 @magic-translate/react？

在项目目录运行 npm install @magic-translate/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17）、react-dom（\>=17）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @magic-translate/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @magic-translate/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @magic-translate/react 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.22\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @magic-translate/react 可以商用吗？

@magic-translate/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @magic-translate/react 还在维护吗？

最新版本 1\.18\.0 发布于 2026/11/02（1 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 5 个；首次发布于 2022/12/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。