docs: API reference for multi version preparation (#2059)

* docs: API reference for mutlti version preparation

* docs: prepare v12 api refenrece

* chore: npm script

Author: kazupon

Diff for: .gitignore

@@ -1,6 +1,6 @@
 dist
-docs/api/*.md
-!docs/api/injection.md
+docs/api/v11/*.md
+!docs/api/v11/injection.md
 packages/vue-i18n/index.html
 temp
 coverage

Diff for: docs/.vitepress/config.mts

@@ -46,6 +46,8 @@ export default defineConfig({
     sidebar: {
       '/guide/': sidebarGuide(),
       '/api/': sidebarApi(),
+      // NOTE: if we need to support multiple versions, we can be enble the following sidebar items
+      // '/api/v11/': sidebarApi('v11/'),
       '/ecosystem/': sidebarEcosystem()
     }
   }
@@ -59,7 +61,9 @@ function nav() {
     },
     {
       text: 'API',
-      link: '/api/general'
+      link: '/api/general',
+      // NOTE: if we need to support multiple versions, we can be enble the following navigation items
+      // items: [{ text: 'latest', link: '/api/general' }, { text: 'v9 ~ v11', link: '/api/v11/general' }]
     },
     {
       text: 'Ecosystem',
@@ -241,34 +245,34 @@ function sidebarGuide() {
   ]
 }
 
-function sidebarApi() {
+function sidebarApi(ns = '') {
   return [
     {
       text: 'API Reference',
       items: [
         {
           text: 'General',
-          link: '/api/general'
+          link: `/api/${ns}general`
         },
         {
           text: 'Legacy API',
-          link: '/api/legacy'
+          link: `/api/${ns}legacy`
         },
         {
           text: 'Composition API',
-          link: '/api/composition'
+          link: `/api/${ns}composition`
         },
         {
           text: 'Components',
-          link: '/api/component'
+          link: `/api/${ns}component`
         },
         {
           text: 'Directives',
-          link: '/api/directive'
+          link: `/api/${ns}directive`
         },
         {
           text: 'Component Injections',
-          link: '/api/injection'
+          link: `/api/${ns}injection`
         }
       ]
     }

Diff for: docs/api/component.md

@@ -0,0 +1,279 @@
+# Components
+
+## BaseFormatProps
+
+BaseFormat Props for Components that is offered Vue I18n
+
+**Signature:**
+```typescript
+export interface BaseFormatProps 
+```
+
+**Details**
+
+The interface definitions of the underlying props of components such as Translation, DatetimeFormat, and NumberFormat.
+
+### i18n
+
+**Signature:**
+```typescript
+i18n?: Composer;
+```
+
+**Details**
+
+A composer instance with an existing scope.
+
+This option takes precedence over the `scope` option.
+
+### locale
+
+**Signature:**
+```typescript
+locale?: Locale;
+```
+
+**Details**
+
+Specifies the locale to be used for the component.
+
+If specified, the global scope or the locale of the parent scope of the target component will not be overridden and the specified locale will be used.
+
+### scope
+
+**Signature:**
+```typescript
+scope?: ComponentI18nScope;
+```
+
+**Details**
+
+Specifies the scope to be used in the target component.
+
+You can specify either `global` or `parent`.
+
+If `global` is specified, global scope is used, else then `parent` is specified, the scope of the parent of the target component is used.
+
+If the parent is a global scope, the global scope is used, if it's a local scope, the local scope is used.
+
+### tag
+
+**Signature:**
+```typescript
+tag?: string | object;
+```
+
+**Details**
+
+Used to wrap the content that is distribute in the slot. If omitted, the slot content is treated as Fragments.
+
+You can specify a string-based tag name, such as `p`, or the object for which the component is defined.
+
+## DatetimeFormat
+
+Datetime Format Component
+
+**Signature:**
+```typescript
+DatetimeFormat: {
+    new (): {
+        $props: VNodeProps & DatetimeFormatProps & BaseFormatProps;
+    };
+}
+```
+
+**Details**
+
+See the following items for property about details
+
+:::danger
+Not supported IE, due to no support `Intl.DateTimeFormat#formatToParts` in [IE](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts)
+
+If you want to use it, you need to use [polyfill](https://github.com/formatjs/formatjs/tree/main/packages/intl-datetimeformat)
+:::
+
+**See Also**
+- [FormattableProps](component#formattableprops)
+- [BaseFormatProps](component#baseformatprops)
+- [Custom Formatting](../guide/essentials/datetime#custom-formatting)
+
+## DatetimeFormatProps
+
+DatetimeFormat Component Props
+
+**Signature:**
+```typescript
+export type DatetimeFormatProps = FormattableProps<number | Date, Intl.DateTimeFormatOptions>;
+```
+
+## FormattableProps
+
+Formattable Props
+
+**Signature:**
+```typescript
+export interface FormattableProps<Value, Format> extends BaseFormatProps 
+```
+
+**Details**
+
+The props used in DatetimeFormat, or NumberFormat component
+
+### format
+
+**Signature:**
+```typescript
+format?: string | Format;
+```
+
+**Details**
+
+The format to use in the target component.
+
+Specify the format key string or the format as defined by the Intl API in ECMA 402.
+
+### value
+
+**Signature:**
+```typescript
+value: Value;
+```
+
+**Details**
+
+The value specified for the target component
+
+## NumberFormat
+
+Number Format Component
+
+**Signature:**
+```typescript
+NumberFormat: {
+    new (): {
+        $props: VNodeProps & NumberFormatProps & BaseFormatProps;
+    };
+}
+```
+
+**Details**
+
+See the following items for property about details
+
+:::danger
+Not supported IE, due to no support `Intl.NumberFormat#formatToParts` in [IE](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatToParts)
+
+If you want to use it, you need to use [polyfill](https://github.com/formatjs/formatjs/tree/main/packages/intl-numberformat)
+:::
+
+**See Also**
+- [FormattableProps](component#formattableprops)
+- [BaseFormatProps](component#baseformatprops)
+- [Custom Formatting](../guide/essentials/number#custom-formatting)
+
+## NumberFormatProps
+
+NumberFormat Component Props
+
+**Signature:**
+```typescript
+export type NumberFormatProps = FormattableProps<number, Intl.NumberFormatOptions>;
+```
+
+## Translation
+
+Translation Component
+
+**Signature:**
+```typescript
+Translation: {
+    new (): {
+        $props: VNodeProps & TranslationProps;
+    };
+}
+```
+
+**Details**
+
+See the following items for property about details
+
+**See Also**
+- [TranslationProps](component#translationprops)
+- [BaseFormatProps](component#baseformatprops)
+- [Component Interpolation](../guide/advanced/component)
+
+**Examples**
+
+
+```html
+<div id="app">
+  <!-- ... -->
+  <i18n keypath="term" tag="label" for="tos">
+    <a :href="url" target="_blank">{{ $t('tos') }}</a>
+  </i18n>
+  <!-- ... -->
+</div>
+```
+
+
+```js
+import { createApp } from 'vue'
+import { createI18n } from 'vue-i18n'
+
+const messages = {
+  en: {
+    tos: 'Term of Service',
+    term: 'I accept xxx {0}.'
+  },
+  ja: {
+    tos: '利用規約',
+    term: '私は xxx の{0}に同意します。'
+  }
+}
+
+const i18n = createI18n({
+  locale: 'en',
+  messages
+})
+
+const app = createApp({
+  data: {
+    url: '/term'
+  }
+}).use(i18n).mount('#app')
+```
+
+
+
+
+## TranslationProps
+
+Translation Component Props
+
+**Signature:**
+```typescript
+export interface TranslationProps extends BaseFormatProps 
+```
+
+### keypath
+
+**Signature:**
+```typescript
+keypath: string;
+```
+
+**Details**
+
+The locale message key can be specified prop
+
+### plural
+
+**Signature:**
+```typescript
+plural?: number | string;
+```
+
+**Details**
+
+The Plural Choosing the message number prop
+