refine useTranslate Hook 深度解析在自定义组件中接入 i18n 翻译的完整方案【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine在构建多语言后台管理系统时官方组件如按钮、表单的文案翻译往往开箱即用但你自己编写的业务组件——自定义列、弹窗、校验提示——同样需要接入国际化体系。本文围绕 refine 提供的useTranslateHook 展开说明它如何将i18nProvider的翻译方法暴露给任意自定义组件、其参数签名与降级fallback策略并结合核心包源码与示例工程给出从配置i18nProvider到在组件中完成翻译的完整落地路径。一、useTranslate 是什么直接拿到 i18n 库的 translate 方法当你需要在自己的组件中翻译文本时refine 提供了useTranslateHook。它的底层实现就是直接返回i18nProvider中的translate方法因此你可以在自定义组件中继续使用你选用的 i18n 库如 react-i18next自身的翻译特性而不受 refine 内置组件的限制import { useTranslate } from pankod/refine-core; export const MyComponent () { const translate useTranslate(); return button{translate(my.translate.text)}/button; };注意只有当Refine组件配置了i18nProvider时该 Hook 才有实际的翻译能力未配置时它会走源码内置的降级逻辑下文详述。二、参数签名key、options、defaultMessage 三件套阅读 useTranslate 源码实现 可以看到它返回的是一个通过 TypeScript 重载overload声明的双签名函数function translate(key: string, options?: any, defaultMessage?: string): string; function translate(key: string, defaultMessage?: string): string;也就是说存在两种调用形式translate(key)/translate(key, defaultMessage)——第二参数为字符串时被视为默认文案默认消息translate(key, options, defaultMessage)——第二参数为对象时作为插值参数如{ name: test }第三参数才是默认文案。这一“第二参数既是 options 又是 defaultMessage 的歧义”正是源码中类型重载要解决的问题运行时通过typeof options string来区分——当第二参数是字符串且没有传第三参数时字符串本身即作为兜底文案返回。三、降级策略没有 i18nProvider 时返回什么源码中的核心逻辑如下见 packages/core/src/hooks/i18n/useTranslate.ts 第 22-33 行function translate(key: string, options?: string | any, defaultMessage?: string) { return ( i18nProvider?.translate(key, options, defaultMessage) ?? defaultMessage ?? (typeof options string typeof defaultMessage undefined ? options : key) ); }可以将其总结为一条四级兜底链优先调用i18nProvider?.translate(key, options, defaultMessage)的返回值若其返回undefined/null退回defaultMessage若也未提供 defaultMessage且第二参数是字符串即调用的是translate(key, 默认文案)形式则返回该字符串最终兜底返回 key 本身保证页面上至少显示一个可读文本而不报错。另外翻译函数通过useMemo以i18nProvider为依赖缓存i18nProvider不变时不会重复创建函数引用这对依赖函数身份的上游useMemo/useCallback逻辑是一个友好的细节。这套行为有明确的测试用例佐证见 useTranslate.spec.tsx无i18nProvider时translate(undefined key, { name: test }, hello test)渲染出hello test命中第 2 级兜底配置了translate: () merhaba的 provider 时渲染出merhaba当 provider 使用插值参数translate: (key, options) \merhaba ${options.name}时渲染出merhaba test验证了 options 对象被原样透传给 i18n 库。四、useTranslate 从哪里取到 providerI18nContext 注入链路useTranslate并非自己管理翻译状态而是从 refine 的 i18n 上下文中取值const { i18nProvider } useContext(I18nContext);这个 I18nContext 由I18nContextProvider提供其数据最终来源于Refine根组件的i18nProvider属性。在 Refine 组件的 Provider 组合 中可以看到注入层级DataContextProvider dataProvider{dataProvider} LiveContextProvider liveProvider{liveProvider} RouterContextProvider router{routerProvider} ResourceContextProvider resources{resources ?? []} I18nContextProvider i18nProvider{i18nProvider} ...也就是说Refine i18nProvider{...}→I18nContextProvider→I18nContext→useTranslate()任何挂载在Refine内部或该 Context 之下的组件都能拿到同一个翻译方法。五、i18nProvider 的接口契约三个必实现方法i18nProvider的类型定义在 I18nContext 类型文件 中是一个只需实现三个方法的简单对象type TranslateFunction ( key: string, options?: any, defaultMessage?: string, ) string; type ChangeLocaleFunction (locale: string, options?: any) Promiseany | any; type GetLocaleFunction () string; export type I18nProvider { translate: TranslateFunction; changeLocale: ChangeLocaleFunction; getLocale: GetLocaleFunction; };translate被useTranslate直接调用的核心方法签名与上文一致changeLocale切换语言返回Promise或任意值供useSetLocale使用getLocale同步返回当前语言标识供useGetLocale使用。由于useTranslate只做“透传”你在translate里完全可以调用任意 i18n 库。以示例工程 examples/i18n-react/src/App.tsx 为例它用 react-i18next 桥接出 refine 要求的i18nProviderconst { t, i18n } useTranslation(); const i18nProvider { translate: (key: string, params: object) t(key, params), changeLocale: (lang: string) i18n.changeLanguage(lang), getLocale: () i18n.language, }; return ( Refine dataProvider{dataProvider(API_URL)} routerProvider{routerProvider} i18nProvider{i18nProvider} ... 桥接完成后业务组件里就可以直接import { useTranslate } from refinedev/core; export const MyComponent () { const translate useTranslate(); return span{translate(posts.title)}/span; };六、实战用法在自定义列表列中翻译表头在示例工程如 examples/blog-refine-mui/src/pages/categories/list.tsx中可以看到useTranslate的典型落地场景——在 MUI DataGrid 的列定义里翻译表头import { useTranslate } from refinedev/core; export const CategoryList () { const translate useTranslate(); const { dataGridProps } useDataGrid(); const columns React.useMemoGridColDef[]( () [ { headerName: translate(labels.header.title), field: title, flex: 1, }, ], [] ); ... };同样的模式也用于表单页的按钮文案如 categories/create.tsx 中translate(buttons.create)。这里有一个值得注意的细节columns的useMemo依赖数组通常只写了[]如果运行期切换语言列定义不会自动重算——从源码结构看useTranslate返回的函数引用只在i18nProvider变化时才更新因此切换语言后组件需要重新渲染如changeLocale触发的 state 更新翻译结果才会刷新到列头等派生结构中。七、与 useTranslation 的分工什么时候该用 useTranslaterefine 还提供另一个 Hook useTranslation二者容易混淆可以这样区分useTranslation面向refine 内置组件DeleteButton、SelectInput、各 UI 包的按钮/标签等使用的翻译体系返回translate与t等方法翻译 refine 自身的内置词条useTranslate面向你自己的组件与业务词条纯粹透传i18nProvider.translate你的 key 命名空间如my.translate.text、labels.header.title完全由自己掌控。配合 useGetLocale 与 useSetLocale就能在语言切换器中实现“读取当前语言 切换语言 全量刷新翻译”的闭环。八、落地清单与注意事项先配置 provider确认Refine上已传入i18nProvider且其translate方法真正接到了你的 i18n 库参考examples/i18n-react的 react-i18next 桥接写法正确区分调用形式translate(key, 默认文案)与translate(key, { name }, 默认文案)中第二参数含义不同混用会导致插值参数被当作默认文案利用降级链即使 provider 缺失或某 key 未配置useTranslate也会按provider 结果 → defaultMessage → 字符串第二参数 → key的顺序返回可读文本不会抛错该行为有 单元测试 覆盖注意语言切换后的重渲染对useMemo缓存的列定义等派生结构确保切换语言后组件会重新渲染翻译才能同步更新。参考文件Hook 实现packages/core/src/hooks/i18n/useTranslate.ts单元测试packages/core/src/hooks/i18n/useTranslate.spec.tsxProvider 类型定义packages/core/src/contexts/i18n/types.tsContext 注入packages/core/src/contexts/i18n/index.tsx、packages/core/src/components/containers/refine/index.tsx完整示例工程examples/i18n-react/src/App.tsx实战用法示例examples/blog-refine-mui/src/pages/categories/list.tsx【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考