From df59c4d3c834f9a0322a938402bd10608a8ea3d7 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Thu, 5 Dec 2024 19:12:06 +0900 Subject: [PATCH] feat!: deprecate `v-t` custom directive --- docs/.vitepress/config.mts | 8 ++++---- docs/guide/advanced/directive.md | 4 ++++ docs/guide/migration/breaking11.md | 19 ++++++++++++++++++ packages/vue-i18n-core/src/directive.ts | 26 ++++++++++++++++++++----- packages/vue-i18n-core/src/warnings.ts | 12 ++++++++++-- 5 files changed, 58 insertions(+), 11 deletions(-) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 56359fda1..db7effa5b 100644 --- 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 index fff768885..6cc562743 100644 --- 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 index 5400020b0..7f7b015c3 100644 --- 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 index 45fcdaa2e..0f346f09d 100644 --- 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 = ObjectDirective +/** + * @deprecated will be removed at vue-i18n v12 + */ export function vTDirective(i18n: I18n): TranslationDirective { + 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 index 70388d4d1..5cea1f658 100644 --- 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(