@intlify/unplugin-vue-i18n 11.0.7 → 11.1.0

package/lib/index.mjs

@@ -37,6 +37,11 @@ function resolveOptions(options) {
   const optimizeTranslationDirective = isString(options.optimizeTranslationDirective) || isArray(options.optimizeTranslationDirective) ? options.optimizeTranslationDirective : !!options.optimizeTranslationDirective;
   const translationIdentifiers = /* @__PURE__ */ new Map();
   const transformI18nBlock = typeof options.transformI18nBlock === "function" ? options.transformI18nBlock : null;
+  const treeShaking = options.treeShaking ? typeof options.treeShaking === "object" ? {
+    safelist: options.treeShaking.safelist || [],
+    dynamicKeyStrategy: options.treeShaking.dynamicKeyStrategy || "keep-all",
+    scanPatterns: options.treeShaking.scanPatterns
+  } : { safelist: [], dynamicKeyStrategy: "keep-all" } : null;
   return {
     include: normalizeGlobOption(options.include || []),
     exclude: normalizeGlobOption(options.exclude),
@@ -55,7 +60,8 @@ function resolveOptions(options) {
     escapeHtml,
     optimizeTranslationDirective,
     translationIdentifiers,
-    transformI18nBlock
+    transformI18nBlock,
+    treeShaking
   };
 }
 
@@ -167,7 +173,7 @@ const RE_VIRTUAL_PREFIXED_INTLIFY_BUNDLE_IMPORT_ID = new RegExp(
 const RE_RESOURCE_FORMAT = /\.(json5?|ya?ml|[c|m]?[j|t]s)$/;
 const RE_SFC_I18N_CUSTOM_BLOCK = /\?vue&type=i18n/;
 const RE_SFC_I18N_WEBPACK_CUSTOM_BLOCK = /blockType=i18n/;
-const debug$2 = createDebug(resolveNamespace("resource"));
+const debug$3 = createDebug(resolveNamespace("resource"));
 function resourcePlugin({
   onlyLocales,
   include,
@@ -185,7 +191,7 @@ function resourcePlugin({
   allowDynamic,
   escapeHtml,
   transformI18nBlock
-}, meta) {
+}, meta, collector) {
   let viteModule = null;
   async function getViteModule() {
     if (viteModule != null) {
@@ -213,15 +219,15 @@ function resourcePlugin({
       return _filter;
     }
     if (meta.framework == "webpack") {
-      debug$2("Using filter for webpack");
+      debug$3("Using filter for webpack");
       _filter = createFilter(...resolveIncludeExclude());
     } else {
       const viteModule2 = await getViteModule();
       if (viteModule2.rolldownVersion) {
-        debug$2("Using filter for rolldown-vite");
+        debug$3("Using filter for rolldown-vite");
         _filter = createFilter(...resolveIncludeExclude());
       } else {
-        debug$2("Using filter for rollup-vite");
+        debug$3("Using filter for rollup-vite");
         _filter = createFilter(...resolveIncludeExcludeForLegacy());
       }
     }
@@ -233,7 +239,7 @@ function resourcePlugin({
   let isProduction = false;
   let sourceMap = false;
   const vueI18nAliasName = module;
-  debug$2(`vue-i18n alias name: ${vueI18nAliasName}`);
+  debug$3(`vue-i18n alias name: ${vueI18nAliasName}`);
   let vuePlugin = null;
   const getSfcParser = () => {
     return vuePlugin ? getVueCompiler(vuePlugin).parse : parse$1;
@@ -259,7 +265,7 @@ function resourcePlugin({
             __VUE_I18N_PROD_DEVTOOLS__: false
           }
         };
-        debug$2("define Config:", defineConfig);
+        debug$3("define Config:", defineConfig);
         const aliasConfig = {
           resolve: {
             alias: {
@@ -270,7 +276,7 @@ function resourcePlugin({
             }
           }
         };
-        debug$2("alias Config:", aliasConfig);
+        debug$3("alias Config:", aliasConfig);
         return assign(defineConfig, aliasConfig);
       },
       async configResolved(config) {
@@ -280,9 +286,9 @@ function resourcePlugin({
         }
         isProduction = config.isProduction;
         sourceMap = config.command === "build" ? !!config.build.sourcemap : false;
-        debug$2(`configResolved: isProduction = ${isProduction}, sourceMap = ${sourceMap}`);
+        debug$3(`configResolved: isProduction = ${isProduction}, sourceMap = ${sourceMap}`);
         const isRolldownVite = !!(await getViteModule()).rolldownVersion;
-        debug$2(`Using ${isRolldownVite ? "rolldown-vite" : "vite"} for the build`);
+        debug$3(`Using ${isRolldownVite ? "rolldown-vite" : "vite"} for the build`);
         if (!isRolldownVite) {
           const jsonPlugin = getVitePlugin(config, "vite:json");
           if (jsonPlugin) {
@@ -296,7 +302,7 @@ function resourcePlugin({
               if (query.vue) {
                 return;
               }
-              debug$2("org json plugin");
+              debug$3("org json plugin");
               return orgTransform.apply(this, [code, id]);
             }
             jsonPlugin.transform = overrideJson;
@@ -321,7 +327,7 @@ function resourcePlugin({
     webpack(compiler) {
       isProduction = compiler.options.mode !== "development";
       sourceMap = !!compiler.options.devtool;
-      debug$2(`webpack: isProduction = ${isProduction}, sourceMap = ${sourceMap}`);
+      debug$3(`webpack: isProduction = ${isProduction}, sourceMap = ${sourceMap}`);
       compiler.options.resolve = normalizeConfigResolveAlias(
         compiler.options.resolve,
         meta.framework
@@ -330,7 +336,7 @@ function resourcePlugin({
         ssr: ssrBuild,
         runtimeOnly
       });
-      debug$2(
+      debug$3(
         `set ${vueI18nAliasName}: ${getVueI18nAliasPath({
           ssr: ssrBuild,
           runtimeOnly
@@ -343,15 +349,15 @@ function resourcePlugin({
           __INTLIFY_PROD_DEVTOOLS__: "false"
         })
       );
-      debug$2(`set __VUE_I18N_LEGACY_API__ is '${compositionOnly}'`);
-      debug$2(`set __VUE_I18N_FULL_INSTALL__ is '${fullInstall}'`);
+      debug$3(`set __VUE_I18N_LEGACY_API__ is '${compositionOnly}'`);
+      debug$3(`set __VUE_I18N_FULL_INSTALL__ is '${fullInstall}'`);
       const filter = createFilter(...resolveIncludeExclude());
       if (compiler.options.module) {
         compiler.options.module.rules.push({
           test: RE_RESOURCE_FORMAT,
           type: "javascript/auto",
           include(resource) {
-            debug$2("webpack resource include", resource);
+            debug$3("webpack resource include", resource);
             return filter(resource);
           }
         });
@@ -370,7 +376,7 @@ function resourcePlugin({
         id: RE_VIRTUAL_PREFIXED_INTLIFY_BUNDLE_IMPORT_ID
       },
       async handler(id) {
-        debug$2("load", id);
+        debug$3("load", id);
         if (INTLIFY_BUNDLE_IMPORT_ID === getVirtualId(id, meta.framework) && include) {
           let resourcePaths = [];
           for (const inc of include) {
@@ -380,7 +386,8 @@ function resourcePlugin({
           const code = await generateBundleResources(resourcePaths, isProduction, {
             forceStringify,
             strictMessage,
-            escapeHtml
+            escapeHtml,
+            usedKeyFilter: collector ? (keyPath) => collector.shouldKeepKey(keyPath) : void 0
           });
           return {
             moduleType: "js",
@@ -397,7 +404,7 @@ function resourcePlugin({
           return;
         }
         const { filename, query } = parseVueRequest(id);
-        debug$2("transform", id, JSON.stringify(query), filename);
+        debug$3("transform", id, JSON.stringify(query), filename);
         let langInfo = defaultSFCLang;
         let inSourceMap;
         if (!query.vue) {
@@ -416,13 +423,14 @@ function resourcePlugin({
               escapeHtml,
               jit: true,
               onlyLocales,
-              forceStringify
+              forceStringify,
+              usedKeyFilter: collector ? (keyPath) => collector.shouldKeepKey(keyPath) : void 0
             }
           );
-          debug$2("parseOptions", parseOptions);
+          debug$3("parseOptions", parseOptions);
           const { code: generatedCode, map } = await generate(code, parseOptions);
-          debug$2("generated code", generatedCode);
-          debug$2("sourcemap", map, sourceMap);
+          debug$3("generated code", generatedCode);
+          debug$3("sourcemap", map, sourceMap);
           if (code === generatedCode) return;
           return {
             moduleType: "js",
@@ -437,8 +445,9 @@ function resourcePlugin({
             } else if (defaultSFCLang) {
               langInfo = defaultSFCLang;
             }
-            debug$2("langInfo", langInfo);
+            debug$3("langInfo", langInfo);
             const generate = /\.?json5?/.test(langInfo) ? generateJSON : generateYAML;
+            const isGlobalBlock = globalSFCScope || !!query.global;
             const parseOptions = getOptions(
               filename,
               isProduction,
@@ -451,10 +460,11 @@ function resourcePlugin({
                 strictMessage,
                 escapeHtml,
                 onlyLocales,
-                forceStringify
+                forceStringify,
+                usedKeyFilter: collector && isGlobalBlock ? (keyPath) => collector.shouldKeepKey(keyPath) : void 0
               }
             );
-            debug$2("parseOptions", parseOptions);
+            debug$3("parseOptions", parseOptions);
             let source = await getCode(
               code,
               filename,
@@ -472,8 +482,8 @@ function resourcePlugin({
               }
             }
             const { code: generatedCode, map } = generate(source, parseOptions);
-            debug$2("generated code", generatedCode);
-            debug$2("sourcemap", map, sourceMap);
+            debug$3("generated code", generatedCode);
+            debug$3("sourcemap", map, sourceMap);
             if (code === generatedCode) return;
             return {
               moduleType: "js",
@@ -529,11 +539,12 @@ async function generateBundleResources(resources, isProduction, {
   strictMessage = true,
   escapeHtml = false,
   jit = true,
-  transformI18nBlock = void 0
+  transformI18nBlock = void 0,
+  usedKeyFilter = void 0
 }) {
   const codes = [];
   for (const res of resources) {
-    debug$2(`${res} bundle loading ...`);
+    debug$3(`${res} bundle loading ...`);
     if (/\.(json5?|ya?ml)$/.test(res)) {
       const { ext, name } = parse(res);
       const source = await getRaw(res);
@@ -545,11 +556,12 @@ async function generateBundleResources(resources, isProduction, {
         strictMessage,
         escapeHtml,
         forceStringify,
-        transformI18nBlock
+        transformI18nBlock,
+        usedKeyFilter
       });
       parseOptions.type = "bare";
       const { code } = generate(source, parseOptions);
-      debug$2("generated code", code);
+      debug$3("generated code", code);
       codes.push(`${JSON.stringify(name)}: ${code}`);
     }
   }
@@ -584,7 +596,7 @@ async function getCode(source, filename, sourceMap, query, parser, framework = "
   }
   if (framework === "webpack") {
     if (issuerPath) {
-      debug$2(`getCode (webpack) ${index} via issuerPath`, issuerPath);
+      debug$3(`getCode (webpack) ${index} via issuerPath`, issuerPath);
       return await getRaw(filename);
     } else {
       const result = parser(await getRaw(filename), {
@@ -594,7 +606,7 @@ async function getCode(source, filename, sourceMap, query, parser, framework = "
       const block = result.descriptor.customBlocks[index];
       if (block) {
         const code = block.src ? await getRaw(block.src) : block.content;
-        debug$2(`getCode (webpack) ${index} from SFC`, code);
+        debug$3(`getCode (webpack) ${index} from SFC`, code);
         return code;
       } else {
         return source;
@@ -618,7 +630,8 @@ function getOptions(filename, isProduction, query, sourceMap, {
   strictMessage = true,
   escapeHtml = false,
   jit = true,
-  transformI18nBlock = null
+  transformI18nBlock = null,
+  usedKeyFilter = void 0
 }) {
   const mode = isProduction ? "production" : "development";
   const baseOptions = {
@@ -631,6 +644,7 @@ function getOptions(filename, isProduction, query, sourceMap, {
     escapeHtml,
     jit,
     onlyLocales,
+    usedKeyFilter,
     env: mode,
     transformI18nBlock,
     onWarn: (msg) => {
@@ -675,7 +689,7 @@ async function getRaw(path) {
   return promises.readFile(path, { encoding: "utf-8" });
 }
 
-const debug$1 = createDebug(resolveNamespace("directive"));
+const debug$2 = createDebug(resolveNamespace("directive"));
 const tsEstree = {
   parse: void 0,
   simpleTraverse: void 0,
@@ -709,7 +723,7 @@ function directivePlugin({
             optimizeTranslationDirective,
             translationIdentifiers
           );
-          debug$1(`vite:vue options['template']:`, vuePlugin.api.options);
+          debug$2(`vite:vue options['template']:`, vuePlugin.api.options);
         }
       },
       configResolved(config) {
@@ -752,7 +766,7 @@ function resolveVueOptions(vuePlugin, optimizeTranslationDirective, translationI
     const vuePluginOptions = getVuePluginOptions(vuePlugin);
     const normalizedFilename = normalizePath(path.relative(vuePluginOptions.root, filename));
     const resolveIdentifier2 = translationIdentifiers.get(normalizedFilename);
-    debug$1("resolved vue-i18n Identifier", resolveIdentifier2);
+    debug$2("resolved vue-i18n Identifier", resolveIdentifier2);
     if (resolveIdentifier2 == null) {
       return void 0;
     }
@@ -770,7 +784,7 @@ function resolveVueOptions(vuePlugin, optimizeTranslationDirective, translationI
 }
 function analyzeIdentifiers(descriptor, { root }, translationIdentifiers) {
   const source = descriptor.scriptSetup?.content || descriptor.script?.content;
-  debug$1("getDescriptor content", source);
+  debug$2("getDescriptor content", source);
   if (!source) {
     return;
   }
@@ -788,11 +802,11 @@ function analyzeIdentifiers(descriptor, { root }, translationIdentifiers) {
   if (importLocalName == null) {
     return;
   }
-  debug$1("importLocalName", importLocalName);
+  debug$2("importLocalName", importLocalName);
   const resolvedIdentifier = getVueI18nIdentifier(scope, importLocalName);
   if (resolvedIdentifier) {
     const normalizedFilename = normalizePath(path.relative(root, descriptor.filename));
-    debug$1("set vue-i18n resolved identifier: ", resolvedIdentifier);
+    debug$2("set vue-i18n resolved identifier: ", resolvedIdentifier);
     translationIdentifiers.set(normalizedFilename, resolvedIdentifier);
   }
 }
@@ -840,9 +854,9 @@ function getVueI18nIdentifier(scope, local) {
     return null;
   }
   const variableIdPairs = parseVariableId(id);
-  debug$1("variableIdPairs:", variableIdPairs);
+  debug$2("variableIdPairs:", variableIdPairs);
   const returnVariableIdPairs = parseReturnStatement(returnStatement);
-  debug$1("returnVariableIdPairs:", returnVariableIdPairs);
+  debug$2("returnVariableIdPairs:", returnVariableIdPairs);
   return resolveIdentifier(variableIdPairs, returnVariableIdPairs);
 }
 const EMPTY_NODE_RETURN = {
@@ -954,6 +968,270 @@ function resolveIdentifier(localVariables, returnVariable) {
   }
 }
 
+function matchSafelistPattern(keyPath, pattern) {
+  const regexStr = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^.]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${regexStr}$`).test(keyPath);
+}
+function createUsedKeysCollector(options) {
+  const usedKeys = /* @__PURE__ */ new Set();
+  const safelistPatterns = options.safelist || [];
+  const dynamicKeyStrategy = options.dynamicKeyStrategy || "keep-all";
+  const removedKeys = /* @__PURE__ */ new Map();
+  let dynamicKeysDetected = false;
+  return {
+    get usedKeys() {
+      return usedKeys;
+    },
+    get dynamicKeysDetected() {
+      return dynamicKeysDetected;
+    },
+    set dynamicKeysDetected(val) {
+      dynamicKeysDetected = val;
+    },
+    safelistPatterns,
+    removedKeys,
+    addKey(key) {
+      usedKeys.add(key);
+    },
+    markDynamic() {
+      dynamicKeysDetected = true;
+    },
+    shouldKeepKey(keyPath) {
+      if (dynamicKeysDetected && dynamicKeyStrategy === "keep-all") {
+        return true;
+      }
+      if (safelistPatterns.some((pattern) => matchSafelistPattern(keyPath, pattern))) {
+        return true;
+      }
+      if (usedKeys.has(keyPath)) {
+        return true;
+      }
+      for (const key of usedKeys) {
+        if (key.startsWith(keyPath + ".")) {
+          return true;
+        }
+      }
+      return false;
+    },
+    reportRemoved(filename, keyPath) {
+      const existing = removedKeys.get(filename);
+      if (existing) {
+        existing.push(keyPath);
+      } else {
+        removedKeys.set(filename, [keyPath]);
+      }
+    },
+    getDiagnostics() {
+      let totalRemoved = 0;
+      for (const keys of removedKeys.values()) {
+        totalRemoved += keys.length;
+      }
+      return { totalRemoved, byFile: removedKeys };
+    }
+  };
+}
+
+const I18N_FUNCTIONS = /* @__PURE__ */ new Set(["t", "$t", "tc", "$tc", "te", "$te", "d", "$d", "n", "$n"]);
+const TEMPLATE_T_REGEX = /\$?t\s*\(\s*['"]([^'"]+)['"]/g;
+const VT_DIRECTIVE_STRING_REGEX = /v-t\s*=\s*"'([^']+)'"/g;
+const VT_DIRECTIVE_PATH_REGEX = /v-t\s*=\s*"\{[^}]*path\s*:\s*'([^']+)'/g;
+const TEMPLATE_DYNAMIC_T_REGEX = /\$?t\s*\(\s*[a-zA-Z_$]/g;
+async function extractKeysFromScript(source) {
+  const keys = [];
+  let hasDynamic = false;
+  let tsEstree;
+  try {
+    tsEstree = await import('@typescript-eslint/typescript-estree');
+  } catch {
+    return extractKeysFromScriptRegex(source);
+  }
+  try {
+    const ast = tsEstree.parse(source, {
+      range: true,
+      jsx: true,
+      allowInvalidAST: true,
+      suppressDeprecatedPropertyWarnings: true
+    });
+    tsEstree.simpleTraverse(ast, {
+      enter(node) {
+        if (node.type !== tsEstree.AST_NODE_TYPES.CallExpression) {
+          return;
+        }
+        const calleeName = getCalleeName(node, tsEstree.AST_NODE_TYPES);
+        if (!calleeName || !I18N_FUNCTIONS.has(calleeName)) {
+          return;
+        }
+        const firstArg = node.arguments[0];
+        if (!firstArg) {
+          return;
+        }
+        if (firstArg.type === tsEstree.AST_NODE_TYPES.Literal && typeof firstArg.value === "string") {
+          keys.push(firstArg.value);
+        } else if (firstArg.type === tsEstree.AST_NODE_TYPES.TemplateLiteral && firstArg.expressions.length === 0 && firstArg.quasis.length === 1) {
+          const value = firstArg.quasis[0].value.cooked;
+          if (value) {
+            keys.push(value);
+          }
+        } else {
+          hasDynamic = true;
+        }
+      }
+    });
+  } catch {
+    return extractKeysFromScriptRegex(source);
+  }
+  return { keys, hasDynamic };
+}
+function getCalleeName(node, AST_NODE_TYPES) {
+  const callee = node.callee;
+  if (callee.type === AST_NODE_TYPES.Identifier) {
+    return callee.name;
+  }
+  if (callee.type === AST_NODE_TYPES.MemberExpression && callee.property.type === AST_NODE_TYPES.Identifier) {
+    return callee.property.name;
+  }
+  return null;
+}
+function extractKeysFromScriptRegex(source) {
+  const keys = [];
+  let match;
+  const regex = /\b(?:\$?t|tc|\$tc|te|\$te|d|\$d|n|\$n)\s*\(\s*['"]([^'"]+)['"]/g;
+  while ((match = regex.exec(source)) !== null) {
+    keys.push(match[1]);
+  }
+  return { keys, hasDynamic: false };
+}
+function extractKeysFromTemplate(templateContent) {
+  const keys = [];
+  let hasDynamic = false;
+  let match;
+  TEMPLATE_T_REGEX.lastIndex = 0;
+  VT_DIRECTIVE_STRING_REGEX.lastIndex = 0;
+  VT_DIRECTIVE_PATH_REGEX.lastIndex = 0;
+  TEMPLATE_DYNAMIC_T_REGEX.lastIndex = 0;
+  while ((match = TEMPLATE_T_REGEX.exec(templateContent)) !== null) {
+    keys.push(match[1]);
+  }
+  while ((match = VT_DIRECTIVE_STRING_REGEX.exec(templateContent)) !== null) {
+    keys.push(match[1]);
+  }
+  while ((match = VT_DIRECTIVE_PATH_REGEX.exec(templateContent)) !== null) {
+    keys.push(match[1]);
+  }
+  if (TEMPLATE_DYNAMIC_T_REGEX.test(templateContent)) {
+    hasDynamic = true;
+  }
+  return { keys, hasDynamic };
+}
+async function analyzeVueSFC(content) {
+  const keys = [];
+  let hasDynamic = false;
+  let parse;
+  try {
+    const compilerSfc = await import('vue/compiler-sfc');
+    parse = compilerSfc.parse;
+  } catch {
+    const templateResult = extractKeysFromTemplate(content);
+    const scriptResult = await extractKeysFromScript(content);
+    return {
+      keys: [...templateResult.keys, ...scriptResult.keys],
+      hasDynamic: templateResult.hasDynamic || scriptResult.hasDynamic
+    };
+  }
+  const { descriptor } = parse(content);
+  if (descriptor.template?.content) {
+    const templateResult = extractKeysFromTemplate(descriptor.template.content);
+    keys.push(...templateResult.keys);
+    if (templateResult.hasDynamic) {
+      hasDynamic = true;
+    }
+  }
+  const scriptContent = descriptor.scriptSetup?.content || descriptor.script?.content;
+  if (scriptContent) {
+    const scriptResult = await extractKeysFromScript(scriptContent);
+    keys.push(...scriptResult.keys);
+    if (scriptResult.hasDynamic) {
+      hasDynamic = true;
+    }
+  }
+  return { keys, hasDynamic };
+}
+async function analyzeFile(content, filePath, collector) {
+  let result;
+  if (filePath.endsWith(".vue")) {
+    result = await analyzeVueSFC(content);
+  } else {
+    result = await extractKeysFromScript(content);
+  }
+  for (const key of result.keys) {
+    collector.addKey(key);
+  }
+  if (result.hasDynamic) {
+    collector.markDynamic();
+  }
+}
+
+const debug$1 = createDebug(resolveNamespace("tree-shaking"));
+function treeShakingPlugin(resolvedOptions, collector) {
+  let projectRoot = "";
+  return {
+    name: resolveNamespace("tree-shaking"),
+    enforce: "pre",
+    vite: {
+      configResolved(config) {
+        projectRoot = config.root;
+      }
+    },
+    webpack(compiler) {
+      projectRoot = compiler.options.context || process.cwd();
+    },
+    async buildStart() {
+      const treeShaking = resolvedOptions.treeShaking;
+      const patterns = treeShaking?.scanPatterns || [`${projectRoot}/src/**/*.{vue,ts,js,tsx,jsx}`];
+      debug$1("scanning patterns:", patterns);
+      const files = await fg(patterns, {
+        ignore: ["**/node_modules/**"],
+        absolute: true
+      });
+      debug$1(`found ${files.length} source files to scan`);
+      for (const file of files) {
+        try {
+          const content = await promises.readFile(file, "utf-8");
+          await analyzeFile(content, file, collector);
+        } catch (err) {
+          debug$1(`failed to analyze file: ${file}`, err);
+        }
+      }
+      debug$1(
+        `scan complete: ${collector.usedKeys.size} used keys found, dynamic: ${collector.dynamicKeysDetected}`
+      );
+      if (collector.dynamicKeysDetected) {
+        const strategy = treeShaking?.dynamicKeyStrategy || "keep-all";
+        if (strategy === "keep-all") {
+          warn(
+            "Tree-shaking: dynamic key usage detected. All keys will be preserved (dynamicKeyStrategy: keep-all)."
+          );
+        } else {
+          warn(
+            "Tree-shaking: dynamic key usage detected. Unused keys will still be removed (dynamicKeyStrategy: ignore)."
+          );
+        }
+      }
+    },
+    buildEnd() {
+      const diagnostics = collector.getDiagnostics();
+      if (diagnostics.totalRemoved > 0) {
+        debug$1(`tree-shaking: removed ${diagnostics.totalRemoved} unused message keys`);
+        for (const [file, keys] of diagnostics.byFile) {
+          debug$1(`  ${file}: removed ${keys.length} keys (${keys.join(", ")})`);
+        }
+      } else {
+        debug$1("tree-shaking: no keys removed");
+      }
+    }
+  };
+}
+
 const debug = createDebug(resolveNamespace("root"));
 const unpluginFactory = (options = {}, meta) => {
   debug("meta framework", meta.framework);
@@ -963,7 +1241,12 @@ const unpluginFactory = (options = {}, meta) => {
   debug("plugin options (resolving):", options);
   const resolvedOptions = resolveOptions(options);
   debug("plugin options (resolved):", resolvedOptions);
-  const plugins = [resourcePlugin(resolvedOptions, meta)];
+  const collector = resolvedOptions.treeShaking ? createUsedKeysCollector(resolvedOptions.treeShaking) : null;
+  const plugins = [];
+  if (resolvedOptions.treeShaking && collector) {
+    plugins.push(treeShakingPlugin(resolvedOptions, collector));
+  }
+  plugins.push(resourcePlugin(resolvedOptions, meta, collector));
   if (resolvedOptions.optimizeTranslationDirective) {
     if (meta.framework === "webpack") {
       raiseError(

package/lib/types.d.cts

@@ -1,5 +1,24 @@
 type SFCLangFormat = 'json' | 'json5' | 'yml' | 'yaml';
 type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';
+interface TreeShakingOptions {
+    /**
+     * Message key patterns to always keep (never tree-shake).
+     * Supports glob-like patterns (e.g., `'errors.*'`, `'validation.**'`).
+     */
+    safelist?: string[];
+    /**
+     * Strategy when dynamic key usage (e.g., `t(variable)`) is detected.
+     * - `'keep-all'`: Disable tree-shaking and keep all keys (safe default).
+     * - `'ignore'`: Continue tree-shaking despite dynamic keys (risky, use with `safelist`).
+     * @default 'keep-all'
+     */
+    dynamicKeyStrategy?: 'keep-all' | 'ignore';
+    /**
+     * Glob patterns for source files to scan for used message keys.
+     * Defaults to `${projectRoot}/src/**\/*.{vue,ts,js,tsx,jsx}` when not specified.
+     */
+    scanPatterns?: string[];
+}
 interface PluginOptions {
     include?: string | string[];
     exclude?: string | string[];
@@ -18,6 +37,12 @@ interface PluginOptions {
     escapeHtml?: boolean;
     optimizeTranslationDirective?: boolean | string | string[];
     transformI18nBlock?: (src: string | Buffer) => string;
+    /**
+     * Enable message key tree-shaking to remove unused locale message keys.
+     * Only effective in production builds.
+     * @default false
+     */
+    treeShaking?: boolean | TreeShakingOptions;
 }
 
-export type { PluginOptions, SFCLangFormat, VueI18nModule };
+export type { PluginOptions, SFCLangFormat, TreeShakingOptions, VueI18nModule };