LinguiJS t 宏在 React 组件中不生效的解决方案与最佳实践

在 LinguiJS 中，t 宏在 React 组件中直接使用作为属性时可能无法正确翻译。这是因为 t 宏返回的是一个消息描述符（MessageDescriptor），而非立即翻译的字符串。要实现动态翻译，需要利用 useLingui 钩子获取 i18n 实例，并通过 i18n._() 方法将消息描述符进行翻译。本文将详细介绍这一机制并提供正确的实现方案。

理解 LinguiJS 的翻译机制

linguijs 提供了多种方式来处理国际化消息，主要包括 <trans> 组件和 t / msg 宏。它们在编译时都会将文本提取到翻译目录中，但在运行时处理方式有所不同：

1. <Trans> 组件: 这是一个 React 组件，它会自动订阅 LinguiJS 的国际化上下文，并在渲染时获取当前语言环境下的翻译字符串。因此，p><Trans>hello world</Trans></p> 能够正常工作。
2. t / msg 宏: 这些宏在编译时用于标记和提取可翻译文本。在运行时，t 或 msg 宏不会立即返回翻译后的字符串，而是返回一个 MessageDescriptor 对象。这个对象包含了原始消息、ID、上下文等信息，它是一个“翻译指令”，而不是最终的翻译结果。要获得实际的翻译字符串，必须将这个 MessageDescriptor 传递给 LinguiJS 的 i18n 实例的 _() 方法。

当我们在 React 组件中将 t 宏的返回值直接作为属性（例如 data={thello react}）传递时，如果接收组件没有显式地获取 i18n 上下文并调用 _() 方法，那么它将无法正确地显示翻译后的内容，因为它接收到的是一个 MessageDescriptor 对象，而不是一个字符串。

解决方案：结合 useLingui 钩子和 i18n._() 方法

为了在 React 函数组件中正确地使用 t 或 msg 宏返回的 MessageDescriptor 进行翻译，我们需要遵循以下步骤：

1. 在定义消息时使用 msg 宏: msg 宏与 t 宏功能类似，但它更明确地表示“定义一个消息描述符以供稍后使用”，这有助于代码意图的清晰表达。
2. 在需要翻译的组件中引入 useLingui 钩子: useLingui 钩子允许 React 函数组件订阅 LinguiJS 的国际化上下文，从而获取到当前的 i18n 实例。
3. 使用 i18n._() 方法进行翻译: 获得 i18n 实例后，将其 _() 方法与 MessageDescriptor 结合，即可获取翻译后的字符串。

下面是根据问题描述和解决方案修改后的代码示例：

index.tsx (或包含消息定义的父组件)

在此处，我们将 t 宏替换为 msg 宏，以明确我们正在定义一个消息描述符，而不是期望立即得到翻译字符串。这个描述符将被传递给 DataComponent。

import React from "react";
import ReactDOM from "react-dom/client";
import reportWebVitals from "./reportWebVitals";
import { StoreProvider } from "./components/store-provider";
import createStore from "./store";
import { LanguageProvider } from "./components/language-provider";
import { LangSwitcher } from "./components/lang-switcher";
import { DataComponent } from "./components/DataComponent";
import { Trans, msg } from "@lingui/macro"; // 导入 msg 宏
const store = createStore();
const root = ReactDOM.createRoot(
document.getElementById("root") as HTMLElement
);
root.render(
<React.StrictMode>
<StoreProvider store={store}>
<LanguageProvider>
<LangSwitcher />
<p>
<Trans>hello world</Trans>
</p>
{/* 使用 msg 宏定义消息，并将其作为 MessageDescriptor 传递 */}
<DataComponent data={msg`hello react`} />
</LanguageProvider>
</StoreProvider>
</React.StrictMode>
);
reportWebVitals();

DataComponent.tsx (接收并翻译消息的子组件)

在 DataComponent 中，我们使用 useLingui 钩子获取 i18n 实例，然后调用 i18n._() 方法来翻译传入的 MessageDescriptor。

import { MessageDescriptor } from "@lingui/core"; // 导入 MessageDescriptor 类型
import { useLingui } from "@lingui/react"; // 导入 useLingui 钩子
type props = {
data: MessageDescriptor; // 明确指定 data 属性的类型为 MessageDescriptor
};
export const DataComponent: React.FC<props> = ({ data }) => {
const { i18n } = useLingui(); // 使用 useLingui 钩子获取 i18n 实例
return <p>{i18n._(data)}</p>; // 使用 i18n._() 方法翻译 MessageDescriptor
};

关键点与注意事项

• MessageDescriptor 类型: 确保你的组件属性类型正确地声明为 MessageDescriptor，这有助于 TypeScript 在开发阶段捕获潜在的类型错误。
• 上下文提供: 确保你的 React 应用被 LanguageProvider (或 I18nProvider) 包裹，这样 useLingui 才能正确获取到 i18n 实例。从提供的 index.tsx 文件来看，LanguageProvider 已经存在。
• 编译与提取: 别忘了运行 lingui extract 和 lingui compile 命令来提取和编译翻译消息。你的 package.json 中已经定义了相应的脚本：

  "extract": "lingui extract --clean",
  "compile": "lingui compile --strict"

• 何时使用 <Trans> vs t/msg + useLingui:
  • 当需要直接在 JSX 中渲染可翻译文本且不需要复杂逻辑时，<Trans> 组件通常是更简洁的选择。
  • 当需要将可翻译文本作为变量、函数参数传递，或者在非 React 组件（如 Redux reducer、saga）中使用翻译时，t 或 msg 宏配合 i18n._() 方法是必需的。在 React 组件中，如果消息需要经过某些处理或作为属性传递，再由子组件翻译，那么 msg + useLingui 是正确的模式。

总结

LinguiJS 的 t 宏和 msg 宏在 React 应用中用于定义可翻译消息，它们在运行时返回 MessageDescriptor 对象。为了在 React 组件中将这些描述符转换为实际的翻译字符串，必须利用 useLingui 钩子获取 i18n 实例，并调用其 _() 方法。理解这一核心机制是正确使用 LinguiJS 进行 React 应用国际化的关键。通过遵循上述最佳实践，您可以确保应用程序中的所有可翻译内容都能得到正确的处理和显示。