feat!: deprecate v-t custom directive (#2045)

kazupon · web-flow · commit 959f271f302c · 2024-12-06T14:34:38.000+09:00
* feat!: deprecate `v-t` custom directive

* fix: e2e
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -195,16 +195,16 @@ function sidebarGuide() {
       collapsible: true,
       items: [
         {
-          text: 'Breaking Changes in v9',
-          link: '/guide/migration/breaking'
+          text: 'Breaking Changes in v11',
+          link: '/guide/migration/breaking11'
         },
         {
           text: 'Breaking Changes in v10',
           link: '/guide/migration/breaking10'
         },
         {
-          text: 'Breaking Changes in v11',
-          link: '/guide/migration/breaking11'
+          text: 'Breaking Changes in v9',
+          link: '/guide/migration/breaking'
         },
         {
           text: 'New Features in v9',
diff --git a/docs/guide/advanced/directive.md b/docs/guide/advanced/directive.md
@@ -1,5 +1,9 @@
 # Custom Directive
 
+:::danger NOTE
+`v-t` will be deprecated at v11, and will be dropped at v12. This section is for those who are still using v10.
+:::
+
 You can translate not only with `$t`, but also with the `v-t` custom directive.
 
 ## String syntax
diff --git a/docs/guide/migration/breaking11.md b/docs/guide/migration/breaking11.md
@@ -1,5 +1,9 @@
 # Breaking Changes in v11
 
+:::warning NOTICE
+Vue I18n v11 is still beta
+:::
+
 ## Deprecate Legacy API mode
 
 ### Reason
@@ -13,6 +17,21 @@ Legacy API mode will be deprecated in v11, as previous vue-i18n releases have al
 
 For compatibility, Legacy API mode still works in v11, but will be removed entirely in v12, so Legacy API mode will not work after that version.
 
+## Deprecate Custom Directive `v-t`
+
+### Reason
+
+The advantage of `v-t` was that it could optimize performance using the vue compiler transform and the pre-translation of `vue-i18n-extension`.
+
+This feature was supported from Vue 2.
+About details see the blog article: https://medium.com/@kazu_pon/performance-optimization-of-vue-i18n-83099eb45c2d
+
+In Vue 3, due to the Composition API, the pre-translation of `vue-i18n-extension` is now limited only for global scope.
+
+In addition, Vue 3 Virtual DOM optimization has been introduced, and the optimization provided by `vue-i18n-extension` is no longer very effective. We need to require settings for SSR, the benefits of using `v-t` have disappeared. And DX of templates using `v-t` is not good. Custom directives do not work with key completion in editors (e.g. vscode).
+
+For compatibility, `v-t` mode still works in v11, but will be removed entirely in v12, so `v-t` will not work after that version.
+
 ## Drop `tc` and `$tc` for Legacy API mode
 
 **Reason**: These APIs had already deprecated in warning about being dropped in v11. docs says, https://vue-i18n.intlify.dev/guide/migration/breaking10.html#deprecate-tc-and-tc-for-legacy-api-mode
diff --git a/e2e/fallback/basic.spec.ts b/e2e/fallback/basic.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/e2e/fallback/default-format.spec.ts b/e2e/fallback/default-format.spec.ts
@@ -5,7 +5,13 @@ import { getText, url } from '../helper'
     beforeAll(async () => {
       page.on('console', msg => {
         if (msg.type() === 'warning') {
-          warnings.push(msg.text())
+          const text = msg.text()
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
+            warnings.push(msg.text())
+          }
         }
       })
       await page.goto(url(`/examples/${pattern}/fallback/default-format.html`))
diff --git a/e2e/fallback/format.spec.ts b/e2e/fallback/format.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/e2e/fallback/option.spec.ts b/e2e/fallback/option.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/e2e/fallback/suppress.spec.ts b/e2e/fallback/suppress.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/e2e/missing/handler.spec.ts b/e2e/missing/handler.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/e2e/missing/option.spec.ts b/e2e/missing/option.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/e2e/missing/suppress.spec.ts b/e2e/missing/suppress.spec.ts
@@ -6,7 +6,10 @@ import { getText, url } from '../helper'
       page.on('console', msg => {
         if (msg.type() === 'warning') {
           const text = msg.text()
-          if (!text.match(/^\[intlify\] Legacy API mode has been/)) {
+          if (
+            !text.match(/^\[intlify\] Legacy API mode has been/) &&
+            !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)
+          ) {
             warnings.push(msg.text())
           }
         }
diff --git a/packages/vue-i18n-core/src/directive.ts b/packages/vue-i18n-core/src/directive.ts
@@ -1,17 +1,24 @@
+import {
+  inBrowser,
+  isNumber,
+  isPlainObject,
+  isString,
+  warnOnce
+} from '@intlify/shared'
 import { watch } from 'vue'
 import { createI18nError, I18nErrorCodes } from './errors'
-import { isString, isPlainObject, isNumber, inBrowser } from '@intlify/shared'
+import { getWarnMessage, I18nWarnCodes } from './warnings'
 
+import type { Locale, NamedValue, TranslateOptions } from '@intlify/core-base'
 import type {
+  ComponentInternalInstance,
   DirectiveBinding,
   ObjectDirective,
-  WatchStopHandle,
-  ComponentInternalInstance
+  WatchStopHandle
 } from 'vue'
+import type { Composer } from './composer'
 import type { I18n, I18nInternal } from './i18n'
 import type { VueI18nInternal } from './legacy'
-import type { Composer } from './composer'
-import type { Locale, TranslateOptions, NamedValue } from '@intlify/core-base'
 
 export type VTDirectiveValue = {
   path: string
@@ -80,7 +87,16 @@ function getComposer(
  */
 export type TranslationDirective<T = HTMLElement> = ObjectDirective<T>
 
+/**
+ * @deprecated will be removed at vue-i18n v12
+ */
 export function vTDirective(i18n: I18n): TranslationDirective<HTMLElement> {
+  if (__DEV__) {
+    warnOnce(
+      getWarnMessage(I18nWarnCodes.DEPRECATE_TRANSLATE_CUSTOME_DIRECTIVE)
+    )
+  }
+
   const _process = (binding: DirectiveBinding): [string, Composer] => {
     const { instance, value } = binding
     /* istanbul ignore if */
diff --git a/packages/vue-i18n-core/src/warnings.ts b/packages/vue-i18n-core/src/warnings.ts
@@ -8,7 +8,11 @@ export const I18nWarnCodes = {
   /**
    * @deprecated will be removed at vue-i18n v12
    */
-  DEPRECATE_LEGACY_MODE: 11
+  DEPRECATE_LEGACY_MODE: 11,
+  /**
+   * @deprecated will be removed at vue-i18n v12
+   */
+  DEPRECATE_TRANSLATE_CUSTOME_DIRECTIVE: 12
 } as const
 
 type I18nWarnCodes = (typeof I18nWarnCodes)[keyof typeof I18nWarnCodes]
@@ -20,7 +24,11 @@ export const warnMessages: { [code: number]: string } = {
   /**
    * @deprecated will be removed at vue-i18n v12
    */
-  [I18nWarnCodes.DEPRECATE_LEGACY_MODE]: `Legacy API mode has been deprecated in v11. Use Composition API mode instead.\nAbout how to use the Composition API mode, see https://vue-i18n.intlify.dev/guide/advanced/composition.html`
+  [I18nWarnCodes.DEPRECATE_LEGACY_MODE]: `Legacy API mode has been deprecated in v11. Use Composition API mode instead.\nAbout how to use the Composition API mode, see https://vue-i18n.intlify.dev/guide/advanced/composition.html`,
+  /**
+   * @deprecated will be removed at vue-i18n v12
+   */
+  [I18nWarnCodes.DEPRECATE_TRANSLATE_CUSTOME_DIRECTIVE]: `'v-t' has been deprecated in v11. Use translate APIs ('t' or '$t') instead.`
 }
 
 export function getWarnMessage(

Original file line number	Diff line number	Diff line change
`@@ -195,16 +195,16 @@ function sidebarGuide() {`
`195`	`195`	`collapsible: true,`
`196`	`196`	`items: [`
`197`	`197`	`{`
`198`		`- text: 'Breaking Changes in v9',`
`199`		`- link: '/guide/migration/breaking'`
	`198`	`+ text: 'Breaking Changes in v11',`
	`199`	`+ link: '/guide/migration/breaking11'`
`200`	`200`	`},`
`201`	`201`	`{`
`202`	`202`	`text: 'Breaking Changes in v10',`
`203`	`203`	`link: '/guide/migration/breaking10'`
`204`	`204`	`},`
`205`	`205`	`{`
`206`		`- text: 'Breaking Changes in v11',`
`207`		`- link: '/guide/migration/breaking11'`
	`206`	`+ text: 'Breaking Changes in v9',`
	`207`	`+ link: '/guide/migration/breaking'`
`208`	`208`	`},`
`209`	`209`	`{`
`210`	`210`	`text: 'New Features in v9',`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,10 @@ import { getText, url } from '../helper'`
`6`	`6`	`page.on('console', msg => {`
`7`	`7`	`if (msg.type() === 'warning') {`
`8`	`8`	`const text = msg.text()`
`9`		`- if (!text.match(/^\[intlify\] Legacy API mode has been/)) {`
	`9`	`+ if (`
	`10`	`+ !text.match(/^\[intlify\] Legacy API mode has been/) &&`
	`11`	`+ !text.match(/^\[intlify\] 'v-t' has been deprecated in v11/)`
	`12`	`+ ) {`
`10`	`13`	`warnings.push(msg.text())`
`11`	`14`	`}`
`12`	`15`	`}`