improvement: exporse type casting API for Legacy mode (#700)

related: #695

Author: kazupon

docs/guide/migration/ways.md

@@ -39,7 +39,7 @@ Include `vue-i18n-bridge` after `vue`, `@vue/composition-api` and it will instal
 <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
 <script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@vue/[email protected]"></script>
-<script src="https://unpkg.com/[email protected].6/dist/vue-i18n-bridge.global.prod.js"></script>
+<script src="https://unpkg.com/[email protected].8/dist/vue-i18n-bridge.global.prod.js"></script>
 ```
 
 ### Usage
@@ -119,6 +119,37 @@ const app = new Vue({ i18n })
 app.$mount('#app')
 ```
 
+for TypeScript:
+```ts
+import Vue from 'vue'
+import VueCompositionAPI from '@vue/composition-api'
+import { createI18n, useI18n, castToVueI18n } from 'vue-i18n-bridge'
+
+Vue.use(VueCompositionAPI)
+Vue.use(VueI18n, { bridge: true })
+
+const i18n = createI18n({
+  locale: 'ja',
+  messages: {
+    en: {
+      message: {
+        hello: 'hello, {name}!'
+      }
+    },
+    ja: {
+      message: {
+        hello: 'こんにちは、{name}！'
+      }
+    }
+  }
+}, VueI18n)
+
+Vue.use(i18n)
+
+const app = new Vue({ i18n: castToVueI18n(i18n) }) // you need to cast `i18n` instance
+app.$mount('#app')
+```
+
 ### Usage UMD module in browser
 
 ```js

jest.config.js

@@ -98,7 +98,9 @@ module.exports = {
   // A map from regular expressions to module names that allow to stub out resources with a single module
   moduleNameMapper: {
     '^@intlify/(.*?)$': '<rootDir>/packages/$1/src',
-    'vue-i18n': '<rootDir>/packages/vue-i18n/src'
+    'vue-i18n': '<rootDir>/packages/vue-i18n/src',
+    'vue-i18n-bridge': '<rootDir>/packages/vue-i18n-bridge/src',
+    'petite-vue-i18n': '<rootDir>/packages/petite-vue-i18n/src'
   },
 
   // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader

packages/vue-i18n-bridge/README.md

@@ -39,7 +39,7 @@ Include `vue-i18n-bridge` after `vue`, `@vue/composition-api` and it will instal
 <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
 <script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@vue/[email protected]"></script>
-<script src="https://unpkg.com/[email protected].5/dist/vue-i18n-bridge.global.prod.js"></script>
+<script src="https://unpkg.com/[email protected].8/dist/vue-i18n-bridge.global.prod.js"></script>
 ```
 
 ## 🚀 Usage
@@ -119,6 +119,37 @@ const app = new Vue({ i18n })
 app.$mount('#app')
 ```
 
+For TypeScript:
+```ts
+import Vue from 'vue'
+import VueCompositionAPI from '@vue/composition-api'
+import { createI18n, useI18n, castToVueI18n } from 'vue-i18n-bridge'
+
+Vue.use(VueCompositionAPI)
+Vue.use(VueI18n, { bridge: true })
+
+const i18n = createI18n({
+  locale: 'ja',
+  messages: {
+    en: {
+      message: {
+        hello: 'hello, {name}!'
+      }
+    },
+    ja: {
+      message: {
+        hello: 'こんにちは、{name}！'
+      }
+    }
+  }
+}, VueI18n)
+
+Vue.use(i18n)
+
+const app = new Vue({ i18n: castToVueI18n(i18n) }) // you need to cast `i18n` instance
+app.$mount('#app')
+```
+
 ### Usage UMD module in browser
 
 ```js

packages/vue-i18n-bridge/src/index.ts

@@ -84,6 +84,7 @@ export {
 export {
   createI18n,
   useI18n,
+  castToVueI18n,
   I18nInjectionKey,
   I18nOptions,
   I18nAdditionalOptions,

packages/vue-i18n-bridge/src/runtime.ts

@@ -79,6 +79,7 @@ export {
 export {
   createI18n,
   useI18n,
+  castToVueI18n,
   I18nInjectionKey,
   I18nOptions,
   I18nAdditionalOptions,

packages/vue-i18n-core/src/i18n.ts

@@ -752,6 +752,29 @@ export function useI18n<
   >
 }
 
+/**
+ * Cast to VueI18n legacy compatible type
+ *
+ * @remarks
+ * This API is provided only with [vue-i18n-bridge](https://vue-i18n.intlify.dev/guide/migration/ways.html#what-is-vue-i18n-bridge).
+ *
+ * The purpose of this function is to convert an {@link I18n} instance created with {@link createI18n | createI18n(legacy: true)} into a `[email protected]` compatible instance of `new VueI18n` in a TypeScript environment.
+ *
+ * @param i18n - An instance of {@link I18n}
+ * @returns A i18n instance which is casted to {@link VueI18n} type
+ *
+ * @VueI18nTip
+ * :new: provided by **vue-i18n-bridge only**
+ *
+ * @VueI18nGeneral
+ */
+export const castToVueI18n = /* #__PURE__*/ (i18n: I18n): VueI18n => {
+  if (!isLegacyVueI18n(i18n)) {
+    throw createI18nError(I18nErrorCodes.NOT_COMPATIBLE_LEGACY_VUE_I18N)
+  }
+  return i18n as unknown as VueI18n
+}
+
 function createGlobal(
   options: I18nOptions,
   legacyMode: boolean,

packages/vue-i18n-core/src/index.ts

@@ -70,6 +70,7 @@ export {
 export {
   createI18n,
   useI18n,
+  castToVueI18n,
   I18nInjectionKey,
   I18nOptions,
   I18nAdditionalOptions,

packages/vue-i18n-core/test/i18n.test.ts

@@ -21,7 +21,7 @@ import {
 } from '@intlify/core-base'
 import { createEmitter } from '@intlify/shared'
 import { mount, pluralRules as _pluralRules } from './helper'
-import { createI18n, useI18n } from '../src/index'
+import { createI18n, useI18n, castToVueI18n } from '../src/i18n'
 import { errorMessages, I18nErrorCodes } from '../src/errors'
 import { Composer } from '../src/composer'
 
@@ -30,6 +30,8 @@ import {
   IntlifyDevToolsHooks
 } from '@intlify/devtools-if'
 
+import type { I18n } from '../src/i18n'
+
 const container = document.createElement('div')
 document.body.appendChild(container)
 
@@ -936,3 +938,25 @@ test('Intlify devtools hooking', () => {
   expect(fnI18nInit).toHaveBeenCalled()
   expect(fnTranslate).toHaveBeenCalled()
 })
+
+describe('castToVueI18n', () => {
+  test('succeeded', () => {
+    const mockVueI18n = {
+      version: '8.2.0'
+    } as unknown as I18n
+    expect(castToVueI18n(mockVueI18n)).toBe(mockVueI18n)
+  })
+
+  test('failed', () => {
+    const mockVueI18n = {} as unknown as I18n
+    let error
+    try {
+      castToVueI18n(mockVueI18n)
+    } catch (e) {
+      error = e.message
+    }
+    expect(error).toEqual(
+      errorMessages[I18nErrorCodes.NOT_COMPATIBLE_LEGACY_VUE_I18N]
+    )
+  })
+})