---
id: FEAT-0011
type: feature
status: closed
stage: Done
title: '增强 i18n 报告功能: 支持缺失文档清单输出 (Enhance i18n Reporting)'
created_at: '2026-01-09'
dependencies: []
related: []
solution: implemented
domains: []
tags:
- '#EPIC-0004'
- '#FEAT-0011'
parent: EPIC-0004
uid: e7caf3
---

## FEAT-0011: 增强 i18n 报告功能: 支持缺失文档清单输出 (Enhance i18n Reporting)

## 目标 (Objective)

增强 `monoco i18n scan` 命令的报告功能，支持更灵活的输出控制和更清晰的缺失文档清单展示。

**核心需求**:

1. 支持限制输出缺失文档的数量（默认最多 10 条）
2. 提供更清晰的缺失文档清单格式
3. 在大量缺失时给出统计摘要，避免信息过载

**业务价值**:

- 提升大型项目的 i18n 检查体验
- 快速定位最需要关注的翻译缺失
- 保持输出简洁，便于 CI/CD 集成

## 验收标准 (Acceptance Criteria)

1. **限制输出数量**:
   - 默认最多显示 10 条缺失文档记录
   - 支持通过 `--limit` 参数自定义输出数量
   - 支持 `--limit 0` 或 `--no-limit` 显示全部缺失记录

2. **改进报告格式**:
   - 当缺失记录超过限制时，显示"仅展示前 N 条，共 M 条缺失"提示
   - 按文件路径字母顺序排序，确保输出稳定性
   - 保持现有的表格格式和颜色方案

3. **统计摘要增强**:
   - 在摘要面板中显示"缺失文件数"统计
   - 区分"部分缺失"（某些语言缺失）和"完全缺失"（所有语言缺失）

4. **向后兼容**:
   - 不改变现有命令的基本行为
   - 保持退出码逻辑（有缺失时返回 1）

## 技术任务 (Technical Tasks)

- [x] **添加 `--limit` 参数**:
  - 在 `commands.py` 的 `scan` 函数中添加 `limit` 参数
  - 默认值设为 10
  - 支持 0 或负数表示无限制
- [x] **实现输出限制逻辑**:
  - 对 `missing_map` 按文件路径排序
  - 根据 `limit` 参数截取要显示的记录
  - 记录总缺失数和显示数的差异
- [x] **增强报告输出**:
  - 在表格标题或表格后添加"显示 X / 总计 Y"的提示
  - 当有截断时，提示用户使用 `--limit 0` 查看全部
- [x] **改进统计摘要**:
  - 添加"缺失文件数"字段
  - 可选: 区分部分缺失和完全缺失的文件数
- [x] **编写测试**:
  - 测试默认限制（10 条）
  - 测试自定义限制
  - 测试无限制模式
  - 测试排序稳定性
- [x] **更新文档**:
  - 更新 `Toolkit/docs/zh/i18n/manual.md`
  - 更新 `Toolkit/docs/en/i18n/manual.md`
  - 在 `--help` 中添加清晰的参数说明
- [x] **禁止路径截断**:
  - 在表格列配置中添加 `no_wrap=True` 和 `overflow="fold"`
  - 确保完整路径可见，避免信息丢失

## Review Comments

- [x] Self-Review
