Woodpecker 国际化(i18n)翻译指南:基于 Weblate 与 Vue I18n 的 Web UI 本地化实践

原创2026-09-27 19:31:471,859 阅读
文章标签:CI/CDDevOps

Woodpecker 国际化(i18n)翻译指南:基于 Weblate 与 Vue I18n 的 Web UI 本地化实践

本文以 Woodpecker 官方文档中的 Translations 章节为核心,结合 web 前端源码 中 Vue I18n 的初始化、语言包结构与语言切换实现,系统讲解如何通过官方 Weblate 实例为 Woodpecker 的 Web UI 贡献翻译、理解其底层本地化机制,以及如何查看、运行和配置多语言界面。

为什么 Woodpecker 需要独立的翻译流程

Woodpecker 是一个开源的 CI/CD 引擎,其 Web UI 由 Vue 3 前端(位于 web/src)承载,包含仓库列表、流水线状态、部署配置、用户设置等大量界面文案。为了让不同语言背景的团队都能流畅使用,项目为 Web UI 引入了完整的多语言(i18n)支持,而不是把文案硬编码在组件里。

翻译工作由官方搭建的 Weblate 翻译平台统一托管。项目官方文档(version-3.16/92-development/08-translations.md)明确指出两条核心规则:

  1. 所有语言翻译均在官方 Weblate 实例(translate.woodpecker-ci.org)上协作完成,译者需要先注册账号;
  2. 项目不接受任何修改非英语语言的 Pull Request,即英文原文的修改可以走 PR 流程,而其他语言的翻译必须通过 Weblate 提交。

这意味着:如果你发现某个界面文案在你使用的语言下翻译不准确,正确做法是前往 Weblate 修正对应语言的词条,而不是直接向仓库提交语言文件的改动。

翻译流程:在 Weblate 上协作

1. 注册并选择目标语言

打开官方 Weblate 实例并注册账号,然后选择你想要翻译的语言。Weblate 会展示所有语言条目的翻译进度,方便你找出缺口或有误的词条。

2. 逐条翻译界面文案

Weblate 以“词条(string)”为最小翻译单位,每个词条对应 UI 上的一句或一段文案,并附带原始英文参考与上下文提示。你可以在 Weblate 界面中直接编辑译文、查看其他译者的建议,并在需要时讨论确认。

3. 提交与合并

Weblate 会自动将翻译成果同步回 Woodpecker 的代码仓库(合并到 web/src/assets/locales 目录下对应语言的 JSON 文件中),无需你手动提交 PR。因此,除了英语之外的任何语言,都不建议(也不会被接受)通过 PR 方式修改。

底层实现:Vue I18n 与语言包结构

Woodpecker 的 Web UI 使用 Vue I18n 作为翻译库,这一点在原文档中亦有明确说明。从源码可以看到,所有界面文案以 JSON 语言包的形式存放在 web/src/assets/locales 目录下,目前包含 20+ 个语言文件,例如:

  • en.json(英语,默认语言与翻译基准)
  • zh-Hans.json / zh-Hant.json(简体 / 繁体中文)
  • de.json、fr.json、ja.json、ko.json、ru.json、es.json、pt.json 等

以 en.json 为例,语言包采用嵌套的键值结构组织,例如:

{
  "cancel": "Cancel",
  "repos": "Repos",
  "repositories": {
    "title": "Repositories",
    "all": {
      "title": "All repositories",
      "desc": "Repositories sorted by last pipeline creation"
    }
  },
  "time": {
    "just_now": "just now"
  }
}

组件中通过 t('repositories.all.title') 这类带路径的键名取用文案,同时支持 t('documentation_for', { topic: '...' }) 这样的插值参数(见 en.json 中的 "documentation_for": "Documentation for \"{topic}\"")。

i18n 实例的初始化

在 web/src/compositions/useI18n.ts 中,Vue I18n 实例的创建方式如下:

import { useStorage } from '@vueuse/core';
import { SUPPORTED_LOCALES } from 'virtual:vue-i18n-supported-locales';
import { createI18n } from 'vue-i18n';

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;
}

const fallbackLocale = 'en';
export const i18n = createI18n({
  locale: userLanguage,
  legacy: false,
  globalInjection: true,
  fallbackLocale,
});

关键点说明:

  • legacy: false:使用 Composition API 模式(Vue 3 推荐用法);
  • fallbackLocale: 'en':当某语言缺少某个词条时,自动回退到英文,保证界面永不出现空白文案;
  • 语言优先级:用户在设置中显式选择的语言(持久化在 woodpecker:locale)> 浏览器语言;
  • getUserLanguage() 会对浏览器语言做一次容错:若完整区域标签(如 zh-CN)不在支持列表,则截取语言主标签(zh)再次匹配。

语言包的按需加载

语言包并不是一次性全部打包进前端,而是通过动态 import 按需加载(见 useI18n.ts):

const loadLocaleMessages = async (locale: string) => {
  const messages = (await import(`~/assets/locales/${locale}.json`)) as { default: any };
  i18n.global.setLocaleMessage(locale, messages.default);
  return nextTick();
};

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);
};

启动时默认加载英语与用户当前语言,切换语言时再动态拉取对应的 JSON,这既控制了首屏体积,也让新增语言无需重新构建即可在运行时加载。

支持语言列表的生成

vite.config.ts 中通过一个虚拟模块 virtual:vue-i18n-supported-locales 动态读取 src/assets/locales/ 目录下的所有 .json 文件名,生成 SUPPORTED_LOCALES 数组,并在 vite-env.d.ts(web/src/vite-env.d.ts)中声明其类型。因此,每新增一个语言文件,支持的语言列表会自动更新,无需手工维护配置。

日期、时长等内容的本地化

除了文案,Woodpecker 还通过 web/src/compositions/useDate.ts 基于 Intl API 本地化日期与时长显示:切换语言时调用 setDateLocale(lang) 同步更新 currentLocale,使 toLocaleString()、Intl.RelativeTimeFormat(如“刚刚 / 3 分钟前”)和 Intl.NumberFormat 输出的单位文本随语言变化。

用户视角:如何查看与切换界面语言

Woodpecker Web UI 的用户可以在 用户设置 → 通用(User General) 页面选择界面语言。对应实现位于 web/src/views/user/UserGeneral.vue,其逻辑为:

  • 使用 SUPPORTED_LOCALES 构建语言下拉选项;
  • 将用户选择持久化到 localStorage 的 woodpecker:locale 键(通过 useStorage);
  • 选择变化时调用 setI18nLanguage(_selectedLocale) 动态切换语言并同步日期本地化。

因此,界面语言的优先级是:手动选择(持久化)> 浏览器语言 > 英文兜底。

贡献翻译时的注意事项

  • 先注册 Weblate 账号,然后在官方实例上选择你的语言进行翻译;
  • 只通过 Weblate 提交非英语翻译,不要针对语言文件开 PR(项目明确不接受);
  • 英文原文的修改(如措辞优化、新增文案键)可以通过正常 PR 流程提交,同时建议在 Weblate 中同步补充说明,便于各语言译者跟进;
  • 新增语言包时,应确保所有键与 en.json 保持一致(缺失键会触发 fallbackLocale 回退到英文,虽不影响可用性,但会留下未翻译的界面);
  • 翻译时请留意插值参数(如 {topic}、{pipelineId} 等占位符)与 HTML/占位上下文,避免破坏文案渲染。

小结

Woodpecker 的国际化体系可以概括为:Weblate 协作翻译 + Vue I18n 运行时加载 + 按语言分文件存储。对于使用者,只需在用户设置中选择语言即可获得本地化界面;对于贡献者,通过官方 Weblate 实例参与翻译是唯一被接受的非英语文案提交途径。相关源码(useI18n.ts、语言包目录、UserGeneral.vue)可帮助你进一步理解其实现细节。

登录后查看全文
woodpecker