Woodpecker 前端国际化指南:基于 Vue I18n 与 Weblate 的多语言翻译机制
Woodpecker 前端国际化指南:基于 Vue I18n 与 Weblate 的多语言翻译机制
Woodpecker 的 Web 界面通过社区驱动的翻译平台和 Vue I18n 运行时框架实现多语言支持,本文以 docs/versioned_docs/version-2.8/92-development/08-translations.md 为核心脉络,结合 web/ 前端源码,完整讲解翻译贡献流程、语言文件的组织方式、语言切换的运行时实现与本地化验证手段。读完本文后,你将掌握"如何为 Woodpecker 翻译界面文案、新增语言或修改英文基准文案"的完整实战路径,并能理解语言文件从静态 JSON 到浏览器渲染的整条调用链。
一、翻译贡献流程总览:Weblate 协作平台
Woodpecker 的界面翻译不采用传统的"改代码提 PR"模式,而是由官方自建的 Weblate 翻译平台统一托管。任何想要为 Woodpecker 界面贡献翻译的开发者,都应当按以下流程参与:
- 在官方 Weblate 翻译平台(
translate.woodpecker-ci.org)注册账号; - 选择 Woodpecker 项目,认领"ui"(界面)组件的翻译任务;
- 在 Web 端逐条翻译或批量导入译文;
- 翻译内容由维护者周期性同步回仓库。
官方翻译平台还提供了实时翻译进度徽章(多语言蓝色徽章),可以直接展示当前各语言的整体完成度,方便贡献者快速判断哪种语言最需要帮助。
为什么只接受英文 PR?
原文档明确声明:"We won't accept PRs changing any language except English." 即除英文之外,任何语言的文件改动都不会被 PR 接受。这一策略的工程意图非常清晰:
- 非英文语言文件统一由 Weblate 平台管理,避免出现"仓库 PR 与平台翻译双线并行"导致译文冲突、覆盖或丢失;
- Weblate 支持审校、术语表、翻译记忆等功能,质量管控比零散 PR 更可控;
- 英文是唯一的"基准语言"(fallback locale),所有非英文翻译都以英文文案为源串,因此英文的变更必须走正常的代码评审流程。
所以,贡献者需要区分两条路径:新增/修改英文文案走 GitHub PR;翻译为其他语言走 Weblate。
二、国际化技术栈:Vue I18n 与动态加载机制
原文档指出 Woodpecker 使用 Vue I18n 可以确认,前端依赖 vue-i18n@^11.3.2,并配套使用了 @intlify/unplugin-vue-i18n(Vite 构建插件,用于预编译消息)与 @intlify/eslint-plugin-vue-i18n(用于 lint 检查翻译 key 的使用)。
i18n 实例的初始化
核心初始化逻辑集中在 web/src/compositions/useI18n.ts,关键代码如下:
export function getUserLanguage(): string {
let browserLocale = navigator.language;
if (!SUPPORTED_LOCALES.includes(browserLocale)) {
browserLocale = browserLocale.split('-')[0];
}
const selectedLocale = useStorage('woodpecker:locale', browserLocale).value;
return selectedLocale;
}
export const i18n = createI18n({
locale: userLanguage,
legacy: false,
globalInjection: true,
fallbackLocale: 'en',
});
这里有几个关键设计值得展开:
legacy: false:使用 Vue I18n 的 Composition API 模式,配合 Vue 3 的组合式函数风格;globalInjection: true:允许在模板中直接使用$t()等全局注入能力;fallbackLocale: 'en':任何语言文件中缺失的 key 都会回退到英文文案,这也是"英文是基准语言"在代码层面的直接体现——即使某个语言翻译不完整,界面依然可用英文兜底。
语言文件的懒加载
loadLocaleMessages 使用动态 import() 按需加载语言包,而不是在启动时一次性引入全部语言:
const loadLocaleMessages = async (locale: string) => {
const messages = (await import(`~/assets/locales/${locale}.json`)) as { default: any };
i18n.global.setLocaleMessage(locale, messages.default);
return nextTick();
};
启动阶段只会预加载 fallbackLocale(en)与当前用户语言两份文件,其余语言在用户切换时才会加载,避免首屏打包体积膨胀。
语言切换
export const setI18nLanguage = async (lang: string): Promise<void> => {
if (!i18n.global.availableLocales.includes(lang)) {
await loadLocaleMessages(lang);
}
i18n.global.locale.value = lang;
await setDateLocale(lang);
};
setI18nLanguage 不仅切换翻译文案,还会同步调用 setDateLocale 更新日期时间格式化所使用的 locale(详见第五节)。
三、语言文件组织与支持的 Locale 列表
所有界面翻译文案都以 JSON 文件形式存放在 web/src/assets/locales/ 目录下,当前仓库包含以下 29 个语言文件:
ar.json(阿拉伯语)、bar.json(巴伐利亚语)、bn.json(孟加拉语)、cs.json(捷克语)、de.json(德语)、en.json(英语)、eo.json(世界语)、es.json(西班牙语)、fi.json(芬兰语)、fr.json(法语)、hi.json(印地语)、hu.json(匈牙利语)、id.json(印尼语)、it.json(意大利语)、ja.json(日语)、ko.json(韩语)、lo.json(老挝语)、lv.json(拉脱维亚语)、nb-NO.json(书面挪威语)、nl.json(荷兰语)、pl.json(波兰语)、pt.json(葡萄牙语)、ru.json(俄语)、th.json(泰语)、uk.json(乌克兰语)、ur.json(乌尔都语)、zh-Hans.json(简体中文)、zh-Hant.json(繁体中文)。
Locale 命名规范
从文件命名可以看出 Woodpecker 遵循 BCP 47 风格的语言代码规范:
- 同一语言的不同地区/书写系统使用
语言-地区形式,如nb-NO(挪威语-挪威)、zh-Hans(简体中文)、zh-Hant(繁体中文); - 通用语言使用简写,如
en、de、fr。
这一点与 getUserLanguage() 的降级逻辑相呼应:当浏览器的 navigator.language(例如 zh-CN)不在 SUPPORTED_LOCALES 列表中时,会先截取 - 之前的语言代码(zh),若仍不在列表中(仓库没有 zh.json),则最终回退到默认 en。这也是为什么简体/繁体中文必须使用带后缀的 zh-Hans / zh-Hant 才能被精确匹配。
SUPPORTED_LOCALES 的来源
支持的 locale 列表不是手工维护的常量,而是由 web/vite.config.ts 中的一个自定义 Vite 虚拟模块在构建时自动生成:
const filenames = readdirSync('src/assets/locales/').map((filename) => filename.replace('.json', ''));
// load 阶段导出: export const SUPPORTED_LOCALES = ["ar","bar",...]
也就是说,只要向 src/assets/locales/ 目录新增一个 JSON 文件,构建时该语言就会自动进入支持列表。同时 VueI18nPlugin 通过 include: path.resolve(import.meta.dirname, 'src/assets/locales/**') 将所有语言文件纳入编译管线。
四、英文基准文件:唯一允许通过 PR 修改的语言
web/src/assets/locales/en.json 是翻译工作的"源串"文件,也是原文档中"仅接受英文 PR"规则的落点。该文件采用嵌套 JSON 结构组织翻译 key,例如:
{
"cancel": "Cancel",
"unknown_error": "An unknown error occurred",
"not_found": {
"not_found": "Whoa 404, either we broke something or you had a typing mishap :-/",
"back_home": "Back to home"
},
"repositories": {
"title": "Repositories",
"all": { "title": "All repositories", "desc": "Repositories sorted by last pipeline creation" }
}
}
嵌套 key 在模板中通过 t('repositories.all.title') 之类的路径访问。消息中还支持参数插值,例如 "documentation_for": "Documentation for \"{topic}\"",运行时通过 t('documentation_for', { topic: ... }) 填充。
修改英文文案的正确姿势
- 修改
en.json中对应 key 的英文文案; - 通过 PR 提交,走正常的代码评审流程;
- 非英文文案不要在 PR 中改动——它们应由 Weblate 平台统一维护,改动会在后续同步中覆盖。
另外,翻译 key 的命名一致性受到 ESLint 插件 @intlify/eslint-plugin-vue-i18n 的约束(见 web/eslint.config.js 与 web/package.json),它能在 lint 阶段发现模板中使用了不存在的 key 或误写的情况。
五、从语言选择到界面渲染的完整链路
用户设置页的语言切换
用户可以在个人设置的"General"页面切换界面语言,实现在 web/src/views/user/UserGeneral.vue:
const localeOptions = computed(() =>
SUPPORTED_LOCALES.map((supportedLocale) => ({
value: supportedLocale,
text: new Intl.DisplayNames(supportedLocale, { type: 'language' }).of(supportedLocale) || supportedLocale,
})),
);
const storedLocale = useStorage('woodpecker:locale', locale.value);
const selectedLocale = computed<string>({
async set(_selectedLocale) {
await setI18nLanguage(_selectedLocale);
storedLocale.value = _selectedLocale;
},
get() {
return storedLocale.value;
},
});
两个细节值得注意:
- 语言名本地化显示:下拉框中的语言名称通过
Intl.DisplayNames生成,用户看到的语言名会以其自身语言显示(例如中文用户看到"简体中文"而非"Simplified Chinese"); - 选择持久化:用户选择写入 localStorage 的
woodpecker:locale键,与useI18n.ts中的getUserLanguage()读取逻辑完全对应——下次访问时直接使用存储值,优先于浏览器语言。
全局 lang 属性同步
web/src/App.vue 监听 locale 变化并同步更新 <html> 标签的 lang 属性:
const { locale } = useI18n();
watch(locale, (value) => {
document.documentElement.setAttribute('lang', value);
});
这保证了屏幕阅读器等辅助技术与浏览器的文本渲染行为能跟随界面语言切换,是国际化中常被忽视但重要的可访问性细节。
日期与相对时间的本地化
web/src/compositions/useDate.ts 将日期格式化与 i18n 绑定在一起:toLocaleString 使用 date.toLocaleString(currentLocale, ...),timeAgo 使用 Intl.RelativeTimeFormat(currentLocale) 生成"x 分钟前"等相对时间,prettyDuration 则使用 Intl.NumberFormat 的 unit 风格输出时长;当时间小于 30 秒时,会回退到翻译 key time.just_now(在 en.json 中定义),而不是硬编码"just now"字符串。这正是国际化做得彻底的表现:连相对时间这种动态文案都完全由 locale 驱动。
六、测试如何守护翻译质量
仓库中的组件测试直接引用真实的英文语言文件来校验文案 key,例如 web/src/components/agent/AgentForm.test.ts:
import en from '~/assets/locales/en.json';
// resolve the labels through the real locale file, so renaming a key there
// automatically breaks the test
同样的模式还出现在 web/src/components/form/ListEditor.test.ts、web/src/components/repo/pipeline/PipelineLog.test.ts 与 web/src/components/repo/pipeline/PipelineStepList.test.ts 中。
这套做法的工程价值在于:如果开发者在重构时误删或重命名了 en.json 中的某个 key,相关组件测试会立即失败(因为 t() 解析不到文案),从而在 CI 阶段就拦截"文案 key 与模板引用不一致"的问题,间接保护了所有依赖英文基准的其他语言翻译。
七、本地开发与验证建议
如果你想在本地验证翻译效果或调试语言切换逻辑:
- 前端开发环境依赖
pnpm(见 web/package.json 的packageManager字段),常用脚本包括pnpm start(启动 Vite dev server)、pnpm build、pnpm lint、pnpm test(Vitest 测试)、pnpm typecheck; - 临时测试某语言的显示效果时,可以在浏览器 localStorage 中设置
woodpecker:locale为对应语言代码(如zh-Hans),或直接在用户设置页的 General 中切换; - 若只是验证某个文案 key 是否被正确引用,可运行
pnpm test执行组件测试,或运行pnpm lint触发@intlify/eslint-plugin-vue-i18n的检查。
总结
Woodpecker 的国际化体系可以概括为三个层次:社区协作层(官方 Weblate 平台承载除英文外的全部翻译,仓库仅接受英文 PR)、静态资源层(src/assets/locales/ 下的 JSON 语言包,构建期自动生成支持列表)、运行时层(useI18n.ts 负责探测语言、持久化选择、懒加载语言包并联动日期格式化)。理解这三层,无论是作为翻译贡献者还是前端开发者,都能准确找到自己应该修改的文件与提交流程,避免"改了非英文文件却被拒绝"或"新增语言却不生效"的常见误区。