feat!: deprecate v-t custom directive

intlify · Dec 5, 2024 · df59c4d · df59c4d
1 parent 404831b
commit df59c4d
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 11 deletions.
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/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(