1. 为什么需要手写Vue3的i18n方案在开发Vue3项目时国际化(i18n)是很多中大型项目的标配需求。虽然市面上有成熟的i18n库如vue-i18n但自己实现一个极简版本能带来几个显著优势首先对于小型项目或特定场景引入完整i18n库可能显得臃肿。一个极简实现可能只有几十行代码却能满足基本的多语言切换需求。其次通过手写实现可以更深入理解Vue3的响应式原理和组合式API的设计思想。最后自定义实现可以完全按照项目需求定制避免不必要的功能冗余。我在最近的一个后台管理系统项目中就遇到了这样的场景项目规模不大但需要支持中英文切换。经过评估后我决定自己实现一个不足50行的i18n方案效果出乎意料的好。2. 核心设计思路与架构2.1 基于Composition API的设计Vue3的组合式API为我们提供了完美的实现基础。我们将使用ref来管理当前语言状态通过provide/inject实现跨组件共享再配合计算属性实现动态翻译。import { ref, computed, provide, inject } from vue type Translations Recordstring, Recordstring, string type I18nOptions { locale: string fallbackLocale: string messages: Translations }这种设计有几个关键考虑使用TypeScript类型定义增强代码可维护性通过ref保持响应式状态计算属性自动处理依赖追踪provide/inject实现依赖注入2.2 消息格式设计我们采用JSON格式存储翻译消息结构如下{ en: { hello: Hello World, button: { submit: Submit, cancel: Cancel } }, zh: { hello: 你好世界, button: { submit: 提交, cancel: 取消 } } }这种嵌套结构既支持简单的键值对也能处理复杂的分组场景同时保持极佳的可读性。3. 完整实现步骤3.1 创建i18n实例首先我们创建一个createI18n函数来初始化i18n实例export function createI18n(options: I18nOptions) { const locale ref(options.locale) const fallbackLocale ref(options.fallbackLocale) const messages reactive(options.messages) const t (key: string) { return computed(() { return ( messages.value[locale.value]?.[key] || messages.value[fallbackLocale.value]?.[key] || key ) }).value } return { locale, fallbackLocale, messages, t, install(app: App) { app.provide(i18n, this) } } }关键点解析使用ref保持locale的响应式reactive处理messages对象t函数实现翻译查找逻辑提供Vue插件安装接口3.2 在应用中使用在main.ts中初始化import { createApp } from vue import App from ./App.vue import { createI18n } from ./i18n const i18n createI18n({ locale: en, fallbackLocale: en, messages: { en: { welcome: Welcome, // 其他翻译... }, zh: { welcome: 欢迎, // 其他翻译... } } }) const app createApp(App) app.use(i18n) app.mount(#app)3.3 组件内使用翻译在任何组件中可以通过inject获取i18n实例import { inject } from vue const i18n inject(i18n) // 模板中使用 template h1{{ i18n.t(welcome) }}/h1 /template4. 高级功能实现4.1 支持插值变量实际项目中经常需要动态插入变量我们扩展t函数const t (key: string, params?: Recordstring, unknown) { let result messages.value[locale.value]?.[key] || messages.value[fallbackLocale.value]?.[key] || key if (params) { Object.keys(params).forEach(k { result result.replace({${k}}, String(params[k])) }) } return result }使用示例i18n.t(welcomeUser, { name: John }) // 对应翻译: Welcome, {name} → Welcome, John4.2 支持复数形式处理不同数量的显示const t (key: string, count?: number) { const message messages.value[locale.value]?.[key] || messages.value[fallbackLocale.value]?.[key] || key if (count ! undefined) { if (count 0 message.zero) return message.zero if (count 1 message.one) return message.one if (count 1 message.other) return message.other.replace({count}, String(count)) } return message }翻译文件需要相应调整{ items: { zero: No items, one: 1 item, other: {count} items } }5. 性能优化与注意事项5.1 避免不必要的重新渲染由于我们的t函数返回的是计算属性Vue会自动优化依赖追踪。但要注意不要在模板中直接调用复杂逻辑的t函数对于静态翻译可以在setup中预先计算对于频繁变化的变量考虑使用memoization5.2 按需加载语言包对于大型项目可以动态加载语言包const loadLocale async (locale: string) { const messages await import(./locales/${locale}.json) i18n.messages.value[locale] messages.default }5.3 与路由集成通常语言切换需要与路由同步import { watch } from vue import { useRouter } from vue-router const router useRouter() watch(i18n.locale, (newVal) { router.push({ params: { lang: newVal } }) })6. 常见问题与解决方案6.1 翻译缺失处理当找不到对应翻译时我们有几种处理方案回退到fallback语言当前实现显示key本身当前实现记录缺失的key用于后续补充抛出错误提醒开发者可以在t函数中添加相应逻辑const missingKeys new Setstring() const t (key: string) { if (!messages.value[locale.value]?.[key]) { missingKeys.add(key) console.warn(Missing translation for key: ${key}) } // 其余逻辑... }6.2 动态切换语言实现语言切换功能const changeLocale (newLocale: string) { if (messages.value[newLocale]) { locale.value newLocale } else { console.warn(Locale ${newLocale} is not available) } }在组件中使用select v-modelcurrentLocale changechangeLocale option valueenEnglish/option option valuezh中文/option /select6.3 与SSR兼容在服务端渲染场景下需要特殊处理避免ref/reactive在服务端使用通过cookie获取用户语言偏好同步客户端和服务端状态可以创建一个ssr友好的版本export function createSSRI18n(options: I18nOptions) { let locale options.locale const t (key: string) { return options.messages[locale]?.[key] || options.messages[options.fallbackLocale]?.[key] || key } return { locale, t, install(app: App) { app.config.globalProperties.$t t } } }7. 测试策略7.1 单元测试使用Vitest编写测试用例import { describe, it, expect } from vitest import { createI18n } from ./i18n describe(i18n, () { const i18n createI18n({ locale: en, fallbackLocale: en, messages: { en: { hello: Hello }, zh: { hello: 你好 } } }) it(should translate, () { expect(i18n.t(hello)).toBe(Hello) i18n.locale.value zh expect(i18n.t(hello)).toBe(你好) }) })7.2 端到端测试使用Cypress测试语言切换describe(Language Switch, () { it(should change language, () { cy.visit(/) cy.contains(Hello) cy.get(select).select(zh) cy.contains(你好) }) })8. 与现有生态集成8.1 与Pinia集成可以创建一个i18n storeimport { defineStore } from pinia export const useI18nStore defineStore(i18n, () { const locale ref(en) const t createTranslator(locale) return { locale, t } })8.2 与Vue Router集成在路由守卫中处理语言router.beforeEach((to) { const newLocale to.params.lang if (newLocale i18n.messages.value[newLocale]) { i18n.locale.value newLocale } })9. 完整代码示例以下是完整的i18n实现代码// i18n.ts import { ref, computed, reactive, provide, inject, App } from vue type Translations Recordstring, Recordstring, string type I18nOptions { locale: string fallbackLocale: string messages: Translations } export function createI18n(options: I18nOptions) { const locale ref(options.locale) const fallbackLocale ref(options.fallbackLocale) const messages reactive(options.messages) const missingKeys new Setstring() const t (key: string, params?: Recordstring, unknown) { let result messages[locale.value]?.[key] || messages[fallbackLocale.value]?.[key] || key if (typeof result ! string) { console.warn(Translation for ${key} is not a string) return key } if (!messages[locale.value]?.[key] !missingKeys.has(key)) { missingKeys.add(key) console.warn(Missing translation for key: ${key}) } if (params) { Object.keys(params).forEach(k { result result.replace(new RegExp(\\{${k}\\}, g), String(params[k])) }) } return result } const changeLocale (newLocale: string) { if (messages[newLocale]) { locale.value newLocale } else { console.warn(Locale ${newLocale} is not available) } } const i18n { locale, fallbackLocale, messages, t, changeLocale, install(app: App) { app.provide(i18n, this) app.config.globalProperties.$t t } } return i18n } export function useI18n() { const i18n inject(i18n) if (!i18n) throw new Error(i18n not installed) return i18n }10. 实际项目中的应用技巧在真实项目中使用时我有几个实用建议组织翻译文件按功能模块拆分翻译文件如auth.json、dashboard.json等便于维护自动化提取编写脚本自动提取模板中的$t()调用生成翻译key列表命名规范采用module.component.key的命名约定如auth.login.title开发环境提示在开发模式下显示翻译key的边界便于检查const t (key: string) { const result /* 获取翻译逻辑 */ if (process.env.NODE_ENV development) { return [${result}] } return result }与CI集成在CI流程中加入翻译完整性检查确保所有key都有对应翻译这个极简i18n实现虽然小巧但覆盖了大部分常见需求。在我的项目中50行左右的代码就完美替代了vue-i18n打包体积减少了近30KB。对于不需要复杂国际化功能的项目来说这种轻量级方案是非常值得考虑的。 Vue3轻量级i18n方案实现与优化
1. 为什么需要手写Vue3的i18n方案在开发Vue3项目时国际化(i18n)是很多中大型项目的标配需求。虽然市面上有成熟的i18n库如vue-i18n但自己实现一个极简版本能带来几个显著优势首先对于小型项目或特定场景引入完整i18n库可能显得臃肿。一个极简实现可能只有几十行代码却能满足基本的多语言切换需求。其次通过手写实现可以更深入理解Vue3的响应式原理和组合式API的设计思想。最后自定义实现可以完全按照项目需求定制避免不必要的功能冗余。我在最近的一个后台管理系统项目中就遇到了这样的场景项目规模不大但需要支持中英文切换。经过评估后我决定自己实现一个不足50行的i18n方案效果出乎意料的好。2. 核心设计思路与架构2.1 基于Composition API的设计Vue3的组合式API为我们提供了完美的实现基础。我们将使用ref来管理当前语言状态通过provide/inject实现跨组件共享再配合计算属性实现动态翻译。import { ref, computed, provide, inject } from vue type Translations Recordstring, Recordstring, string type I18nOptions { locale: string fallbackLocale: string messages: Translations }这种设计有几个关键考虑使用TypeScript类型定义增强代码可维护性通过ref保持响应式状态计算属性自动处理依赖追踪provide/inject实现依赖注入2.2 消息格式设计我们采用JSON格式存储翻译消息结构如下{ en: { hello: Hello World, button: { submit: Submit, cancel: Cancel } }, zh: { hello: 你好世界, button: { submit: 提交, cancel: 取消 } } }这种嵌套结构既支持简单的键值对也能处理复杂的分组场景同时保持极佳的可读性。3. 完整实现步骤3.1 创建i18n实例首先我们创建一个createI18n函数来初始化i18n实例export function createI18n(options: I18nOptions) { const locale ref(options.locale) const fallbackLocale ref(options.fallbackLocale) const messages reactive(options.messages) const t (key: string) { return computed(() { return ( messages.value[locale.value]?.[key] || messages.value[fallbackLocale.value]?.[key] || key ) }).value } return { locale, fallbackLocale, messages, t, install(app: App) { app.provide(i18n, this) } } }关键点解析使用ref保持locale的响应式reactive处理messages对象t函数实现翻译查找逻辑提供Vue插件安装接口3.2 在应用中使用在main.ts中初始化import { createApp } from vue import App from ./App.vue import { createI18n } from ./i18n const i18n createI18n({ locale: en, fallbackLocale: en, messages: { en: { welcome: Welcome, // 其他翻译... }, zh: { welcome: 欢迎, // 其他翻译... } } }) const app createApp(App) app.use(i18n) app.mount(#app)3.3 组件内使用翻译在任何组件中可以通过inject获取i18n实例import { inject } from vue const i18n inject(i18n) // 模板中使用 template h1{{ i18n.t(welcome) }}/h1 /template4. 高级功能实现4.1 支持插值变量实际项目中经常需要动态插入变量我们扩展t函数const t (key: string, params?: Recordstring, unknown) { let result messages.value[locale.value]?.[key] || messages.value[fallbackLocale.value]?.[key] || key if (params) { Object.keys(params).forEach(k { result result.replace({${k}}, String(params[k])) }) } return result }使用示例i18n.t(welcomeUser, { name: John }) // 对应翻译: Welcome, {name} → Welcome, John4.2 支持复数形式处理不同数量的显示const t (key: string, count?: number) { const message messages.value[locale.value]?.[key] || messages.value[fallbackLocale.value]?.[key] || key if (count ! undefined) { if (count 0 message.zero) return message.zero if (count 1 message.one) return message.one if (count 1 message.other) return message.other.replace({count}, String(count)) } return message }翻译文件需要相应调整{ items: { zero: No items, one: 1 item, other: {count} items } }5. 性能优化与注意事项5.1 避免不必要的重新渲染由于我们的t函数返回的是计算属性Vue会自动优化依赖追踪。但要注意不要在模板中直接调用复杂逻辑的t函数对于静态翻译可以在setup中预先计算对于频繁变化的变量考虑使用memoization5.2 按需加载语言包对于大型项目可以动态加载语言包const loadLocale async (locale: string) { const messages await import(./locales/${locale}.json) i18n.messages.value[locale] messages.default }5.3 与路由集成通常语言切换需要与路由同步import { watch } from vue import { useRouter } from vue-router const router useRouter() watch(i18n.locale, (newVal) { router.push({ params: { lang: newVal } }) })6. 常见问题与解决方案6.1 翻译缺失处理当找不到对应翻译时我们有几种处理方案回退到fallback语言当前实现显示key本身当前实现记录缺失的key用于后续补充抛出错误提醒开发者可以在t函数中添加相应逻辑const missingKeys new Setstring() const t (key: string) { if (!messages.value[locale.value]?.[key]) { missingKeys.add(key) console.warn(Missing translation for key: ${key}) } // 其余逻辑... }6.2 动态切换语言实现语言切换功能const changeLocale (newLocale: string) { if (messages.value[newLocale]) { locale.value newLocale } else { console.warn(Locale ${newLocale} is not available) } }在组件中使用select v-modelcurrentLocale changechangeLocale option valueenEnglish/option option valuezh中文/option /select6.3 与SSR兼容在服务端渲染场景下需要特殊处理避免ref/reactive在服务端使用通过cookie获取用户语言偏好同步客户端和服务端状态可以创建一个ssr友好的版本export function createSSRI18n(options: I18nOptions) { let locale options.locale const t (key: string) { return options.messages[locale]?.[key] || options.messages[options.fallbackLocale]?.[key] || key } return { locale, t, install(app: App) { app.config.globalProperties.$t t } } }7. 测试策略7.1 单元测试使用Vitest编写测试用例import { describe, it, expect } from vitest import { createI18n } from ./i18n describe(i18n, () { const i18n createI18n({ locale: en, fallbackLocale: en, messages: { en: { hello: Hello }, zh: { hello: 你好 } } }) it(should translate, () { expect(i18n.t(hello)).toBe(Hello) i18n.locale.value zh expect(i18n.t(hello)).toBe(你好) }) })7.2 端到端测试使用Cypress测试语言切换describe(Language Switch, () { it(should change language, () { cy.visit(/) cy.contains(Hello) cy.get(select).select(zh) cy.contains(你好) }) })8. 与现有生态集成8.1 与Pinia集成可以创建一个i18n storeimport { defineStore } from pinia export const useI18nStore defineStore(i18n, () { const locale ref(en) const t createTranslator(locale) return { locale, t } })8.2 与Vue Router集成在路由守卫中处理语言router.beforeEach((to) { const newLocale to.params.lang if (newLocale i18n.messages.value[newLocale]) { i18n.locale.value newLocale } })9. 完整代码示例以下是完整的i18n实现代码// i18n.ts import { ref, computed, reactive, provide, inject, App } from vue type Translations Recordstring, Recordstring, string type I18nOptions { locale: string fallbackLocale: string messages: Translations } export function createI18n(options: I18nOptions) { const locale ref(options.locale) const fallbackLocale ref(options.fallbackLocale) const messages reactive(options.messages) const missingKeys new Setstring() const t (key: string, params?: Recordstring, unknown) { let result messages[locale.value]?.[key] || messages[fallbackLocale.value]?.[key] || key if (typeof result ! string) { console.warn(Translation for ${key} is not a string) return key } if (!messages[locale.value]?.[key] !missingKeys.has(key)) { missingKeys.add(key) console.warn(Missing translation for key: ${key}) } if (params) { Object.keys(params).forEach(k { result result.replace(new RegExp(\\{${k}\\}, g), String(params[k])) }) } return result } const changeLocale (newLocale: string) { if (messages[newLocale]) { locale.value newLocale } else { console.warn(Locale ${newLocale} is not available) } } const i18n { locale, fallbackLocale, messages, t, changeLocale, install(app: App) { app.provide(i18n, this) app.config.globalProperties.$t t } } return i18n } export function useI18n() { const i18n inject(i18n) if (!i18n) throw new Error(i18n not installed) return i18n }10. 实际项目中的应用技巧在真实项目中使用时我有几个实用建议组织翻译文件按功能模块拆分翻译文件如auth.json、dashboard.json等便于维护自动化提取编写脚本自动提取模板中的$t()调用生成翻译key列表命名规范采用module.component.key的命名约定如auth.login.title开发环境提示在开发模式下显示翻译key的边界便于检查const t (key: string) { const result /* 获取翻译逻辑 */ if (process.env.NODE_ENV development) { return [${result}] } return result }与CI集成在CI流程中加入翻译完整性检查确保所有key都有对应翻译这个极简i18n实现虽然小巧但覆盖了大部分常见需求。在我的项目中50行左右的代码就完美替代了vue-i18n打包体积减少了近30KB。对于不需要复杂国际化功能的项目来说这种轻量级方案是非常值得考虑的。