本プロジェクトの技術的背景
正史和訳（AI）の成果物に加え、再現に必要なスクリプト・プロンプト・手順を GitHub で公開しています。
公開の形：本ページはサイト用フォルダ 技術解説/ に置き、同じ内容のリポジトリ akiasahi2008-hue/shisho-gijutsu に index.html・LICENSE（MIT）・code/金史/ を載せています。code/金史/ はローカル開発ディレクトリ 史書/金史 から取り込んだスナップショットであり、作業の本線は引き続きローカル側です。含めていないもの：原文・和訳の大量テキスト、生成 HTML、URLリスト.txt などのデータ類（リポジトリ容量と著作権のため）。実行時は --base-dir でご自身のプロジェクトルートを指定し、API キーは環境変数 DEEPSEEK_API_KEY のみを使用してください（コードに直書きしないこと）。
翻訳されたテキストを公開するだけでなく、その翻訳に至った手法やスクリプトを共有することは、漢文史料のデジタル化とAI翻訳の活用を広げるための重要なステップだと考えています。 — 本ページの公開方針
1. なぜ「手法」の公開に価値があるのか
- 再現性：『春秋』『資治通鑑』、地方志など、未処理の漢文史料は膨大です。プロンプト・分割・API 設定が分かれば、他の有志が同じ手法を用いて別の史書の翻訳に挑戦しやすくなります。
- AI翻訳の信頼性の検証：AIへの指示内容や翻訳処理の各種設定が明示されていれば、読者は翻訳の精度や妥当性を検証しやすくなります。
- 構造化データの普及：「漢文1行：和訳1行」のように構造化された対訳データは、NotebookLM等での活用をはじめ、検索や研究用途に大きく役立ちます。
2. 金史パイプラインのファイル構成
次の表は、GitHub の code/金史/（およびローカルの 史書/金史）に含まれる主なファイルです。入手・閲覧はリポジトリの該当パス、または手元にクローンしたフォルダから行ってください。入口の説明は code/金史/README.md にまとめています。
| 種別 | ファイル（例） | 役割 |
|---|---|---|
| パイプライン | workflow.py |
単巻の流れ：fetch → split → DeepSeek 翻訳 → merge。既定では 原文/巻*.txt を読み、Wikisource 取得が必要なときだけ --fetch。 |
| Windows バッチ | run_translate.bat |
ダブルクリックで対話実行。モード1は単巻（内部で workflow.py）、モード2は巻番号範囲（run_range.py）。バッチと同じフォルダを --base-dir に自動設定。このバッチ自体は Wikisource を取りに行かず、事前に 原文/ を用意するか、別途 wikisource_fetch.py／workflow.py --fetch を使ってください。 |
| API | deepseek_translate.py |
DeepSeek Chat API（https://api.deepseek.com/chat/completions）呼び出し。環境変数 DEEPSEEK_API_KEY を使用。進捗は各巻フォルダの progress.json で管理し、中断後の再開に利用。※ DeepSeek APIは有料ですので、ご購入ページから必要な分だけチャージ（Top up）してください。 目安としては「100巻の翻訳で1〜2ドルぐらい」です。 |
| 分割 | splitter.py |
トークン・行数制限対策として、--max-lines（既定 15）と --max-chars（既定 1900）でチャンク化。 |
| 取得・整備 | wikisource_fetch.py、bulk_preflight_fetch.py、cleanup_raw_pipeline.py |
ウィキソース由来テキストの取得と前処理。 |
| ウィキ整形 | strip_wiki_templates.py、remove_toc_lines.py、remove_wiki_html_artifacts.py |
MediaWiki テンプレや __TOC__ 等の除去。手順は テキスト整備手順.md に記載。 |
| URL 一覧 | regen_url_list.py |
zh.wikisource の索引から巻ページ URL を収集し URLリスト.txt を生成。 |
| プロンプト | 翻訳プロンプト2.txt |
workflow.py の --prompt-file 既定で参照。役割・文体・1行対1行・固有名詞の扱いを記述。 |
| HTML 化 | 和訳/convert_kyutango_to_premium_html.py ほか |
和訳テキストから閲覧用 HTML への変換（指示は 和訳/史書HTML変換指示書.md）。 |
「表」巻と表マークアップ（除外の考え方）
正史の志・表・列伝の「表」という区分だからといって、見出しだけで機械的に巻を除外しているわけではありません。パイプラインが扱いづらいと判断しているのは、Wikisource の wikitext に含まれる表マークアップです。具体的には、MediaWiki の表構文（{| で始まる形式）、HTML の <table> タグ、{{table 系テンプレートなどが検出された巻は、bulk_preflight_fetch.py（一括取得時）や purge_volumes_with_tables.py（既存の 原文/ を検査）により、和訳対象から外し、URLリスト.txt からも除く実装になっています。検出関数は wikisource_fetch.py の wikitext_has_table_markup です。
逆に、巻名が「表」でも本文がプレーンな行ベースのテキストに近い場合は、この判定に引っかからず処理対象になることがあります。単発取得では wikisource_fetch.py の --reject-if-table で保存を拒否することもできます。
3. 本リポジトリで示している「公開セット」
歴史資料のデジタル化や AI 和訳を他者が再現しやすくするために、次の三層をそろえています。
① Python スクリプト（API・分割・再開）
- API 連携：
deepseek_translate.pyが HTTP で JSON を送受信。キーはコードに書かず環境変数のみ。 - テキスト分割：
splitter.pyの行数・文字数上限が、長大な史書を安全に分割して処理するための主要な設定項目です。行数不一致が続く場合はworkflow.pyの--fast-stable（小さめサイズに分割するプリセット）も利用可能です。 - エラーハンドリング・レジューム：
progress.jsonのdone_chunks/failed_chunksと、既存のtranslated/chunk_*.txtを照合して続きから処理します。
② プロンプト（翻訳プロンプト2.txt）
リポジトリ内の同名ファイルでは、次のような方針を明示しています（抜粋）。
あなたは中国正史『金史』（元・脱脱等撰）の漢文を、学術的な日本語に翻訳する専門家です。 【基本方針】 ・文体は現代日本語の文語調（である調）。過度な口語・俗語は避ける。 ・原文の行構造を保つ：1行の入力に対し、和訳も原則1行（…） 【固有名詞・時代】 ・人名・王朝名・地名・官職名は、一般的な日本史学・漢籍慣例に従う（…）
公開用に API キーや個人パスを含むコマンド例は載せず、DEEPSEEK_API_KEY は各自の環境変数で設定してください。
③ ワークフロー（手順の全体像）
- ウィキソース等から原文テキストを用意する（
regen_url_list.py→ fetch 系スクリプト）。表マークアップ検出で除外された巻は表検出_除外巻.txt等に記録されます。 strip_wiki_templates.py等でテキストを整備（テキスト整備手順.md）。- Windowsでは
run_translate.batからworkflow.py／run_range.pyを叩くと、コマンドラインに不慣れでも単巻・範囲実行しやすくなります。 workflow.pyで分割・翻訳・結合し、ローカルで和訳/巻*.txtを生成。和訳/convert_kyutango_to_premium_html.py等で公開用 HTML を出力し、ポータル（史書.html）から成果物へリンク。
4. 公開している場所の役割
- 本サイト（ポータル）：和訳 HTML の閲覧が主目的です。
史書.htmlから本ページ（技術解説/index.html）へ導線を張り、閲覧者が手法の概要と GitHub へ辿れるようにしています。 - GitHub（shisho-gijutsu）：スクリプト・プロンプト・手順書の取得、Issue やフォークによる改善の受け皿として使えます。コードのライセンスはリポジトリ直下の MIT です。
5. 著作権・ライセンス
スクリプト類はリポジトリルートの LICENSE（MIT）に従います。改変・再利用・再配布の条件は同ファイルを参照してください。
翻訳テキスト（和訳本文）の利用・引用については、公開サイトの「ご利用・引用について」およびフッターの案内に従ってください。底本（中華書局版・維基文庫等）との関係もそこで示しています。
6. 初心者の方へ（AIエディタの活用）
スクリプトやPythonの詳しい仕組みがわからない方でも、Cursor などのAIコードエディタを活用すれば簡単に翻訳環境を構築できます。
公開しているファイル一式をローカルPCのプロジェクトフォルダにすべて保存し、Cursorでそのフォルダを開いてください。そして、CursorのAIチャットに対して以下のように指示を出します。
「https://zh.wikisource.org/wiki/%E9%87%91%E5%8F%B2 （※ 例として金史のURL）を翻訳したいので、このフォルダ内にあるコード類を私の環境に合わせて修正・調整してください」
このように指示すれば、あとはAIがコードの修正から翻訳開始に必要な準備までを自動的に案内し、環境を整えてくれます。