前端国际化全流程落地：TSF / TSP 翻译工具实战指南（Vue 版）
导读
本文详细讲解前端项目国际化翻译的全流程落地方案，涵盖「翻译平台配置→工具初始化→开发实现→发布上线→回滚操作」核心环节，重点介绍 TSF 翻译工具、TSP 平台的实操配置与最佳实践，解决翻译文件管理、多环境发布、缓存处理等核心问题，适配 Vue 技术栈的国际化开发场景。
一、整体概览
api请求服务
返回翻译文件
业务开发
业务开发
npx spc-tsf update
npx spc-tsf upload
npx spc-tsf export
终端
i18n, $gt, tsp 平台初始化，集成翻译
TSP 平台对 key 进行分环境版本管理，包括发布，回滚操作
短文案，不易变的文案，使用 $gt 函数，依靠翻译平台扫描生产 hash key,上传翻译平台
长文案，公共文案，使用明确的 key，上传到 transify 平台，使用 $t 进行翻译
上传到 transify 平台
导出新增 key，提供给业务翻译
业务翻译完成
1.1 核心流程
国际化翻译落地分为 5 个核心阶段，流程闭环如下：
翻译平台配置
翻译工具初始化
开发阶段（$t / $gt 使用）
发布阶段（NonLive / Live）
回滚操作（仅 Live）
1.2 核心工具功能速览
| 功能 | 所属工具 | 核心作用 |
|---|---|---|
| spc-tsf update | TSF 翻译工具 | 扫描代码提取翻译 key，自动上传至翻译平台 |
| spc-tsf upload / download | TSF 翻译工具 | 批量上传 / 下载翻译文件（JSON 格式） |
| spc-tsf export | TSF 翻译工具 | 导出指定版本间的翻译 key（CSV 格式） |
| generateTransifyCommon | TSF 翻译工具 | 生成规范翻译函数 $gt（用于 key 扫描） |
| useSPCTransify | TSF 翻译工具 | 页面显示翻译 key / 内容切换（调试用） |
| TSP SDK Create / SwitchLanguage | TSP 平台 | 初始化语言、切换语言、拉取翻译文件 |
| TSP 发布 / 回滚 | TSP 平台 | 翻译内容多环境发布、线上版本回滚 |
二、初始化准备：平台与工具配置
2.1 翻译平台（Transify）项目创建
步骤1：创建 Project 并获取 Resource ID
在翻译平台完成项目创建，生成唯一的 Resource ID（后续配置核心参数）。
步骤2：获取 Token
生成并保存 download/upload 对应的 Token（翻译工具鉴权使用）。
2.2 TSF 翻译工具初始化
TSF 工具用于扫描、上传、导出翻译 key，核心依赖两个包，初始化流程如下：
步骤2.2.1 安装依赖
npminstall @spcfe-common/utils-transify @spcfe-common/utils-transify-client 步骤2.2.2 核心配置（transify.config.js）
执行初始化命令生成配置文件，替换占位符为实际值：
npx spc-tsf init // 项目根目录 transify.config.js - 翻译工具核心配置 module.exports ={project:'{projectName}',// 项目名（作为 key 前缀，不可随意修改）token:'***',// 翻译平台 TokenresourceId:'{resourceId}',// 翻译平台项目 ID// 上传 / 下载接口（替换 {resourceId} 为实际值）uploadUrl:'https://transify.seagroup.com/api/resources/{resourceId}/languagestoken/import/json',downloadUrl:'https://transify.seagroup.com/api/resources/{resourceId}/languagestoken/export/json',funName:['$gt'],// 需扫描的翻译函数名fileType:['*.js','*.vue'],// 需扫描的文件类型};步骤2.2.3 Git Hook 配置（自动扫描key）
在 package.json 配置钩子，提交代码时自动扫描新增key并上传：
"scripts":{"diff":"npx spc-tsf update",// 扫描并上传新增 key},"husky":{"hooks":{"post-commit":"npm run diff"// 提交后执行扫描}}2.3 TSP 平台配置（推荐）
TSP 平台通过 API 线上拉取翻译文件，支持多环境管理，替代本地打包翻译文件的方式，配置步骤：
步骤2.3.1 平台操作
- 创建 Permission Group（权限组）；
- 添加 Resource（关联 Resource ID、权限组，配置自动发布规则）；
步骤2.3.2 安装 TSP SDK
yarnadd [email protected] 三、开发阶段：翻译功能实现
3.1 首次接入：核心能力集成（Vue 示例）
初始化 i18n、$gt 翻译函数、TSP SDK，实现翻译文件异步拉取：
import Vue from'vue';import VueI18n from'vue-i18n';import{ generateTransifyCommon }from'@spcfe-common/utils-transify-client';import{ Translator }from'@spcfe-common/tsp-sdk'; Vue.use(VueI18n);// 1. 初始化 i18nconst i18n =newVueI18n({locale:'en',// 默认语言fallbackLocale:'en',// 兜底语言messages:{},// 初始为空，通过 TSP 拉取});// 2. 初始化 TSP Translatorconst translator =newTranslator({projectId:'your-project-id',// TSP项目ID});// 核心参数配置const resourceId = xxx;// 翻译平台Resource IDconst env = process.env.NODE_ENV==='production'?'live':'nonLive';const currentLang ='en';// 3. 异步拉取翻译文件constfetchLocales=async()=>{try{const{ translation }=await translator.create({ env,// 环境：live / nonLivelocale: currentLang,// 目标语言（en / vi / th / zh-Hans 等）translation:{resources:[resourceId]},// 关联的 Resource ID}); i18n.mergeLocaleMessage(currentLang, translation);// 合并到 i18n}catch(e){ console.error('翻译文件拉取失败：', e);}};// 4. 生成 $gt 翻译函数（供 TSF 扫描）const $gt =generateTransifyCommon({t:(key, options)=> i18n.t(key, options),// 复用 i18n 的 t 函数project:'your-project-name',// 与 transify.config.js 的 project 一致});// 5. 全局挂载 + 应用初始化Vue.prototype.$gt = $gt;asyncfunctioninit(){awaitfetchLocales();// 先拉取翻译，再初始化 VuenewVue({el:'#app', i18n,render:h=>h(App),});}init();3.2 翻译函数使用规范
3.2.1 $t 函数：适用于通用 / 易变文案
适用场景：统一提示文案、后台返回内容、需频繁修改的文案。
使用方式：
- 执行
npx spc-tsf upload transify_keys.json上传至翻译平台；
业务代码中使用：
console.log(this.$t('common.tips.success'));// 输出翻译后内容手动维护 transify_keys.json 定义 key 和初始内容：
{"common.tips.success":"操作成功","common.tips.error":"操作失败"}3.2.2 $gt 函数：适用于短 / 稳定文案
适用场景：简短固定文案（如按钮文字、标签）。
核心特性：自动生成 hash key（无需手动定义），TSF 扫描后上传至平台。
使用方式：
// 基础使用 console.log(this.$gt('Hello!'));// 指定命名空间 console.log(this.$gt('Hello!','namespace'));// 带参数 console.log(this.$gt('Hello {name}!',null,{name:'lay'}));// 注意：第二个参数为命名空间，无则传null3.2.3 $gt 避坑点
$gt 依赖异步拉取的翻译文件，禁止在常量 / 初始化代码中直接使用（会因翻译未加载导致失效），建议封装为函数：
// 错误示例：常量中直接使用（翻译未加载时返回原文案）constTITLE=$gt('首页');// 正确示例：封装为函数，按需执行constgetTitle=()=>$gt('首页');四、发布阶段：多环境发布策略
4.1 废弃方案：本地打包翻译文件
原方案通过构建前拉取翻译文件打包进 bundle，缺点是无法实时更新、增大包体积，已废弃：
"scripts":{"build":"npm run transify && npm run build","transify":"npx spc-tsf download",}4.2 推荐方案：TSP 平台发布
接入 TSP 后，翻译文件通过 API 线上拉取，发布操作在 TSP 平台完成：
步骤1：触发发布
在 TSP 平台的 Resource Detail 页面点击「发布」按钮，确认版本变更后提交。
步骤2：多环境发布规则
| 环境 | 覆盖范围 | 发布策略 |
|---|---|---|
| NonLive | 开发 / 测试 / UAT / 预发 | 每 2 小时自动发布（有变更时），也可手动发布 |
| Live | 生产环境 | 支持自动 / 手动发布，由专人负责（代码合入后执行） |
4.3 缓存注意事项
- TSP API 存在 5 分钟强缓存，发布后需强刷页面才能看到最新翻译；
- TSP SDK ≥ xxx 版本时，会用 IndexedDB 缓存翻译文件，导致需刷新两次才能生效（开发环境建议用 < xxx 版本）。
五、回滚操作：Live 环境版本回退
5.1 回滚说明
仅支持 Live 环境回滚，基于已发布版本的 key 维度操作，最多回滚最近 4 个版本。
5.2 操作步骤
- 进入 TSP 平台 Resource Detail 页面；
- 点击「rollback」按钮，选择目标语言和回滚版本；
- 确认后完成回滚（自动发布功能会暂停，需手动重新开启）。
六、辅助功能：调试与导出
6.1 导出新增未翻译 key
导出指定版本间的新增 key（供业务翻译）：
npx spc-tsf export--from<源分支 commitId>--to<开发分支 commitId># 导出文件：项目根目录 / transify-export-file.csv6.2 ShowKey 调试功能
页面切换显示「翻译 key」/「翻译内容」，方便定位问题：
import{ useSPCTransify }from'@spcfe-common/utils-transify-client';// 初始化 ShowKeyuseSPCTransify((lang)=>{// 语言切换回调 i18n.locale = lang; location.reload();},()=> i18n.locale // 当前语言);七、核心注意事项
- TSP 兜底机制：API 拉取失败 / 超时（默认 3s）时，自动拉取 CDN 翻译文件；
- IndexedDB 缓存：SDK ≥ xxx 版本启用；
- 发布后生效：Live 环境发布后需强刷页面，缓存 5 分钟后自动失效；
- 回滚影响：回滚后自动发布功能暂停，需手动重新发布。
八、总结与最佳实践
8.1 核心流程回顾
初始化 → 开发（$t / $gt） → 发布（NonLive / Live） → 回滚（仅 Live） 8.2 最佳实践
- 翻译函数选择：短 / 稳定文案用 $gt，通用 / 易变文案用 $t；
- 异步加载：翻译文件拉取完成后再渲染页面，避免 $gt 失效；
- 发布管控：NonLive 环境按需发布，Live 环境专人负责；
- 缓存处理：生产环境发布后提醒用户强刷，内部系统降级 SDK 版本。
