localization-packager — agent 技能
用途
实现多语言本质上是一个打包问题：每种语言都需要相同的 4 个文件，返回的内容需要检查——文件存在性、标题长度、字幕可解析性、提示数量、提示时间漂移。此工具从一个项目 JSON 文件中生成计划、交接表和结构检查。纯 Python 标准库；仅本地运行。
此工具的核心诚实原则： 它不翻译任何内容，也不评判任何翻译。check 验证结构——文件存在性、可解析性、长度、时间。一个 COMPLETE 的语言包仍然可能包含糟糕的翻译；只有懂该语言的人才能评判。切勿将 COMPLETE 结论报告为“翻译良好”或“可发布”——它只是“结构完整，可供人工质量审阅”。
何时使用 / 不使用
使用场景：
- 视频或应用即将以其他语言发布，工作交付给翻译人员：
manifest用于制定计划，sheet用于交接，check作为返回内容的验收关卡。 - 管道需要每种语言的通过/不通过结果：
check退出码 0 = 每种语言结构完整；退出码 1 = 输出指出每种不完整的语言及其具体问题。
不要使用的情况：
- 需要翻译本身——此工具不调用任何翻译 API，也不生成任何翻译文本。空白的“目标”列是为人类翻译人员准备的。
- 需要翻译质量保证——这里没有拼写检查、回译或质量评分，这是有意为之。
- 需要频道级资源（横幅、结束画面）或应用商店元数据（超出 4 个打包文件的范围）——刻意排除在外。
命令
每个命令都将项目文件作为位置参数，并支持 --json。
# 每种语言的交付计划
python3 src/localization_packager.py manifest PROJECT.json
# 翻译交接表（默认 Markdown，或 CSV；单个语言或所有目标语言）
python3 src/localization_packager.py sheet PROJECT.json \
[--format md|csv] [--language CODE]
# 验证填充的语言包（任何语言不完整时退出码为 1；当文件夹位于其他位置时使用 --root）
python3 src/localization_packager.py check PROJECT.json \
[--root DIR]
项目字段：project（名称）、source_language、source_title、source_description、source_thumbnail_text、source_subtitles（源 SRT 文件路径，相对于项目文件）、targets——{"language", "name", "translator"?} 列表；语言代码必须唯一。每次读取都会验证文件；结构问题（缺少字段、重复语言、源 SRT 缺失或无法解析）是退出码为 2 的错误，会明确指出问题。
包的目录结构：每种语言一个文件夹，包含 title.txt、description.txt、subtitles.srt、thumbnail.txt。
检查规则（精确）
每种语言，按文件顺序：
title.txt——缺失或为空是问题；去除空白后的文本超过 100 个字符 是问题（100 通过，101 标记）。字符按 Unicode 码点计算。description.txt——缺失或为空是问题。subtitles.srt——缺失或为空是问题；文本无法解析为 SRT 是问题（解析错误会被引用）；提示数量与源文件相差超过 25% 是问题（正好 25% 通过，小于 25% 会记录，但不标记）；每个位置开始时间漂移超过 2000 毫秒 是问题，会指出提示和漂移值（正好 2000 毫秒通过，2100 毫秒标记为 "2.1s"）。漂移通过位置配对各提示，范围是 min(源提示数, 目标提示数) 的起始，仅比较开始时间。thumbnail.txt——缺失或为空是问题。
结论：零问题的语言为 COMPLETE，否则为 INCOMPLETE 并显示问题数量。只有所有语言都是 COMPLETE 时，check 的退出码才为 0。
输出 JSON 模式（--json）
通用字段：tool（"localization-packager"）、version、command、project_file（文件名）、project。
manifest：source_language、source_title、source_cues、languages——每个 {language, name, translator, folder, files}，其中 files 是 4 个必需文件，每个 {file, what, source_fact}。
check：source_cues、root、languages——每个 {language, name, translator, status ("complete" | "incomplete"), items, problems}，其中 items 是 4 个每个文件的结果 {file, ok, detail}，problems 列出失败细节——以及 complete、total、all_complete 和一个重申检查仅为结构性的 note。
sheet：sheets——每个目标语言一个，每个 {language, name, translator, rows}；rows 是 {n, item, timing, source, target}——3 个字符串行（标题、描述、缩略图文本），然后每个源提示一行（item = "cue N"，timing = SRT 格式 "start --> end"）；target 始终为 ""——空白列供翻译人员填写。
出错时，标准输出是一个单一对象：{"error": "<message>"}，退出码为 2——包括 --json 模式下的 argparse 使用错误。不输出纯文本，不输出回溯。
退出码
0——命令成功；对于check，每种语言都是 COMPLETE。1——发现：check至少发现一种不完整的语言。不是崩溃——问题列表就是发送回翻译人员的修复列表。2——错误：项目文件丢失或不是有效 JSON、缺少必需字段、重复的目标语言、源字幕缺失或无法解析、未知的--language、无效标志。失败的运行中不得引用任何输出事实。
agent 必须遵守的限制与诚实原则
- COMPLETE 仅表示结构完整——仅此而已。 切勿将其提升为“翻译正确”、“良好”或“可发布”。发布仍需懂该语言的人审阅；报告 COMPLETE 语言包时务必说明这一点。
- INCOMPLETE 是一个修复列表，而非翻译人员的失败。 报告确切的问题（文件、提示编号、漂移、字符数）——它们被设计为可直接转发。
- 此工具不产生任何翻译文本。 交接表中的“目标”列有意留空。切勿通过机器翻译填充并声称这是此工具的输出，也切勿在语言包的 4 个文件实际存在于磁盘上且
check已运行之前声称该语言包存在。 - 漂移标记基于位置。 如果翻译人员将一个提示拆分为两个，后续提示的位置会偏移并可能被标记；输出中的提示数量注释提供了上下文。报告这两个事实，而不只是标记。
- 仅本地运行： 该工具仅读取项目文件、源 SRT 和命令行中指定的包文件夹，不会发送任何数据到任何地方。