localization-packager — エージェントスキル
目的
多言語対応は、翻訳に関するパッケージングの問題です。各言語には同じ4つのファイルが必要であり、戻ってきたファイルのチェック（存在確認、タイトル文字数、字幕のパース可否、キュー数、タイミングのずれ）が必要です。このツールは、1つのプロジェクトJSONから、計画、引き継ぎシート、構造検証を生成します。Pure Python標準ライブラリのみで動作し、ローカル環境のみで使用します。
このツールの誠実さの中核： 翻訳は行わず、翻訳の品質も判断しません。check は構造（ファイルの存在、パース可能性、長さ、タイミング）を検証します。COMPLETE なパッケージでも、翻訳が不適切である可能性があります。その言語を読める人間だけが判断できます。COMPLETE という判定結果を「翻訳が正しい」や「公開準備完了」と報告してはいけません。それは「構造的に完全であり、人間による品質確認の準備ができた」という意味です。
使用する場合 / 使用しない場合
使用する場合：
- 動画やアプリを追加言語でリリースし、翻訳者に作業を依頼するとき：
manifestで計画を、sheetで引き継ぎシートを、checkで戻ってきたもののゲートとして使用します。 - パイプラインで言語ごとの可否（yes/no）が必要なとき：
checkの終了コード0 = 全言語が構造的に完全、終了コード1 = 不完全な言語とその問題を出力します。
使用しない場合：
- 翻訳自体が必要な場合 — このツールは翻訳APIを呼び出さず、翻訳テキストを生成しません。空白のターゲット列は人間の翻訳者が記入するためのものです。
- 翻訳品質保証が必要な場合 — スペルチェック、逆翻訳、品質スコアリングは意図的に実装されていません。
- チャンネルレベルのアセット（バナー、エンドスクリーン）や、パッケージ化された4つのファイル以外のアプリストアメタデータが必要な場合 — 意図的に範囲外です。
コマンド
すべてのコマンドはプロジェクトファイルを位置引数として受け取り、--json をサポートします。
# 言語別の配信計画
python3 src/localization_packager.py manifest PROJECT.json
# 翻訳者引き継ぎシート（デフォルトMarkdown、またはCSV;
# 1言語または全ターゲット言語）
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— 存在しないか空の場合は問題。strip後のテキストが100文字を超えると問題（100は通過、101はフラグ）。文字数はUnicodeコードポイントでカウント。description.txt— 存在しないか空の場合は問題。subtitles.srt— 存在しないか空の場合は問題。SRTとしてパースできないテキストは問題（パースエラーが引用される）。ソースのキュー数との差がソース数の25%を超えると問題（25%ちょうどは通過、それ以下の差は注記されフラグは立たない）。位置ごとの先頭タイミングの最大ドリフトが2000msを超えると問題（該当のキューとドリフト値を明示。2000msちょうどは通過、2100msは「2.1s」とフラグ）。ドリフトは最初のmin(ソース数, ターゲット数)のキューを位置でペアリングし、開始時刻のみ比較。thumbnail.txt— 存在しないか空の場合は問題。
判定: 問題がゼロの言語はCOMPLETE、それ以外はINCOMPLETE（問題数付き）。check はすべての言語がCOMPLETEの場合のみ終了コード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 — ターゲット言語ごとに1つ、各 {language, name, translator, rows}。rows は {n, item, timing, source, target} — 最初の3行（title、description、thumbnail）は文字列、その後はソースキューごとに1行（item = "cue N"、timing = SRT形式の "start --> end"）。target は常に "" — 翻訳者が記入する空白の列。
エラー時は、標準出力に単一のオブジェクト {"error": "<メッセージ>"} を出力し、終了コード2で終了します。--json モードでもargparseの使用法エラーを含みます。プレーンテキストやトレースバックは出力しません。
終了コード
0— コマンド成功。checkの場合はすべての言語がCOMPLETE。1— 発見事項あり：checkで少なくとも1つの言語が不完全。クラッシュではありません — 問題リストは翻訳者に送り返す修正リストです。2— エラー：プロジェクトファイルが見つからない、または有効なJSONでない、必須フィールドの欠落、ターゲット言語の重複、ソース字幕が見つからないまたはパースできない、未知の--language、無効なフラグ。失敗した実行からの出力内容を引用してはいけません。
エージェントが尊重すべき制限と誠実さのルール
- COMPLETE は構造的に完全という意味 — それ以上ではありません。 決して「翻訳が正しい」「良い」「公開可能」と格上げしてはいけません。リリースにはその言語を読める人間による確認が依然として必要です。COMPLETE なパッケージを報告する際は、その旨を必ず伝えてください。
- INCOMPLETE は修正リストであり、翻訳者の失敗ではありません。 正確な問題（ファイル、キュー番号、ドリフト、文字数）を報告してください — これらはそのまま転送できるように設計されています。
- このツールは翻訳テキストを生成しません。 シートのターゲット列は意図的に空白です。機械翻訳で埋めて、このツールの出力として提示してはいけません。また、実際に4つのファイルがディスク上に存在し、
checkが実行されるまで、言語パッケージが存在すると主張してはいけません。 - ドリフトフラグは位置ベースです。 翻訳者が1つのキューを2つに分割した場合、後続のキューの位置がずれてフラグが立つ可能性があります。出力のキュー数注記がそのコンテキストを提供します。フラグだけでなく、両方の事実を報告してください。
- ローカルのみ： ツールはプロジェクトファイル、ソースSRT、およびコマンドラインで指定されたパッケージフォルダのみを読み取り、どこにもデータを送信しません。