localization-packager — agent 技能
目的
多語言化是一個圍繞翻譯的打包問題：每一種語言都需要相同的 4 個檔案，而回傳的內容則需要檢查——是否存在、標題長度、字幕能否解析、提示數量、提示時間漂移。這個工具從一個專案 JSON 產生計劃、交接表和結構檢查。純 Python 標準函式庫；僅限本機執行。
這個工具的誠實核心： 它不翻譯任何內容，也不評斷任何翻譯。check 驗證的是結構——檔案是否存在、能否解析、長度、時間。一個 COMPLETE 的套件仍然可能包含糟糕的翻譯；只有懂得該語言的人才能評斷。永遠不要把 COMPLETE 的結果回報為「翻譯是好的」或「準備好發布」——它只表示「結構完整，已準備好讓人進行品質審閱」。
何時使用 / 不使用
在以下情況使用：
- 影片或應用程式即將以額外的語言發布，且工作已交給翻譯人員：
manifest用於計劃，sheet用於交接，check作為驗收回傳內容的門檻。 - 管線需要每種語言的通過/不通過判斷：
checkexit 0 = 每種語言結構完整；exit 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]
# 驗證已填寫的套件（當有任何語言不完整時 exit 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）會產生 exit code 2 錯誤，並指出問題所在。
套件佈局：每種語言代碼一個資料夾，內含 title.txt、description.txt、subtitles.srt、thumbnail.txt。
檢查規則（精確）
每種語言，依檔案順序：
title.txt——缺少或空白視為問題；去除前後空白後，文字長度超過 100 個字元 視為問題（100 個字元通過，101 個字元標記）。字元計數以 Unicode 碼點為準。description.txt——缺少或空白視為問題。subtitles.srt——缺少或空白視為問題；文字無法解析為 SRT 視為問題（會引用解析錯誤）；提示數量與來源相差超過 25%（的來源數量）視為問題（差距恰好 25% 通過，較小的差距會備註，但不會標記）；每個位置的開始時間漂移超過 2000 毫秒 視為問題，會指出提示編號和漂移量（恰好 2000 毫秒通過；2100 毫秒標記為「2.1s」）。漂移是按位置配對 min(來源提示數, 目標提示數) 的前幾個提示進行比較，僅比較開始時間。thumbnail.txt——缺少或空白視為問題。
判定：一個語言零問題則為 COMPLETE，否則為 INCOMPLETE 並附上問題數量。check 僅在每種語言都是 COMPLETE 時以 exit code 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 行是字串（title、description、thumbnail），然後每個來源提示一個行（item = "cue N"，timing = SRT "start --> end"）；target 永遠是 ""——留給翻譯人員填寫的空白欄位。
發生錯誤時，stdout 是一個單一物件：{"error": "<訊息>"}，exit code 為 2——包括使用 --json 模式時的 argparse 使用方式錯誤。永遠不回傳純文字，永遠不回傳 traceback。
Exit codes
0——指令成功；對於check，表示每種語言都是 COMPLETE。1——發現問題：check發現至少一個不完整的語言。這不是當機——問題清單就是可以送回給翻譯人員的修正清單。2——錯誤：專案檔案不存在或不是有效的 JSON、缺少必要欄位、目標語言重複、來源字幕不存在或無法解析、未知的--language、無效的旗標。失敗的執行中不應引用任何輸出事實。
agent 必須遵守的限制與誠實規則
- COMPLETE 僅表示結構完整——沒有其他意義。 永遠不要將其升級為「翻譯是正確的」、「好的」或「可發布的」。發布前仍然需要一位懂該語言的人進行審閱；在回報 COMPLETE 套件時請這樣說明。
- INCOMPLETE 是一個修正清單，而不是翻譯人員的失敗。 回報確切的問題（檔案、提示編號、漂移、字元數）——這些問題被設計成可以直接轉發。
- 這個工具不會產生任何翻譯文字。 交接表中的目標欄位刻意保留空白。永遠不要用機器翻譯填充它，並將結果冒充為此工具的輸出；也永遠不要聲稱某個語言套件已存在，直到其 4 個檔案實際存在於磁碟上且
check已對它們執行過。 - 漂移標記是基於位置的。 如果翻譯人員將一個提示分成兩個，後面的提示位置會偏移並可能被標記；輸出中的提示數量備註提供了上下文。請同時回報這兩個事實，而不只是標記。
- 僅限本機：此工具只讀取命令列指定的專案檔案、來源 SRT 和套件資料夾，不會傳送任何資料到任何地方。