2026 年 7 月 10 日
- Markdown -> JSONL Converter で公式ドキュメント JSONL 変換収集量を 1180 件から 1230 件に進めた
- 多言語翻訳パイプラインが思ったより遅延しており、安定化まで時間がかかる可能性があることを確認した
- private リポジトリで多言語ドキュメント同期パイプラインをテストし、その過程で私が設定した基準は以下の通りです
文書構造基準
- 韓国語文書を基準文書とする
- 多言語文書は
docs/<lang>/...形式で配置する - もともと
docs/直下にあったサブパスは韓国語基準文書とみなし、docs/ko/...以下に移動する - 言語コードは
jp,chのような任意コードではなく、ja,zh,pt-BRのような標準言語コードを使用する - ルート
README.mdはルート文書として維持する - README の翻訳版もルート基準で扱う
README.mdの修正がdocs/内のファイル修正に誤って連鎖しないようにする- 既に存在する
docs/en,docs/jaなどの言語フォルダがdocs/ko/enのように入れ子にならないようにする - 圧縮ファイルテスト時は
READMEとdocsのみを展開して反映する
リンクとパス基準
- README と docs 内部のリンクは対象言語に合わせて変更する。例として韓国語 README の
docs/ko/...リンクは英語 README ではdocs/en/...に置き換える - docs 内部文書同士の相対パスも対象言語基準で置き換える
- 画像パス、サブディレクトリリンク、相対パスが翻訳/同期過程で壊れないようにする
- README の言語リンクはユーザーが該当言語文書へ移動または切り替えたと感じられる形にする
自動同期基準
docs/koにファイルが追加されたら他言語にも対応ファイルを生成するdocs/koからファイルが削除されたら他言語でも対応ファイルを削除するdocs/koの特定ファイルが更新されたら対応する他言語ファイルだけを再生成対象とする- 全体を毎回最初から翻訳しない
- 既に成功した言語/ファイルは再翻訳しない
- 失敗しても成功した成果物は削除しない
- 失敗した対象ファイルだけを除去し、次回実行時にそのファイルだけを再生成する
- ファイル数比較や単純バージョンファイルで既に正しい言語フォルダはスキップする
- バージョンファイルは複雑な JSON/ハッシュより
v1や数字のようなシンプルな形を使用する
翻訳処理基準
- 翻訳は実際の API でテストする
- mock の成功処理は使用しない
- モデルの公式コンテキスト/出力上限を見てチャンクサイズを決める
- 入力コンテキストより実際の翻訳出力が
max_tokensを超えないようにカットすることを重視する - チャンクを翻訳した直後にすぐ検査する
- 翻訳直後の検査で失敗した領域はキューに入れる
- キューに入った失敗領域だけを depth を増やして細分化し、再翻訳/再検査する
- すべてのチャンクを結合した後に最後に一度だけ検査する構造は避ける
検査基準
- 翻訳結果に韓国語がそのまま残っていないか確認する
- 空白が削除されているか確認する
- Markdown 構造が保持されているか確認する
- コードフェンス、リンク、画像、ヘッディングが保持されているか確認する
- 中国語のように長さが短くなる言語は単純な長さ比較だけで判断しない
- 成果物を実際に読んで原文と比較し、違和感がないか確認する
失敗ログ基準
HTTP 429,504,RemoteDisconnected,finish_reason=length, 空応答 などの失敗原因を区別する- 応答ヘッダー、応答本文、所要時間、モデル名、入力サイズ、トークン使用量をログに残す
- 失敗一件でパイプライン全体が停止したり成果物が消失しないようにする
- 失敗が繰り返される場合はまず原因を分析する
NVIDIA API 使用基準
- 翻訳パイプラインは NVIDIA API を基準にテストする
gpt-oss-120bは入力コンテキストが最大 128k まで可能だが、NVIDIA API のポリシー上出力は約 4096 トークンが上限と見なされる- 入力を大量に入れても出力上限のため翻訳結果が切れる可能性があるので、実際のチャンク基準は output 4096 トークン制限を基準に設定する
- 1 分間に 40 回呼び出しを基準に試行し、エラーが発生したら待機/再試行ポリシーを設ける
ハードコーディング基準
docs/<lang>, マーカー, リンク正規表現, コードフェンス解析などの構造規則を使用する- 特定の単語を任意に置き換えたり削除したりしない
example.comを任意に削除しない- 文書ファイルを個別にパスで登録する方式は使用しない
- 言語的表現や特定文/単語を無理に置換しない
運用基準
- GitHub Actions と Mac self‑hosted runner の両方を検討する
- Mac で実行する場合も完了後に自動コミット/プッシュされるフローにする
- GitHub Actions のように進捗が見えるようにする
- どの言語/ファイル/チャンクが進行中かをログで確認できるようにする
- ブランチ名、run URL、失敗原因、現在の進捗率を明確に残す
翻訳とは別に、最近面白い文書を見つけた。
curlで API キーなしでもテキスト応答が得られ、画像生成も可能な構造のように見えるAPI キーを作成して課金の心配なく軽く実験できないかと考える
とりあえずこれを使って面白いものを開発し、もう少し使ってみてから後で公開するつもり
Qwen Validation Debuggerのバージョン分離 JSONL スロット構造を再整理docs_chunksはコード説明根拠なので Godot 3 コードと Godot 4 コード別説明/無関係説明スロットを維持api_mappingとlabel_prototypesは Godot 3 専用、Godot 4 専用 JSONL を別々に作るより、Godot 3 コードと Godot 4 コードを一緒に入れて3 -> 4変換根拠 JSONL として生成する方向に変更3 -> 4変換根拠 JSONL の検証期待値は Godot 3 コードは「はい」、Godot 4 コードは「いいえ」とする- 無関係変換 JSONL の検証期待値は Godot 3 コードも Godot 4 コードも「いいえ」とする