idea_world_labDEV JOURNAL
2026年7月10日金曜日

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、失敗原因、現在の進捗率を明確に残す

翻訳とは別に、最近面白い文書を見つけた。

  • Pollinations APIDOCS.md を確認

  • 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 コードも「いいえ」とする

  • 回顧: docs/retrospectives/2026-07-10.md