From 3c03b1c362fbdbe7f0a3b06bcedb91a32f0b736a Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Mon, 15 Apr 2024 17:41:58 +0900 Subject: [PATCH 1/3] docs: improve documentation --- docs/.vitepress/config.mts | 27 ++-- docs/.vitepress/theme/styles/global.css | 16 +++ .../guide/{index.md => essentials/started.md} | 4 +- docs/guide/extra/dist.md | 63 +++++++++ docs/guide/{ => extra}/roadmap.md | 0 docs/guide/extra/v8-docs.md | 22 +++ docs/guide/installation.md | 129 ++++-------------- docs/guide/introduction.md | 2 +- 8 files changed, 144 insertions(+), 119 deletions(-) rename docs/guide/{index.md => essentials/started.md} (89%) create mode 100644 docs/guide/extra/dist.md rename docs/guide/{ => extra}/roadmap.md (100%) create mode 100644 docs/guide/extra/v8-docs.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 71fd18d74..1e3de5b91 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -67,7 +67,7 @@ function nav() { }, { text: 'Roadmap', - link: '/guide/roadmap' + link: '/guide/extra/roadmap' }, { text: 'v9.x', @@ -90,17 +90,9 @@ function sidebarGuide() { text: 'What is Vue I18n?', link: '/guide/introduction' }, - { - text: 'Getting Started', - link: '/guide/' - }, { text: 'Installation', link: '/guide/installation' - }, - { - text: 'Roadmap', - link: '/guide/roadmap' } ] }, @@ -108,6 +100,10 @@ function sidebarGuide() { text: 'Essentials', collapsible: true, items: [ + { + text: 'Getting Started', + link: '/guide/essentials/started', + }, { text: 'Message Format Syntax', link: '/guide/essentials/syntax' @@ -217,13 +213,20 @@ function sidebarGuide() { ] }, { - text: 'v8.x', + text: 'Extra Topics', collapsible: true, - collapsed: true, items: [ + { + text: 'Different Distribution files', + link: '/guide/extra/dist' + }, { text: 'Documentation for v8.x', - link: '/guide/v8-docs' + link: '/guide/extra/v8-docs' + }, + { + text: 'Roadmap', + link: '/guide/extra/roadmap' } ] } diff --git a/docs/.vitepress/theme/styles/global.css b/docs/.vitepress/theme/styles/global.css index 6516422db..8e4b7f7a6 100644 --- a/docs/.vitepress/theme/styles/global.css +++ b/docs/.vitepress/theme/styles/global.css @@ -1,10 +1,26 @@ :root { + --vp-c-brand-1: var(--vp-c-green-1); + --vp-c-brand-2: var(--vp-c-green-2); + --vp-c-brand-3: var(--vp-c-green-3); + --vp-c-brand-soft: var(--vp-c-green-soft); + --vp-code-color: #476582; --vp-home-hero-name-color: transparent; --vp-home-hero-image-filter: blur(72px); --vp-home-hero-image-background-image: linear-gradient( -45deg, #647eff 30%, #42d392 ); --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #647eff, #42d392); } +:root.dark { + --vp-code-color: #c9def1; + + --vp-home-hero-image-filter: blur(72px); + --vp-home-hero-image-background-image: linear-gradient( + 0deg, + var(--vp-c-brand-soft) 50%, + var(--vp-c-brand-soft) 50% + ); +} + .vp-sponsor-grid.xmini .vp-sponsor-grid-link { height: 64px; } .vp-sponsor-grid.xmini .vp-sponsor-grid-image { max-width: 64px; max-height: 22px } diff --git a/docs/guide/index.md b/docs/guide/essentials/started.md similarity index 89% rename from docs/guide/index.md rename to docs/guide/essentials/started.md index b7d4e9830..bb3cb923b 100644 --- a/docs/guide/index.md +++ b/docs/guide/essentials/started.md @@ -1,9 +1,7 @@ # Getting started :::tip NOTE -We will be using [ES6](https://github.com/lukehoban/es6features) in the code samples in the guide. - -Also, all examples will be using the full version of Vue to make on-the-fly template compilation possible. See more details [here](https://v3.vuejs.org/guide/installation.html#runtime-compiler-vs-runtime-only). +This guide will assume that you are already familiar with Vue itself. You don't need to be a Vue expert, but you may occasionally need to refer back to the [core Vue documentation](https://vuejs.org/) for more information about certain features. ::: Creating a global application with Vue + Vue I18n is dead simple. With Vue.js, we are already composing our application with components. When adding Vue I18n to the mix, all we need to do is ready resource messages and simply use the localization API that are offered with Vue I18n. diff --git a/docs/guide/extra/dist.md b/docs/guide/extra/dist.md new file mode 100644 index 000000000..7b2231e31 --- /dev/null +++ b/docs/guide/extra/dist.md @@ -0,0 +1,63 @@ +# Different Distribution files +In the [dist/ directory of the npm package](https://cdn.jsdelivr.net/npm/vue-i18n@9.1.10/dist/) you will find many different builds of Vue I18n. Here is an overview of which dist file should be used depending on the use-case. + +## From CDN or without a Bundler + +- **`vue-i18n(.runtime).global(.prod).js`**: + - For direct use via ` - -``` - -You can also use a specific version/tag via URLs like - -### ES Modules import - -```html - + ``` +You can also use a specific version/tag via URLs like -## Explanation of Different Builds -In the [dist/ directory of the npm package](https://cdn.jsdelivr.net/npm/vue-i18n@9.1.10/dist/) you will find many different builds of Vue I18n. Here is an overview of which dist file should be used depending on the use-case. - -### From CDN or without a Bundler - -- **`vue-i18n(.runtime).global(.prod).js`**: - - For direct use via ` + + ``` the above codes, by specifying the defined schema as the first type parameter of `useI18n`, you can use TypeScript to check for undefined resources for locale messages and number formats. Also, by specifying the locale to be defined in the second type parameter, TypeScript can check for undefined locales. @@ -186,6 +183,7 @@ Use-cases on your project, you may have Vue components that do not use local sco For that use case, you can also support interpolation of resource keys by explicitly specifying the schema defined for the global scope in the type parameter of `useI18n`. define schema for global scope: + ```ts /** * define the resource schema @@ -207,29 +205,24 @@ export type NumberSchema = { ``` Then, just import the defined schema and use it as a type parameter of `useI18n`, as in the following Vue component: -```html - +```vue + + + ``` As a result, you can use the interpolation of resource keys in the APIs provided by VueI18n, such as `t` and `n`. @@ -256,6 +249,7 @@ VueI18n provides the following interfaces: With using these interfaces and the `declare module`, you can define a global schema for VueI18n. The following is an example of a global schema defined in `d.ts`: + ```ts /** * you need to import the some interfaces @@ -304,6 +298,7 @@ Previously, when using `createI18n` and `useI18n` with type definitions for glob This way, you don't need to do that. The following is an example with `createI18n`: + ```ts import { createI18n, type I18nOptions } from 'vue-i18n' @@ -356,28 +351,22 @@ The first type parameter of `createI18n` above does not specify the type that is The second type parameter of `createI18n` specifies a type hint for options. In the case of the `useI18n` case used by Vue components, it looks like this: -```html - - + + ``` As you can see from the above code, you don't need to specify anything for the type parameter of `useI18n`. You can interpolate API Resource Keys such as `t`, `d`, and `n` without specifying them. diff --git a/docs/guide/advanced/wc.md b/docs/guide/advanced/wc.md index 9aaccc161..26af7708a 100644 --- a/docs/guide/advanced/wc.md +++ b/docs/guide/advanced/wc.md @@ -21,9 +21,10 @@ Using `defineCustomElement`, which is supported since Vue 3.2, we can provide Vu However, the provided Web Components cannot be inserted directly into HTML. You need to prepare the following Web Components to host the i18n instance created by `createI18n`. Web Components that host the i18n instance: -```html - @@ -79,7 +71,7 @@ Then, to host other Web Components, the `template` block makes it possible by us Export this hosted Web Components as follows: -```javascript +```js import { defineCustomElement } from 'vue' import I18nHost from './components/I18nHost.ce.vue' @@ -90,7 +82,7 @@ export { I18nHostElement } The following `useI18n` implements and exports Web Components to: -```html +```vue + - - ``` ## DatetimeFormat Component diff --git a/docs/guide/migration/vue2.md b/docs/guide/migration/vue2.md index e98a53af5..001af6423 100644 --- a/docs/guide/migration/vue2.md +++ b/docs/guide/migration/vue2.md @@ -2,6 +2,10 @@ ## `vue-i18n-bridge` +:::danger NOTE +vue-i18n-bridge will not be provided in v10 due to Vue 2 EOL. v9.x will be the last version. +::: + ### What is `vue-i18n-bridge`? `vue-i18n-bridge` is a bridge to make the upgrade as easy as possible between vue-i18n@v8.26.1 or later and vue-i18n@v9.x. @@ -17,15 +21,23 @@ And, also some features are backported from vue-i18n@v9.x: #### Package manager -```sh -# npm +::: code-group + +```sh [npm] npm install vue-i18n-bridge -# yarn +``` + +```sh [yarn] yarn add vue-i18n-bridge -# pnpm +``` + +```sh [pnpm] pnpm add vue-i18n-bridge ``` +::: + + You must install the below packages before using this library: - vue-i18n: >= v8.26.1 < v9 diff --git a/examples/type-safe/global-type-definition/src/App.vue b/examples/type-safe/global-type-definition/src/App.vue index 00a694468..4c5cd7824 100644 --- a/examples/type-safe/global-type-definition/src/App.vue +++ b/examples/type-safe/global-type-definition/src/App.vue @@ -1,19 +1,11 @@ + + - -