欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在鸿蒙（OpenHarmony）出海产品的开发过程中，多语言支持是必不可少的。然而，随着项目从数十次迭代到最终重构，翻译文件夹（如 ARB 或 JSON）中往往积累了大量不再使用的“僵尸词条”。

这些废弃的翻译不仅占用了包体积，还拖慢了构建速度，更让维护者难以理清真正的有效文本。

translations_cleaner 正是为了解决这一痛点而设计的。它像一把精准的手术刀，能够自动扫描代码引用并安全剔除那些不再被使用的翻译条目，为你的多语言项目轻松瘦身。

一、原理解析 / 概念介绍

1.1 基础概念

translations_cleaner 的工作核心是双向比对。它会通过扫描所有 Dart 源码文件，提取页面中实际调用的翻译键值，再将其与翻译源文件（如 .arb）进行交集运算。对于没有任何引用记录的键值，它会将其标记为无效并剔除。

1.2 进阶概念

• 交叉引用审计（Cross-Reference Auditing）：该库能深入多层代码引用，确保动态组合生成的翻译键不被误删。
• 预览模式（Dry Run）：在真实执行清理操作前，提供了一个安全的预览机制，允许开发者查看清理明细，防止误触导致生产环境文本缺失。

二、核心 API / 组件详解

2.1 命令行一键清理

这是最推荐的使用方式，集成简单高效。

# 扫描 lib 目录，清理 assets/i18n 中的冗余翻译
dart run translations_cleaner --path=lib --translations=assets/i18n

2.2 使用 Dart API 进行集成测试

你也可以在 CI/CD 流程中通过代码调用：

import 'package:translations_cleaner/translations_cleaner.dart';

void runCleanAudit() {
   final cleaner = TranslationsCleaner(
      sourcePath: 'lib/features/', 
      translationsPath: 'assets/l10n/zh_CN.arb',
   );
   
   // 执行清理逻辑
   cleaner.clean();
   
   print("👑 清理完毕！应用瘦身成功。"); 
}

三、场景示例

3.1 场景一：利用 Dry Run 模式进行安全风险摸排

在正式提交清理代码前，务必先观察哪些词条可能存在风险。

# 开启预览模式，不修改任何文件
dart run translations_cleaner list-unused-terms

四、要点讲解 & OpenHarmony 平台适配挑战

4.1 动态键值的安全识别

⚠️ 适配提醒：
由于该库基于静态扫描，如果你的鸿蒙应用中使用了极其灵活的动态拼接翻译键（例如：Intl.message("status_$i")），静态扫描可能无法准确捕获。
✅ 应用策略：
在清理过程中，务必开启预览模式逐一排查这类动态键。同时建议将这类动态映射在专用配置文件中声明，以引导扫描器进行识别。

五、综合演示：瘦身过程模拟展示器

由于该库是命令行工具，我们在 Flutter 中模拟其核心的逻辑反馈流：

import 'package:flutter/material.dart';

class CleanerMonitor extends StatefulWidget {
  @override
  _CleanerMonitorState createState() => _CleanerMonitorState();
}

class _CleanerMonitorState extends State<CleanerMonitor> {
  String _status = "等待触发审计...";

  void _runMockClean() async {
      setState(() => _status = "⏳ 正在扫描 Dart 源码...\n🔍 发现 152 个引用...");
      await Future.delayed(Duration(seconds: 1));
      setState(() => _status = "✅ 扫描完毕！\n删除冗余词条：32个\n节省包体积：约 45KB\n瘦身成功！");
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('翻译瘦身中心'), backgroundColor: Colors.indigo),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Icon(Icons.cleaning_services, size: 64, color: Colors.blue),
            const SizedBox(height: 20),
            ElevatedButton(onPressed: _runMockClean, child: const Text('执行模拟审计')),
            const SizedBox(height: 20),
            Text(_status, textAlign: TextAlign.center, style: const TextStyle(fontWeight: FontWeight.bold)),
          ],
        ),
      ),
    );
  }
}

六、总结

在追求高性能、小体积的应用开发语境下，translations_cleaner 是完善鸿蒙工程化链路的重要一环。它将开发者从枯燥的人工比对中解放出来，确保每一行被打包的翻译都是“活着的”代码，让你的国际化工程始终保持轻盈。