From ba3e3c648d07c6e157feb87681a950f6ad9f41ab Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Thu, 23 May 2024 16:37:52 +0900 Subject: [PATCH 1/3] feat: move to GA from experimental for petite-vue-i18n --- packages/petite-vue-i18n/README.md | 67 ++++++++++++------- .../size-check-petite-vue-i18n/vite.config.ts | 3 +- packages/size-check-vue-i18n/vite.config.ts | 4 +- 3 files changed, 46 insertions(+), 28 deletions(-) diff --git a/packages/petite-vue-i18n/README.md b/packages/petite-vue-i18n/README.md index aca9d0793..da5a049ad 100644 --- a/packages/petite-vue-i18n/README.md +++ b/packages/petite-vue-i18n/README.md @@ -4,19 +4,19 @@ Small size subset of Vue I18n `petite-vue-i18n` is an alternative distribution of Vue I18n, which provides only minimal features. -## :question: What is the difference from Vue I18n ? +## ❓ What is the difference from Vue I18n ? - The Size is smaller than vue-i18n - CDN or without a Bundler - - Reduce size: runtime + compiler `~36%`, runtime only `~49%` - - `petite-vue-i18n`: runtime + compiler `~7.48KB`, runtime only `~4.07KB` (production build, brotli compression) - - `vue-i18n`: runtime + compiler `~11.71KB`, runtime only `~8.30KB` (production build, brotli compression) + - Package reduce size: runtime + compiler `~32%`, runtime only `~45%` + - `petite-vue-i18n`: runtime + compiler `~9.61KB`, runtime only `~5.51KB` (production build, brotli compression) + - `vue-i18n`: runtime + compiler `~14.18KB`, runtime only `~10.12KB` (production build, brotli compression) - ES Modules for browser - - Reduce size: runtime + compiler `~35%`, runtime only `~49%` - - `petite-vue-i18n`: runtime + compiler `~7.51KB`, runtime only `~4.09KB` (production build, brotli compression) - - `vue-i18n`: runtime + compiler `~11.73KB`, runtime only `~8.34KB` (production build, brotli compression) - - Bundle size - - Reduce size from `vue-i18n`: runtime + compiler `~14%`, runtime only `~22%` (Code size check measurement of [vue-i18n](https://github.com/intlify/vue-i18n-next/tree/master/packages/size-check-vue-i18n) and [petite-vue-i18n](https://github.com/intlify/vue-i18n-next/tree/master/packages/size-check-petite-vue-i18n)) + - Package reduce size: runtime + compiler `~32%`, runtime only `~45%` + - `petite-vue-i18n`: runtime + compiler `~10.51KB`, runtime only `~6.20KB` (production build, brotli compression) + - `vue-i18n`: runtime + compiler `~15.40KB`, runtime only `~11.12KB` (production build, brotli compression) + - Application bundle size + - Reduce size from `vue-i18n`: `~10%` (Code size check measurement of [vue-i18n](https://github.com/intlify/vue-i18n-next/tree/master/packages/size-check-vue-i18n) and [petite-vue-i18n](https://github.com/intlify/vue-i18n-next/tree/master/packages/size-check-petite-vue-i18n)) - The legacy API is not supported, **only the composition API** - The APIs for the following DateTime Formats, Number Formats, and utilities aren’t included. **Translation only** - `n`, `$n` @@ -33,21 +33,13 @@ Small size subset of Vue I18n - DatetimeFormat `i18n-d` - NumberFormat `i18n-n` -## :hammer: The use case of `petite-vue-i18n` +## 🔨 The use case of `petite-vue-i18n` `vue-i18n` includes various i18n features such as translation, datetimes format and number formats. Some projects may only use translation and not datetime formats. At the moment, even in that case, the code for that feature is included. If your project only uses `t` or `$t` API for translation, so we recommended you would use `petite-vue-i18n` better than `vue-i18n`. And your project needs the features of `vue-i18n`, you can smoothly migrate from `petite-vue-i18n` to `vue-i18n`. This means that it’s progressive enhancement. -## :warning: About the supporting of `petite-vue-i18n` - -Note that `petite-vue-i18n` is still experimental, and you may encounter bugs and unsupported use cases. Proceed at your own risk. - -However, please don’t worry about it. Depending on the usage of `petite-vue-i18n` and the feedback, we would like to use it refer to the development of the next version of `vue-i18n`. This means we will to maintain it. - -We welcome your feedback on `petite-vue-i18n`. - -## :cd: Installation +## 💿 Installation Basically, it’s the same as installing `vue-i18n`. The only difference is that the part of URL or part of path are changed from `vue-i18n` to `petite-vue-i18n`. @@ -83,7 +75,12 @@ app.mount('#app') NPM: ```sh -npm install petite-vue-i18n +npm install petite-vue-i18n --save +``` + +PNPM: +```sh +pnpm add petite-vue-i18n ``` Yarn: @@ -107,7 +104,7 @@ app.use(i18n) app.mount('#app') ``` -## :rocket: Usage +## 🚀 Usages ### Hello world @@ -171,9 +168,11 @@ Note that at this time, only bundlers like vite and webpack are supported. You need to install `@intlify/core-base` to your project with package manager. ```sh -$ npm install --save @intlify/core-base@alpha -# or -# yarn add @intlify/core-base@alpha +npm install --save @intlify/core-base +# for pnpm +# pnpm add @intlify/core-base +# for yarn +# yarn add @intlify/core-base ``` Then, at the entry point of the application, configure the message resolver and locale fallbacker using the API as the below: @@ -200,6 +199,24 @@ registerLocaleFallbacker(fallbackWithLocaleChain) With the above settings, locale message resolving and locale fallbacking will be handled in the same way as in vue-i18n, note that the code size will increase slightly. -## :copyright: License +### Switch without changing import id + +You can switch from vue-i18n to petite-vue-i18n in your application using npm alias without changing the import id. + +package.json: +```diff + { + // ... + "dependencies": { + "vue": "^3.4.14", +- "vue-i18n": "^10.0.0" ++ "vue-i18n": "npm:petite-vue-i18n@^10.0.0" + }, + } +``` + +You need `@intlify/unplugin-vue-i18n` to build your application. + +## ©️ License [MIT](https://opensource.org/licenses/MIT) diff --git a/packages/size-check-petite-vue-i18n/vite.config.ts b/packages/size-check-petite-vue-i18n/vite.config.ts index 0647429df..953c8b3fa 100644 --- a/packages/size-check-petite-vue-i18n/vite.config.ts +++ b/packages/size-check-petite-vue-i18n/vite.config.ts @@ -24,7 +24,8 @@ export default defineConfig({ }, resolve: { alias: { - 'vue-i18n': 'petite-vue-i18n/dist/petite-vue-i18n.esm-bundler.js' + 'vue-i18n': 'petite-vue-i18n/dist/petite-vue-i18n.runtime.esm-bundler.js' + // 'vue-i18n': 'petite-vue-i18n/dist/petite-vue-i18n.esm-bundler.js' } }, build: { diff --git a/packages/size-check-vue-i18n/vite.config.ts b/packages/size-check-vue-i18n/vite.config.ts index 878a6dcd6..0e46c4164 100644 --- a/packages/size-check-vue-i18n/vite.config.ts +++ b/packages/size-check-vue-i18n/vite.config.ts @@ -25,8 +25,8 @@ export default defineConfig({ }, resolve: { alias: { - // 'vue-i18n': 'vue-i18n/dist/vue-i18n.runtime.esm-bundler.js' - 'vue-i18n': 'vue-i18n/dist/vue-i18n.esm-bundler.js' + 'vue-i18n': 'vue-i18n/dist/vue-i18n.runtime.esm-bundler.js' + // 'vue-i18n': 'vue-i18n/dist/vue-i18n.esm-bundler.js' } }, build: { From a8a0f9dbec74603fdc0c94e694b776a457a3083a Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Thu, 23 May 2024 16:51:36 +0900 Subject: [PATCH 2/3] docs: add docs for petite-vue-i18n --- docs/.vitepress/config.mts | 4 + docs/guide/advanced/lite.md | 229 ++++++++++++++++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 docs/guide/advanced/lite.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 1bfd663cf..8ed2be7da 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -177,6 +177,10 @@ function sidebarGuide() { { text: 'Custom Message Format', link: '/guide/advanced/format' + }, + { + text: 'Petite Vue I18n', + link: '/guide/advanced/lite' } ] }, diff --git a/docs/guide/advanced/lite.md b/docs/guide/advanced/lite.md new file mode 100644 index 000000000..c3cbf92c0 --- /dev/null +++ b/docs/guide/advanced/lite.md @@ -0,0 +1,229 @@ +# Small size subset of Vue I18n + +:::warning NOTICE +`petite-vue-i18n` **is not still GA. +It will be GA with the release of Vue I18n v10. +::: + +`petite-vue-i18n` is an alternative distribution of Vue I18n, which provides only minimal features. + +## What is the difference from Vue I18n ? + +- The Size is smaller than vue-i18n + - CDN or without a Bundler + - Package reduce size: runtime + compiler `~32%`, runtime only `~45%` + - `petite-vue-i18n`: runtime + compiler `~9.61KB`, runtime only `~5.51KB` (production build, brotli compression) + - `vue-i18n`: runtime + compiler `~14.18KB`, runtime only `~10.12KB` (production build, brotli compression) + - ES Modules for browser + - Package reduce size: runtime + compiler `~32%`, runtime only `~45%` + - `petite-vue-i18n`: runtime + compiler `~10.51KB`, runtime only `~6.20KB` (production build, brotli compression) + - `vue-i18n`: runtime + compiler `~15.40KB`, runtime only `~11.12KB` (production build, brotli compression) + - Application bundle size + - Reduce size from `vue-i18n`: `~10%` (Code size check measurement of [vue-i18n](https://github.com/intlify/vue-i18n-next/tree/master/packages/size-check-vue-i18n) and [petite-vue-i18n](https://github.com/intlify/vue-i18n-next/tree/master/packages/size-check-petite-vue-i18n)) +- The legacy API is not supported, **only the composition API** +- The APIs for the following DateTime Formats, Number Formats, and utilities aren’t included. **Translation only** + - `n`, `$n` + - `d`, `$d` + - `rt`, `$rt` + - `tm`, `$tm` + - `getDateTimeFormat`, `setDateTimeFormat`, `mergeDateTimeFormat` + - `getNumberFormat`, `setNumberFormat`, `mergeNumberFormat` +- **The only locale messages that can be handled are simple key-values**. if you can handle hierarchical locale messages, you need to customize them using the API +- The algorithm of local fallback is **the array order** specified in `fallbackLocale` +- Custom directive `v-t` isn’t included +- The following components provided by `vue-i18n` aren’t included + - Translation `i18n-t` + - DatetimeFormat `i18n-d` + - NumberFormat `i18n-n` + +## The use case of `petite-vue-i18n` + +`vue-i18n` includes various i18n features such as translation, datetimes format and number formats. Some projects may only use translation and not datetime formats. At the moment, even in that case, the code for that feature is included. + +If your project only uses `t` or `$t` API for translation, so we recommended you would use `petite-vue-i18n` better than `vue-i18n`. And your project needs the features of `vue-i18n`, you can smoothly migrate from `petite-vue-i18n` to `vue-i18n`. This means that it’s progressive enhancement. + +## Installation + +Basically, it’s the same as installing `vue-i18n`. The only difference is that the part of URL or part of path are changed from `vue-i18n` to `petite-vue-i18n`. + +### CDN +You need to insert the following scripts to end of ``: + +```html + + +``` + +The following is the application code with the script tag: + +```html + +``` + +### Package managers + +::: code-group + +```sh [npm] +npm install petite-vue-i18n@next --save +``` + +```sh [yarn] +yarn add petite-vue-i18n@next +``` + +```sh [pnpm] +pnpm add petite-vue-i18n@next +``` +::: + + +```js +import { createApp } from 'vue' +import { createI18n } from 'petite-vue-i18n' + +const i18n = createI18n({ + // something vue-i18n options here ... +}) + +const app = createApp({ + // something vue options here ... +}) + +app.use(i18n) +app.mount('#app') +``` + +## Usages + +### Hello world + +Template: +```html +
+

{{ t('hello world') }}

+
+``` + +Scripts: +```js +const { createApp } = Vue +const { createI18n, useI18n } = PetiteVueI18n +// or for ES modules +// import { createApp } from 'vue' +// import { createI18n } from 'petite-vue-i18n' + +const i18n = createI18n({ + locale: 'en', + messages: { + en: { + 'hello world': 'Hello world!' + }, + ja: { + 'hello world': 'こんにちは、世界！' + } + } +}) + +// define App component +const App = { + setup() { + const { t } = useI18n() + return { t } + } +} + +const app = createApp(App) + +app.use(i18n) +app.mount('#app') +``` + +### Use the same message resolver and locale fallbacker as `vue-i18n` + +In `petite-vue-i18n`, the message resolver and locale fallbacker use simple implementations to optimize code size, as described in the [differences section](https://github.com/intlify/vue-i18n-next/tree/master/packages/petite-vue-i18n#question-what-is-the-difference-from-vue-i18n-), as the belows: + +- message resolver + - Resolves key-value style locale messages + - About implementation, see the [here](https://github.com/intlify/vue-i18n-next/blob/2d4d2a342f8bae134665a0b7cd945fb8b638839a/packages/core-base/src/resolver.ts#L305-L307) +- locale fallbacker + - Fallback according to the array order specified in `fallbackLocale` + - If a simple string locale is specified, fallback to that locale + - About implementation, see the [here](https://github.com/intlify/vue-i18n-next/blob/2d4d2a342f8bae134665a0b7cd945fb8b638839a/packages/core-base/src/fallbacker.ts#L40-L58) + +If you want to use the same message resolver and locale fallbacker as `vue-i18n`, you can change them using the API. + +Note that at this time, only bundlers like vite and webpack are supported. + +You need to install `@intlify/core-base` to your project with package manager. + +::: code-group + +```sh [npm] +npm install --save @intlify/core-base@next +``` + +```sh [yarn] +yarn add @intlify/core-base@next +``` + +```sh [pnpm] +pnpm add @intlify/core-base@next +``` +::: + +Then, at the entry point of the application, configure the message resolver and locale fallbacker using the API as the below: + +```js +import { createApp } from 'vue' +import { createI18n } from 'petite-vue-i18n' +import { + registerMessageResolver, // register the message resolver API + resolveValue, // message resolver of vue-i18n which is used by default + registerLocaleFallbacker, // register the locale fallbacker API + fallbackWithLocaleChain // locale fallbacker of vue-i18n which is used by default +} from '@intlify/core-base' + +// register message resolver of vue-i18n +registerMessageResolver(resolveValue) + +// register locale fallbacker of vue-i18n +registerLocaleFallbacker(fallbackWithLocaleChain) + +// some thing code ... +// ... +``` + +With the above settings, locale message resolving and locale fallbacking will be handled in the same way as in vue-i18n, note that the code size will increase slightly. + +### Switch without changing import id + +You can switch from vue-i18n to petite-vue-i18n in your application using npm alias without changing the import id. + +package.json: +```diff + { + // ... + "dependencies": { + "vue": "^3.4.14", +- "vue-i18n": "^10.0.0" ++ "vue-i18n": "npm:petite-vue-i18n@^10.0.0" + }, + } +``` + +You need `@intlify/unplugin-vue-i18n` to build your application. From 01ae060cfda6b518de5700382db047cce29f28d5 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Thu, 23 May 2024 16:53:47 +0900 Subject: [PATCH 3/3] fix: textlint errors --- .textlintrc.js | 3 ++- packages/petite-vue-i18n/README.md | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.textlintrc.js b/.textlintrc.js index cc626c6e4..66597fd82 100644 --- a/.textlintrc.js +++ b/.textlintrc.js @@ -36,7 +36,8 @@ module.exports = { 'SFC', 'PHP', 'SSR', - 'MIT' + 'MIT', + 'PNPM' ] }, 'abbr-within-parentheses': true, diff --git a/packages/petite-vue-i18n/README.md b/packages/petite-vue-i18n/README.md index da5a049ad..b65e75632 100644 --- a/packages/petite-vue-i18n/README.md +++ b/packages/petite-vue-i18n/README.md @@ -199,11 +199,11 @@ registerLocaleFallbacker(fallbackWithLocaleChain) With the above settings, locale message resolving and locale fallbacking will be handled in the same way as in vue-i18n, note that the code size will increase slightly. -### Switch without changing import id +### Switch without changing import ID -You can switch from vue-i18n to petite-vue-i18n in your application using npm alias without changing the import id. +You can switch from vue-i18n to petite-vue-i18n in your application using npm alias without changing the import ID. -package.json: +Package.json: ```diff { // ...