Vue I18n 中文文档

简体中文

English

简体中文

English

Appearance

Vue I18n 的小体积子集 ​

petite-vue-i18n 是 Vue I18n 的替代发行版，仅提供最少的功能。

与 Vue I18n 有什么区别？ ​

  • 体积比 vue-i18n 更小
    • CDN 或不使用构建工具
      • 包体积减小：运行时 + 编译器 ~32%，仅运行时 ~45%
      • petite-vue-i18n：运行时 + 编译器 ~9.61KB，仅运行时 ~5.51KB（生产构建，brotli 压缩）
      • vue-i18n：运行时 + 编译器 ~14.18KB，仅运行时 ~10.12KB（生产构建，brotli 压缩）
    • 浏览器的 ES 模块
      • 包体积减小：运行时 + 编译器 ~32%，仅运行时 ~45%
      • petite-vue-i18n：运行时 + 编译器 ~10.51KB，仅运行时 ~6.20KB（生产构建，brotli 压缩）
      • vue-i18n：运行时 + 编译器 ~15.40KB，仅运行时 ~11.12KB（生产构建，brotli 压缩）
    • 应用程序包大小
  • 不支持传统 API，仅支持组合式 API
  • 不包含以下日期时间格式、数字格式和工具的 API。仅支持翻译
    • n, $n
    • d, $d
    • rt, $rt
    • tm, $tm
    • getDateTimeFormat, setDateTimeFormat, mergeDateTimeFormat
    • getNumberFormat, setNumberFormat, mergeNumberFormat
  • 只能处理简单的键值本地化消息。如果要处理分层本地化消息，需要使用 API 进行自定义
  • 本地回退算法是 fallbackLocale 中指定的数组顺序
  • 不包含自定义指令 v-t
  • 不包含 vue-i18n 提供的以下组件
    • 翻译 i18n-t
    • 日期时间格式 i18n-d
    • 数字格式 i18n-n

petite-vue-i18n 的使用场景 ​

vue-i18n 包含各种 i18n 功能，如翻译、日期时间格式和数字格式。有些项目可能只使用翻译功能，而不使用日期时间格式。目前，即使在这种情况下，该功能的代码仍然包含在内。

如果您只使用 t 或 $t API 进行翻译，我们推荐您使用 petite-vue-i18n 而不是 vue-i18n。如果您的项目需要 vue-i18n 的功能，可以从 petite-vue-i18n 平滑迁移到 vue-i18n。这意味着这是渐进式增强。

安装 ​

基本上与安装 vue-i18n 相同。唯一的区别是 URL 或路径部分从 vue-i18n 更改为 petite-vue-i18n。

CDN ​

您需要在 <head> 结尾插入以下脚本：

html
<script src="https://unpkg.com/vue@next"></script>
<script src="https://unpkg.com/petite-vue-i18n"></script>

带脚本标签的应用程序代码如下：

html
<script>
const { createApp } = Vue
const { createI18n } = PetiteVueI18n

const i18n = createI18n({
  // 这里放一些 vue-i18n 选项...
})

const app = createApp({
  // 这里放一些 vue 选项...
})

app.use(i18n)
app.mount('#app')
</script>

包管理器 ​

sh
npm install petite-vue-i18n@next --save
sh
yarn add petite-vue-i18n@next
sh
pnpm add petite-vue-i18n@next
js
import { createApp } from 'vue'
import { createI18n } from 'petite-vue-i18n'

const i18n = createI18n({
  // 这里放一些 vue-i18n 选项...
})

const app = createApp({
  // 这里放一些 vue 选项...
})

app.use(i18n)
app.mount('#app')

用法 ​

你好世界 ​

模板：

html
<div id="app">
  <h1>{{ t('hello world') }}</h1>
</div>

脚本：

js
const { createApp } = Vue
const { createI18n, useI18n } = PetiteVueI18n
// 或者 ES 模块
// import { createApp } from 'vue'
// import { createI18n } from 'petite-vue-i18n'

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      'hello world': 'Hello world!'
    },
    ja: {
      'hello world': '你好，世界！'
    }
  }
})

// 定义 App 组件
const App = {
  setup() {
    const { t } = useI18n()
    return { t }
  }
}

const app = createApp(App)

app.use(i18n)
app.mount('#app')

使用与 vue-i18n 相同的消息解析器和本地回退器 ​

在 petite-vue-i18n 中，消息解析器和本地回退器使用简单实现来优化代码大小，如差异部分所述，如下所示：

  • 消息解析器
    • 解析键值样式本地化消息
    • 实现细节请见这里
  • 本地回退器
    • 根据 fallbackLocale 中指定的数组顺序回退
    • 如果指定了简单字符串形式的语言环境，回退到该语言环境
    • 实现细节请见这里

如果您想要使用与 vue-i18n 相同的消息解析器和本地回退器，可以使用 API 更改它们。

请注意，此时仅支持像 vite 和 webpack 这样的构建工具。

您需要使用包管理器将 @intlify/core-base 安装到您的项目中。

sh
npm install --save @intlify/core-base@next
sh
yarn add @intlify/core-base@next
sh
pnpm add @intlify/core-base@next

然后，在应用程序入口点，使用以下 API 配置消息解析器和本地回退器：

js
import { createApp } from 'vue'
import {
  createI18n,
  registerMessageResolver, // 注册消息解析器 API
  registerLocaleFallbacker, // 注册本地回退器 API
} from 'petite-vue-i18n'
import {
  resolveValue, // vue-i18n 默认使用的消息解析器
  fallbackWithLocaleChain // vue-i18n 默认使用的本地回退器
} from '@intlify/core-base'

// 注册 vue-i18n 的消息解析器
registerMessageResolver(resolveValue)

// 注册 vue-i18n 的本地回退器
registerLocaleFallbacker(fallbackWithLocaleChain)

// 一些代码...
// ...

使用以上设置后，本地化消息解析和本地回退将与 vue-i18n 中相同的方式处理，但请注意代码大小会略微增加。

设置构建工具插件 ​

如果您正在使用像 vite 这样的构建工具链构建应用程序，必须进行配置。 请按照以下方式设置 @intlify/unplugin-vue-i18n 配置中的 'module' 选项。

NOTE

关于 @intlify/unplugin-vue-i18n 设置，请参阅'performance' 部分 和 @intlify/unplugin-vue-i18n 文档

IMPORTANT

@intlify/unplugin-vue-i18n 版本必须 5.1.0 及更高版本

diff
 // vite.config.ts
 import { defineConfig } from 'vite'
 import { resolve, dirname } from 'node:path'
 import { fileURLToPath } from 'url'
 import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

 export default defineConfig({
   /* ... */
   plugins: [
     /* ... */
     VueI18nPlugin({
       /* 选项 */
+      module: 'petite-vue-i18n',
       // 本地化消息资源预编译选项
       include: resolve(dirname(fileURLToPath(import.meta.url)), './path/to/src/locales/**'),
     }),
   ],
 })

无需更改导入 ID 即可切换 ​

您可以在应用程序中使用 npm 别名从 vue-i18n 切换到 petite-vue-i18n，而无需更改导入 ID。

package.json:

diff
 {
   // ...
   "dependencies": {
     "vue": "^3.4.14",
-    "vue-i18n": "^10.0.0"
+    "vue-i18n": "npm:petite-vue-i18n@^10.0.0"
   },
 }

您需要 @intlify/unplugin-vue-i18n 来构建您的应用程序。

Copyright © 2026-present allyouneed.tools