js-lingui Metro Transformer 深度指南：在 React Native 与 Expo 中直接编译 .po 目录文件-北京尧图网络

开发工具前端【免费下载链接】js-lingui A readable, automated, and optimized (2 kb) internationalization for JavaScript项目地址https://gitcode.com/gh_mirrors/js/js-lingui点击查看免费下载本篇指南围绕 Lingui 的lingui/metro-transformer包展开它让基于 Metro 打包器的 React Native / Expo 应用能够跳过lingui compile这一步在打包时由 transformer 将.po目录文件catalog即时编译为 JS 模块。读完本文你将掌握完整的安装与metro.config.js配置方法、TypeScript 类型声明的写法、运行时直接import/require.po文件的用法并理解 transformer 在 Metro 管线中的调用链、缓存策略与错误处理机制。背景从两步流程到一步流程在lingui/metro-transformer出现之前React Native 开发者使用 Lingui 需要遵循一个两步流程用lingui extract从源码中提取译文消息到.po文件用lingui compile把翻译好的.po文件编译为 JS/TS 文件供运行时import使用。而lingui/metro-transformer消除了第二步——编译在 Metro 打包时自动完成。该包自 Lingui v4.12.0 起可用当前仓库版本已迭代到 6.x见 packages/metro-transformer/package.json适用于所有受 React Native 支持的平台Android、iOS、Web 等唯一前提是应用使用 Metro 打包器。仓库中的 React Native 示例应用完整演示了该 transformer 的用法可以直接参考。安装与环境要求lingui/metro-transformer作为开发依赖安装npm install --save-dev lingui/metro-transformer适用前提以仓库当前声明为准仅支持 Expo SDK 50 和 React Native v0.73.0 及以上版本仅支持基于po/pot文件的目录catalog不支持 JSON/CSV 等其他格式从 package.json 的peerDependencies可以看到expo/metro-config与react-native/metro-babel-transformer均为可选 peer 依赖按项目类型二选一即可。配置 metro.config.jstransformer 通过 Metro 的babelTransformerPath配置项注入同时需要把po、pot加入sourceExts。根据项目类型有两种写法Expo 项目// Learn more https://docs.expo.io/guides/customizing-metro const { getDefaultConfig } require(expo/metro-config); const config getDefaultConfig(__dirname); const { transformer, resolver } config; config.transformer { ...transformer, babelTransformerPath: require.resolve(lingui/metro-transformer/expo), }; config.resolver { ...resolver, sourceExts: [...resolver.sourceExts, po, pot], }; module.exports config;这与示例应用 examples/react-native/metro.config.js 的配置完全一致。原生 React Native 项目const { getDefaultConfig, mergeConfig } require(react-native/metro-config); const defaultConfig getDefaultConfig(__dirname); const { sourceExts } defaultConfig.resolver; /** * type {import(metro-config).MetroConfig} */ const config { transformer: { babelTransformerPath: require.resolve(lingui/metro-transformer/react-native), }, resolver: { sourceExts: [...sourceExts, po, pot], }, }; module.exports mergeConfig(defaultConfig, config);两个入口文件的区别在源码中一目了然src/expo/index.ts 以 Expo 的expo/metro-config/babel-transformer作为上游 transformersrc/react-native/index.ts 以react-native/metro-babel-transformer作为上游 transformer。两者都只是调用同一个工厂函数createLinguiMetroTransformer(upstreamTransformer)把它包成自己的transform导出。用法直接 import .po 文件配置完成后核心用法就是让业务代码直接引入.po文件-import { messages } from ./src/locales/en/messages.ts; import { messages } from ./src/locales/en/messages.po;示例应用中 App.tsx 的初始化代码正是这种写法import { messages } from ./src/locales/en/messages.po; i18n.loadAndActivate({ locale: en, messages });此外运行时按需切换语言时也可以require.po文件。示例应用 MainScreen.tsx 的loadAndActivateLocale方法就是这样实现的const catalog newActiveLanguage en ? require(./locales/en/messages.po) : require(./locales/cs/messages.po); i18n.load(newActiveLanguage, catalog.messages); i18n.activate(newActiveLanguage);目录路径由 Lingui 配置决定。示例应用的 lingui.config.js 声明了catalogs.path为src/locales/{locale}/messages因此src/locales/en/messages.po与src/locales/cs/messages.po恰好是 transformer 能匹配到的目录文件。TypeScript 类型声明如果项目使用 TypeScript需要为.po扩展名添加模块声明否则 TS 不认识该文件类型declare module *.po { import type { Messages } from lingui/core; export const messages: Messages; }示例应用中的 po-types.d.ts 即为这段声明本身。缓存注意事项首次配置后用expo start -c或yarn start --reset-cache重启 Metro 以清空 transformer 缓存每次修改 Lingui 配置文件后都必须重启 Metro bundler——这一点在源码中有直接依据下文缓存策略部分。源码解析transformer 的工作机制理解 metroTransformer.ts 的实现能帮你快速定位实际项目中的问题。只拦截 .po 文件其余透传工厂函数返回的transform是装饰器模式export const createLinguiMetroTransformer ( upstreamTransformer: BabelTransformer, ): BabelTransformer[transform] { return async function linguiMetroTransformer(params) { if (!params.filename.endsWith(.po)) { return upstreamTransformer.transform(params) } const jsSource await transformFile(params) return upstreamTransformer.transform({ ...params, src: jsSource, }) } }对非.po文件直接交给上游 transformer即 Expo / React Native 官方 Babel transformer处理行为与未安装 Lingui 时完全一致对.po文件先转换成一段 JS 源码再让上游 transformer 做常规的 Babel 编译。BabelTransformerArgs的最小类型定义见 types.ts包含filename、src、options、plugins四个字段。目录匹配与错误提示transformFile的核心流程通过getConfig()来自lingui/conf读取 Lingui 配置调用getCatalogs(config)来自lingui/cli/api列出所有目录用getCatalogForFile把请求文件的路径先转为相对 Lingui 配置根目录的路径匹配到某个目录调用catalog.getTranslations(locale, { fallbackLocales, sourceLocale })取出消息其中回退逻辑直接复用lingui compile的同一套配置项用createCompiledCatalog生成编译产物。如果请求的.po文件不属于任何已声明目录transformer 会抛出包含详细上下文的错误列出所有已配置的目录路径与当前工作目录并提示请检查catalogs.path配置并重启 Metro 服务器。测试用例 metroTransformer.test.ts 中的should throw an error when provided path is invalid验证了这条错误路径断言拒绝信息匹配/is not matched to any of your catalogs paths/。缓存策略为什么改配置必须重启 Metro源码中有一个刻意的激进的缓存// We are aggressive at caching the set of all catalogs (but not their contents) because // the set of processed po files doesnt change unless Lingui config changes, and we dont need to call getCatalogs() on every request. const memoizedGetCatalogList memoizeOne(getCatalogList)即所有目录的集合而非内容被memoize-one缓存。目录集合只有在 Lingui 配置变化时才会变化而 Metro 服务进程内的 transformer 模块缓存感知不到配置文件改动——这正是官方文档反复强调修改 Lingui 配置后必须重启 Metro的原因。编译产物与运行环境差异createCompiledCatalog调用时有几个值得注意的参数const strict process.env.NODE_ENV ! production const { source } createCompiledCatalog(locale, messages, { strict, namespace: es, pseudoLocale: pseudoLocaleConfig?.locale, pseudoLocaleOptions: pseudoLocaleConfig?.options, })strict在非生产环境开启与lingui compile的行为一致支持 Lingui 的伪本地化pseudo-localization配置按 locale 从config.pseudoLocale中查找命名空间固定为 ES 模块导出。测试用例中的内联快照展示了实际产物形态.po文件最终被转换为/*eslint-disable*/export const messagesJSON.parse({\dEgA5A\:[\Cancel\],\p1AaTM\:[\Add a message to your inbox\]});即一个内嵌 JSON 字符串的messages具名导出——这也解释了为什么类型声明中messages的类型是Messages。同文件还验证了捷克语目录在en源语言回退下的编译结果以及绝对路径输入会被正确转为相对 Lingui 配置根目录的路径这一实现细节。与 React Server Components 的关系博客原文还提到Lingui 现已提供对 React 的真正通用支持——同一套消息语法可在 Web 端 React、React Native 以及 React Server ComponentsRSC中使用。对于 RSC 场景lingui/metro-transformer并非必需但仓库中 TransRsc.tsx 与 index-rsc.ts 的存在印证了这一跨环境支持是产品化能力而非口号。小结与排查清单场景处理方式找不到目录匹配报错 is not matched to any of your catalogs paths检查lingui.config中catalogs.path是否正确覆盖该.po文件然后重启 Metro修改了 Lingui 配置后行为未变化重启 Metro目录集合被memoize-one激进缓存TS 报.po模块不存在添加declare module *.po声明文件Expo / 原生 RN 报错确认babelTransformerPath分别指向lingui/metro-transformer/expo或/react-native入口需要再次强调的限制该 transformer 只支持po/pot格式的目录最低支持 Expo SDK 50 与 React Native v0.73.0。相关参考资料metro-transformer 包 README、测试用例与完整示例 examples/react-native。赞分享开发工具前端【免费下载链接】js-lingui A readable, automated, and optimized (2 kb) internationalization for JavaScript项目地址https://gitcode.com/gh_mirrors/js/js-lingui点击查看免费下载相关推荐js-lingui lingui/metro-transformer让 React Native 与 Expo 应用直接 import .po 文件Metro 即时编译消息目录js lingui lingui/metro transformer让 React Native 与 Expo 应用直接 import .po 文件Met开发工具前端Lingui lingui/loader 实战在 Webpack、Rspack 与 Rsbuild 中即时编译 .po 目录Lingui lingui/loader 实战在 Webpack、Rspack 与 Rsbuild 中即时编译 .po 目录 lingui/loader开发工具前端js-lingui lingui/format-po默认 PO 目录格式的深度解析与 PO 格式化器实现js lingui lingui/format po默认 PO 目录格式的深度解析与 PO 格式化器实现本文以 packages/format po/RE开发工具前端上一篇解码prism4cj核心标记化算法greedy贪婪匹配与lookbehind如何实现精准代码标记下一篇存档文件与多周目进度管理REPENTOGON SaveSyncing 同步机制深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

js-lingui Metro Transformer 深度指南：在 React Native 与 Expo 中直接编译 .po 目录文件

相关推荐

板级适配 · SystemInit：给芯片上电后的“自检程序“动手

HackRF One手册解析：硬件、编译与GNURadio实战

Graffle 实战：使用 `___on_` 内联片段查询 GraphQL Interface 类型并获得可收窄的判别联合类型

更多资讯

磁盘未分配数据恢复，分区消失文件这样找回

GEO信任机制：企业内容如何通过大模型权威审核

传统SEO退场后，企业数字资产的GEO价值分化

第五篇：Keepalived + LVS 四层负载均衡高可用实战：DR 模式全流程

第六篇：Keepalived 脑裂专题：成因、危害与防脑裂实战（含检测脚本）

CentOS下源码编译安装高版本Python：依赖准备与环境配置全指南

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？