摘要

针对前端微前端、多 Portal、多应用场景下翻译方案混乱、框架不统一、开发体验不一致、资源维护成本高的核心痛点，本文提出「短中长期结合」的翻译统一方案。通过封装通用翻译 SDK、抹平多框架差异、统一开发规范与资源加载策略，实现开发无感接入、Portal 高效管理、性能最优的国际化能力，可直接用于企业级多应用体系落地。

一、落地任务概览

围绕前端翻译统一方案，明确各模块核心职责与推进方向，便于落地跟踪与协同：

模块分类	功能名称	功能描述
翻译 SDK	init	规范 SDK 初始化流程
	generateFunction	生成并获取 $gt 翻译实例
	showKey	展示翻译 key，辅助问题定位
	changeLanguage	统一语言切换、持久化与事件通知
	i18n 框架集成	暂不支持热更新，降低实现复杂度
	Vue / React 解耦	支持插件化配置，适配多框架
	性能优化	非阻塞加载，优化移动端多实例性能
	fetch	统一拉取翻译资源，支持缓存、异步与动态更新
文档	翻译工具指南	输出项目接入与 $gt 使用规范
Lint	翻译 Lint	校验 $gt 语法，约束开发规范
Dev Tool	上传 key 工具	CI/CD 自动化上传翻译 key
样板间	样板间落地	统一样板间代码，接入 Lint 并优化旧逻辑
脚手架	脚手架接入	集成至脚手架，实现新项目快速接入
配置化	配置中心	远程管理翻译配置，支持动态扩展

二、方案概览与目标

2.1 方案概览

本方案聚焦前端多 Portal、多应用、多框架场景的翻译痛点，通过「标准化 SDK + 统一配置 + 性能优化」实现翻译能力横向对齐、差异收敛，核心结论如下：

• 跨 Portal 子应用：新增独立 Resource，容器层抹平 $gt 差异，开发无感知；AI 翻译跟随 Portal 配置，人工翻译由主 Portal PM 负责。
• 主 Portal 兼容：仓储系统未用标准方案，其子应用需上传冗余 key 至同一 Resource；物流系统区分内外子应用，内部共用一个 Resource、外部独立另一个。
• 语言切换：优先采用「刷新页面」方案，暂不支持热更新，降低实现复杂度与落地风险。

2.2 方案目标

核心目标

• 一线开发无感接入多 Portal，无需关注底层翻译实现差异；
• Portal 可高效管理跨域接入模块，降低翻译资源维护成本。

落地产出物

• 输出前端翻译最佳实践规范；
• 样板间强制落地规范，保证标准统一；
• 新项目从源头接入规范；
• 存量项目兼容过渡，支持增量升级。

三、现状分析

当前前端翻译主要分为「微前端多应用」与「单应用」两种模式，框架、资源加载、key 管理均不统一，痛点突出，同时参考业界成熟方案，明确优化方向。

3.1 核心应用模式

3.1.1 微前端多应用模式

采用单例模式：父应用提供翻译能力，子应用直接消费；通过 TSP 服务拉取翻译资源，支持实时更新，无需重新构建。

3.1.2 单应用模式

单应用分为两种资源加载策略，核心差异为是否支持动态更新：

1. 模式一（构建时缓存）：翻译资源与静态资源打包，更新需重构，不支持动态更新；

2. 模式二（缓存 + TSP）：本地缓存 + 实时拉取，支持动态更新，无需重构。

3.2 业界方案参考

参考 3 类主流国际化方案，提炼可借鉴的核心思路，结合自身业务场景优化落地：

3.2.1 抖音 Starling

以 CLI 工具为核心，串联开发、翻译、运营全流程，实现翻译标准化管理，核心优势是流程闭环、分工清晰。

3.2.2 阿里 Kiwi

依托 CLI 工具与 API，实现自动翻译、开发提示、本地文案管理一体化，核心优势是开发体验友好、自动化程度高。

3.2.3 VoerkaI18n 国际化框架

开源多包工程，提供 CLI 工具与多框架适配插件，支持命令行文本提取/编译，适配 Vue、React 等多框架，核心优势是兼容性强、可扩展性高。

四、方案设计

针对跨 Portal 翻译资源复用核心问题，采用「短期落地方案 + 长期演进方案」结合的思路，兼顾业务快速上线与架构可持续发展。

4.1 跨 Portal 翻译复用方案

4.1.1 方案对比

围绕跨 Portal 翻译资源复用，设计 3 种方案，从架构合理性、维护成本、落地难度综合对比：

方案 1：冗余上传 key（不推荐）

核心逻辑：各 Portal 绑定独立 Resource，模块向所有 Resource 上传重复 key 实现复用。
优点：Portal 无改造成本，接入简单。
缺点：key 分散维护、权责模糊，冗余 key 污染资源库，长期维护成本高。

方案 2：顺序查找 key（短期推荐）

核心逻辑：初始化加载多份 Resource，TSP 聚合资源，$gt 按优先级匹配 key（先加载覆盖后加载）。
优点：逻辑内聚、维护成本低，兼容现有技术栈、落地快。
缺点：需手动维护资源加载列表，加载多份资源存在轻微性能损耗。

方案 3：服务端聚合 Resource（长期演进）

核心逻辑：服务端统一配置资源组合规则，Portal 仅加载分配的资源集合。
优点：架构解耦，支持动态配置，业务层无感知。
缺点：需开发服务端合并逻辑，短期开发成本高。

4.1.2 方案选型结论

• 方案 1 弃用：长期维护成本不可控，存在严重技术债务；
• 方案 3 作为长期规划：依赖服务端开发，无法快速落地；
• 选定方案 2（短期推荐）：适配现有技术体系、落地快、副作用小，可平滑升级至方案 3。

4.2 长期演进方案

以「统一规范、高性能、易扩展、低成本」为目标，基于 react-i18next 重构翻译体系，解决跨 Portal 翻译底层架构痛点。

4.2.1 现有架构痛点与约束

核心痛点

• 框架异构：vue-i18n 与 react-i18next API、功能不一致；
• 能力不统一：多 Portal 的 $gt 函数行为差异，无法标准化开发；
• 动态翻译失效：变量赋值场景下，语言切换无法自动更新；
• 性能缺陷：同步 fetch 请求阻塞首屏渲染。

架构约束

• 翻译 key 由 transify-tool 生成，不直接使用原始文案，解决同文案不同翻译、长度限制问题；
• 运行时依赖 transify-client 解析，保证上传与运行时 key 规则一致；
• 工具强绑定，上下游耦合度高，扩展性差。

4.2.2 核心需求与设计思路

核心需求

• 开发标准化：全 Portal 统一调用写法，开发者无差异化感知；
• 加载高性能：优化资源加载，解决首屏阻塞问题；
• 落地低成本：兼容旧方案，支持增量迭代、平滑升级。

设计思路

• Portal 层：仅保留语言切换交互，剥离翻译底层实现；
• 工具层：封装初始化、调用、构建能力，提供统一通用工具。

4.2.3 统一开发写法规范（Lint 强制约束）

应用场景	标准写法	约束备注
基础翻译	$gt(‘xx’)	禁止全局定义变量（如 const a = $gt(‘xx’)）
Key 冲突处理	$gt(‘xx’，‘functionA’)	用命名空间区分模块
模板字符串	$gt(‘xx {name}’，null，{ name: ‘lay’ })	全局统一语法
富文本翻译	提取独立处理	穿插会导致机器翻译出错

4.2.4 翻译资源加载优化

构建「高性能、实时性、无阻塞」加载策略，可独立落地，不依赖热更新：

• 按需加载：最小化资源体积，非核心资源懒加载；
• 动态更新：每 2 小时自动拉取最新翻译资源；
• 预加载优化：用 prefetch link 预加载，避免首屏阻塞。

4.2.5 低成本落地策略

采用「最小改造、兼容共存、自动化支撑」方案，实现平滑迁移：

• 最小改动：仅修改 Portal 层逻辑，核心能力封装至通用工具包；
• 双版本共存：新老翻译体系并行，支持灰度迁移；
• 自动化工具：提供代码扫描 + 替换工具，快速完成存量改造。

五、整体方案与特殊场景设计

5.1 多场景方案对比

针对旧项目兼容、新项目标准化两类核心场景，提供差异化落地方案，覆盖存量改造与全新项目需求。

5.1.1 兼容方案（旧项目接入）

核心逻辑：主应用统一初始化国际化能力，子应用运行时自主判断环境，按需初始化对应框架实例，兼容多框架、多 Portal 混合场景。

适用场景：父子应用使用不同底层国际化框架、有独立 $gt 实例，适用于存量旧项目改造。
核心特点：支持 vue-i18n、react-i18next 并存，无需统一技术栈；子应用自治不侵入主应用；改造量小、落地快速。

5.1.2 标准方案（新项目标准化）

核心逻辑：面向无历史包袱、技术栈统一的全新微前端项目，通过容器统一管控、翻译工具自动化、配置中心化，实现国际化标准化接入。

适用场景：全新微前端/模块化项目、多应用多门户需统一规范、追求自动化与高可维护性的中大型项目。
核心优势：接入规范统一、自动化程度高、容器中心化管控、扩展性强、便于维护升级。

5.2 整体架构设计

采用「分层架构、统一协议、多端兼容、自动化闭环」设计，自上而下分为 7 层，支撑多门户、多框架、多场景标准化接入与管理。

架构分层说明

1. 应用层：承载多门户入口，通过 module 统一接入，实现入口收敛；
2. 产品层：按门户独立封装，各产品线隔离配置、遵循统一规范；
3. 统一协议层 $gt：提供全系统一 $gt 翻译协议，配套 webpack 集成、运行时调用、Lint 校验工具链；
4. transify-init：统一接收 setLang、changeLang、showKey 指令，实现全局状态收敛；
5. 翻译逻辑层：适配 vue-i18n、react-i18next，通过自研 proxy 层屏蔽框架差异；
6. 缓存数据层：通过 html prefetch、本地缓存等优化加载速度，减少重复请求；
7. 服务层：由 tsp 服务分发资源，transify 资源池存储多语言文案；
8. 自动化工具：通过 transify-tool 上传 Key、AI 自动翻译，形成全自动化闭环。

核心流程与优势

核心流程：

• 接入流程（多门户→module→产品层→统一协议→翻译逻辑）；
• 初始化控制（应用/产品层调用 transify-init）；
• 资源流程（翻译逻辑→缓存→服务层→资源池）；
• 自动化闭环（module→工具→上传→AI 翻译→资源池更新）。

架构优势：$gt 协议统一、多框架兼容、多门户隔离、性能优化、自动化程度高、可扩展性强。

5.3 特殊场景设计

5.3.1 初始化流程（翻译预加载）

规范与优化：

• 禁止 JS 直接赋值 $gt（避免热更新失效）；
• 不支持热更新时，刷新页面即可；
• 首次加载优先用离线包；
• 通过优化加载耗时，翻译资源每 2 小时自动更新。

5.3.2 多实例性能优化方案

痛点：多子应用独立初始化实例，导致内存占用高、加载耗时久，通过实例复用、资源共享优化，方案对比如下：

方案	说明	优点	缺点	结论
二次封装 product 层	产品线仅维护一个翻译实例	结构清晰、落地高效	通用性差，不适配产品内部差异	未来可扩展
翻译逻辑层 + 数据层复用	复用已创建的 vue-i18n 实例	同框架通用，大幅降低开销	跨框架不兼容（React）	提供扩展能力
仅数据层复用	底层缓存复用翻译资源	通用性最强，减少网络请求	需评估多实例开销占比	优先采用

核心思路：禁止子应用重复初始化资源；优先采用数据层复用；同框架可升级为逻辑 + 数据层复用；产品层封装作为长期方向。

六、统一翻译能力核心设计

6.1 翻译 SDK 设计

核心目标：封装统一 API、抹平 Vue / React 差异、提供标准翻译能力。

6.1.1 核心配置与方法

类型	名称	说明
构造选项	lang、region、resourcesIds、fetchKeys	lang 必填，其余选填；fetchKeys 支持自定义拉取逻辑
公共属性	i18n、$gt	i18n 实例、统一翻译函数
核心方法	init()	初始化 SDK、拉取资源、注入上下文

6.1.2 初始化流程

核心流程：初始化配置 → 创建 i18n 实例 → 拉取翻译资源 → 合并资源 → 生成 $gt 函数 → 返回函数

6.2 i18n 框架选择与适配

针对多技术栈现状，对比主流框架与适配方案，明确统一选型，确保多框架兼容。

6.2.1 现有框架现状对比

框架	应用场景	说明	缺点
vue-i18n	微前端 Vue 主应用	可在 React 中复用取值，依赖刷新更新	React 子应用不支持热更新
react-i18next	React 单应用	React 生态主流，依赖 I18nextProvider 注入	仅支持 React，Vue 无法兼容

6.2.2 统一适配方案选型

方式	使用方式	优点	缺点
主应用共享	主应用创建实例，子应用全局获取	灵活性高、开发量低	管控成本高，框架能力泛滥
统一 API 封装	对外提供标准化接口，按框架导入	API 统一，接入成本低	灵活性受限，存在一定开发量

七、总结与后续计划

7.1 核心设计原则

1. 开发无感知：统一 $gt 协议，业务无需关注底层差异；
2. 统一标准：全局统一规范，降低维护协作成本；
3. 性能优先：通过预加载、资源复用等优化性能；
4. 渐进式接入：兼容存量项目，支持增量迁移。

7.2 关键技术决策

决策点	选择	理由
语言切换方式	刷新页面	实现简单、稳定兼容，暂不引入热更新复杂度
跨 Portal 子应用	独立 Resource	子应用开发无感知，容器层抹平差异
性能优化方案	数据层复用	通用性强，大幅降低网络与资源开销
翻译资源加载	html prefetch	大幅优化加载耗时
i18n 统一适配	统一 API 封装	API 统一，接入成本低