i18n Mage

Appearance

🧩 检测词条使用率 ​

功能简介 ​

本功能能够扫描你的代码库，全面分析翻译词条的使用情况，帮助你：

  • ✅ 识别正在使用的翻译词条
  • ❌ 发现未使用的冗余词条
  • ⚠️ 找出代码中引用但未定义的词条

通过清理无用词条、补充缺失翻译，让你的语言文件保持整洁高效。

开始之前 ​

必需配置 ​

1. 设置项目路径

  • 配置 i18n-mage.workspace.projectPath 指向项目根目录
  • 插件将在此目录下扫描所有相关文件

2. 设置语言文件路径

  • 配置 i18n-mage.workspace.languagePath 指向翻译文件目录
  • 插件会自动检测常见的语言文件位置

3. 配置文件类型

  • 设置 i18n-mage.general.fileExtensions 指定要扫描的文件格式
  • 默认支持：.js、.ts、.vue、.jsx、.tsx 等前端文件

可选配置 ​

🔍 扫描字符串字面量

  • 启用后，代码中的普通字符串也会被分析为可能的翻译键
  • 设置项：i18n-mage.analysis.scanStringLiterals

💬 忽略注释代码

  • 启用后，注释中的词条不会被统计
  • 设置项：i18n-mage.analysis.ignoreCommentedCode

📁 排除目录

  • 配置 i18n-mage.workspace.ignoredDirectories 排除不需要扫描的目录
  • 建议排除：node_modules、dist、build 等

⚡ 性能优化

  • 设置文件大小阈值：i18n-mage.analysis.fileSizeSkipThresholdKB
  • 默认跳过超过 100KB 的大文件，提升扫描速度

🔄 自动检测

  • 启用 i18n-mage.analysis.onSave 可在保存文件时自动触发检测
  • 内置防抖机制，避免频繁触发影响性能

如何使用 ​

手动触发检测 ​

  1. 启动扫描

    • 点击侧边栏顶部的 "刷新" 按钮
    • 使用快捷键：Ctrl+Alt+C (Win/Linux) 或 Cmd+Alt+C (Mac)
    • 在命令面板执行：i18n Mage: Check Usage

  2. 等待完成

    • 查看进度条了解扫描状态
    • 完成后树视图会自动更新

  3. 查看结果

    • 在侧边栏"使用信息"面板查看统计
    • 显示使用率百分比和具体数量（如 "76% | 342/450"）

自动检测模式 ​

  1. 开启自动检测

    • 在设置中启用 i18n-mage.analysis.onSave

  2. 实时查看更新

    • 保存文件后，视图会自动刷新
    • 使用信息面板显示最新数据

理解检测结果 ​

使用信息面板 ​

🟢 已使用词条

  • 代码中实际引用的翻译词条
  • 显示使用次数和翻译内容
  • 展开可查看具体使用位置（文件路径 + 行号）
  • 点击位置可直接跳转到代码

🔴 未使用词条

  • 语言文件中定义但代码未使用的词条
  • 显示翻译内容
  • 支持右键删除或标记为已使用

🟡 未定义词条

  • 代码中使用但语言文件中未定义的词条
  • 显示格式：总数(可修复数) + 提示信息
  • 展开可查看使用位置
  • 支持右键"提取未定义文本"快速修复

使用率计算 ​

使用率 = (已使用词条数 ÷ 总词条数) × 100%

示例：450 个词条中 342 个被使用，使用率为 76%

重要说明 ​

动态 Key 处理 ​

✅ 支持的模式

  • 字符串拼接：t("prefix." + key + ".suffix")
  • 这些动态匹配会影响使用率统计

可修复词条条件 ​

词条被认为是"可修复"需满足：

必须满足：

  • 不启用语言验证，或语言匹配参考语言
  • 不启用变量忽略，或词条不像英文变量名

修复方式：

  • 使用"提取未定义文本"功能
  • 自动生成新 key 并添加到语言文件

性能优化措施 ​

🚀 扫描优化

  • 跳过超过阈值的大文件
  • 内置 3 秒防抖机制，避免频繁触发
  • 自动保存时只扫描修改的文件，使用缓存结果

配置变更影响 ​

修改以下配置会自动重新检测：

  • 命名空间策略 (i18nFeatures.namespaceStrategy)
  • 同步基准 (analysis.syncBasedOnReferredEntries)
  • 字符串扫描开关 (analysis.scanStringLiterals)
  • 文件扩展名 (general.fileExtensions)
  • 文件大小阈值 (analysis.fileSizeSkipThresholdKB)
  • 注释忽略开关 (analysis.ignoreCommentedCode)

多文件模式 ​

📂 命名空间策略

  • 支持：auto（自动）、full（完整）、file（文件）、none（无）
  • 不同策略影响 key 的识别和匹配
  • auto 模式会选择使用率最高的策略

🌐 多文件结构

  • 自动检测项目是否使用多文件结构
  • 多文件模式下，根据文件路径生成命名空间前缀

总结 ​

翻译词条使用率检测是插件的核心功能，与"修复未定义词条"和"补充缺失翻译"功能紧密配合，形成完整的国际化管理流程。

使用信息面板提供三个维度的统计分析，每个类别都支持详细查看和快捷操作。通过多项性能优化，确保在大型项目中也能快速完成扫描，帮助你保持翻译词条的整洁和高效。