RE:CZ

CZON ディレクトリ構造のリファクタリングと翻訳最適化

コンテンツ管理

👤 ドキュメント生成ツール開発者、技術文書メンテナー、翻訳最適化とコスト管理に関心のある技術者
本稿では、CZON ドキュメント生成ツールの 0.6.0 バージョンにおける大規模なリファクタリングについて詳細に解説します。著者はまず、以前のバージョンでハッシュをソースファイルIDとして使用したことにより、記事の修正時に雪崩式翻訳タスクが発生する問題と、対抗生成翻訳のトークン消費が過大になる課題を指摘します。これに対処するため、CZON は生成ディレクトリ構造をリファクタリングし、パスに基づいてソースファイルをそのままコピーする方式に変更することで、連鎖的な再生成を回避しました。同時に、著者は対抗生成翻訳のトークン消費を最適化する方法（例：一時ディレクトリを使用してファイルアクセスを制限する）について議論します。さらに、静的リソースの参照、メタデータ翻訳タスクの分離、残留ファイルの自動削除などのさらなる最適化の方向性を紹介し、長文を処理するために将来的に対抗生成翻訳を再導入することを強調しています。
  • ✨ CZON 0.6.0 はディレクトリ構造をリファクタリングし、ハッシュIDからパスコピーに変更して雪崩式翻訳を回避
  • ✨ 対抗生成翻訳のトークン消費は高く、通常翻訳の10倍以上
  • ✨ エージェントのファイルアクセスを制限する一時ディレクトリの使用でトークン消費を最適化可能
  • ✨ 静的リソース参照は画像、PDFなど多様なファイルタイプをサポート
  • ✨ メタデータ翻訳タスクを分離し、.czon/meta.jsonに保存する計画
📅 2026-01-26 · 1,720 文字 · 約 6 分で読めます
  • CZON
  • ディレクトリ構造
  • 翻訳最適化
  • トークン消費
  • ドキュメント生成
  • 静的リソース
  • メタデータ
  • 対抗生成

Table of Contents

CZON ディレクトリ構造のリファクタリング静的リソースの参照さらなる最適化

現在は2026年1月26日、月曜日午前4時です。

CZON ディレクトリ構造のリファクタリング

前回で述べた対抗生成翻訳の効果は確かに良好でした。しかし、CZON に一つの問題があることに気づきました。それは、ソースファイルの ID としてハッシュを使用している点です。これにより、9回引用されている記事を1回修正しただけで、(1 + 9) * 3 = 30 件の翻訳タスクが雪崩式にトリガーされてしまいました。さらに、対抗生成翻訳のトークン消費量は通常の翻訳の約10倍以上であり、長文を何度も修正するとトークン消費量が非常に大きくなり、コストも非常に高くなります。そのため、私は OpenCode の翻訳統合を再度ロールバックし、通常の単発翻訳を使用するように戻しました。

この問題を解決するため、CZON の生成ディレクトリ全体をリファクタリングしました。バージョン 0.6.0 以降、CZON はソースファイルを生成ディレクトリにパスを維持したままそのままコピーします。例えば、docs/guide/intro.md は .czon/src/{lang}/docs/guide/intro.md に書き込まれます。これにより、一つの記事を修正した後は、その記事のみを再翻訳すれば済むようになり、雪崩式の再生成を回避できます。(ただし、CZON の以前のバージョンをご利用のユーザーは .czon/src ディレクトリ全体を再生成する必要があり、すべての記事を再度翻訳する必要があります)

雪崩式再生成の連鎖を断ち切った後は、対抗生成翻訳のトークン消費量の最適化に取り組みます。対抗生成エージェントが時々他のファイルを過剰に読み取ることに気づきました。例えば、明明らかに zh-Hans から es-ES への翻訳タスクなのに、翻訳エージェントが en-US の内容を読み取ってしまうのです。これは明らかに不要なトークン消費です。しかし、OpenCode では現時点でセッションレベルでエージェントのファイルアクセス権限を制限することができません。一つの小さなトリックとして、必要なファイルを一時ディレクトリにコピーし、エージェントにその一時ディレクトリのみをアクセスさせる方法があります。ただ、今のところこの方法を採用するかどうか検討中です。詳細なプロンプトによってこのような不要なファイルアクセスを減らせるでしょうか？それとも、一時ディレクトリを使用する方が確実でしょうか？

CZON の生成ディレクトリ構造を修正したことで、これまで主導的な役割を果たしていた SHA-256 ハッシュ ID はほとんど活躍の場を失いました。czon://hash プロトコルも廃止されました。しかし、リファクタリング後はリンクの置き換えがよりエレガントになりました。翻訳前後では、これらのリンクを置き換える必要が全くなくなり、HTML をレンダリングする際にフックを使用して正しいパスにリンクを置き換えることができます。

現在の .czon ディレクトリ構造の設計は、git およびサードパーティの SSG 統合にとってより親しみやすいものになっています。

  • 各 .czon/src/{lang} ディレクトリは完全なディレクトリであり、個別にレンダリングまたはプレビューすることができます。
  • ハッシュではなくパスを使用することで、ソースファイルを修正するたびに新しいターゲットファイルが作成されるのではなく、既存のターゲットファイルが上書きされるため、大量の冗長ファイルの発生を回避できます。

静的リソースの参照

静的リソースは通常のリンク方式で参照できます。

CZON バージョン 0.6.0 では、画像、PDF など任意のリソースファイルを参照することもできます。これらのリソースファイルは、生成ディレクトリ内の対応する位置にコピーされます。画像だけでなく、txt、pdf、docx なども参照可能です。CZON はこれらのリソースファイルのコピー作業を自動的に処理します。

さらなる最適化

メタデータ翻訳タスクの分離

さらに進めて、YAML FrontMatter、つまりメタデータも .czon/meta.json に残し、事前に Markdown の先頭に enhance する必要はありません。むしろ、この YAML FrontMatter 自体が意味をなさなくなるかもしれません。

flowchart TD
    A[ソースMarkdownファイル] --> B["抽出されたMetaData (ソース言語で保存)"]
    A --> F[ソース言語のHTMLファイル]
    A --> C[ターゲット言語に翻訳されたMarkdownファイル]
    B --> D["翻訳されたMetaData (ターゲット言語で保存)"]
    D --> E
    C --> E[ターゲット言語のHTMLファイル]
    B --> F

.czon/src 内の残留ファイルの自動削除

CZON は現在、.czon/src/{lang} ディレクトリ内の不要なファイルを削除しません。例えば、ある記事が削除された後も、.czon/src/{lang}/path/to/deleted-article.md は残ったままです。将来のバージョンでは、CZON はこれらの不要なファイルを自動的に検出し、削除して生成ディレクトリを整理します。

対抗生成翻訳の再開

これは必然です。なぜなら、ワンショット翻訳では長文を全く処理できないからです。エージェントの使用は必須ですが、トークン消費量が大きすぎる問題を解決する必要があります。

See Also

Referenced By