ドキュメント翻訳を「成果物」ではなく

バージョン管理されたソフトウェア資産として扱うという考え方

大規模なドキュメントリポジトリを運用していると、
翻訳の問題はほとんどの場合、静かに発生します。

明らかに間違った翻訳は少なく、
多くの場合、翻訳文自体は自然に読めます。

しかし、原文はすでに更新されており、
翻訳は気づかれないまま古くなっています。

この「静かなズレ」は、時間とともに蓄積され、
最終的にはメンテナンス負債になります。

翻訳は間違っていないが、同期していない

ドキュメントは常に変化します。

テキストが修正され
コード例が更新され
スクリーンショットが差し替えられ
ノートブックの挙動が変わる

それでも翻訳は、
「一度完了した成果物」として扱われがちです。

このとき問題になるのは、
翻訳の品質ではありません。

同期状態です。

翻訳は正しくても、
もはや現在のソースと一致していない可能性があります。

問題の再定義

従来の翻訳ワークフローは、
次のような問いを暗黙的に前提としています。

この翻訳は正しいか？

しかし、実際に運用していて重要なのは別の問いです。

この翻訳は、現在のソースと同期しているか？

この違いは非常に重要です。

翻訳は間違っていなくても、
ソースの更新によって古くなることがあります。

この時点で、
翻訳を静的なコンテンツとして扱う前提は崩れます。

翻訳を「バージョン管理された資産」として扱う

そこで私たちは、翻訳の扱い方を根本から見直しました。

翻訳を、
特定のソースバージョンから生成された
ソフトウェア資産として扱うことにしたのです。

これは、Markdownファイルだけではありません。

翻訳された画像
ローカライズされたノートブック
その他の翻訳成果物すべて

これらを一貫して
「バージョンを持つ成果物」として扱います。

新しい仕組みを発明しない

この考え方を実装するために、
新しい概念を発明したわけではありません。

参考にしたのは、
pip や poetry、npm といった
依存関係管理ツールの設計思想です。

依存関係が更新されたとき、
それは突然「間違い」になるのではなく、
単に現在の状態と一致しなくなるだけです。

翻訳も同じです。

ファイル単位で状態を管理する理由

多くの翻訳システムは、
文字列やセグメント単位で状態を管理します。

UI翻訳では有効な方法ですが、
ドキュメントには必ずしも適していません。

ドキュメントでは、

Markdownファイル
画像
ノートブック

これらはファイル単位の成果物として消費されます。

そのため、翻訳の状態も
ファイル単位で管理する方が、
リポジトリの運用モデルと自然に一致します。

実際に変わったこと

ファイル内部のマーカーから、明示的な状態へ

以前は、翻訳状態を
翻訳ファイル内部のコメントやマーカーで管理していました。

しかしこの方法では、

状態が分散し
全体を把握しづらく
リポジトリが大きくなるほど破綻しやすい

という問題がありました。

現在は、
言語ごとにスコープされた JSON 状態ファイルを用いて、

ソースのバージョン
翻訳された成果物
同期状態

を明示的に管理しています。

画像やノートブックにも同じモデルを適用する

このモデルは、
テキストだけに限定されません。

ソース画像が更新されれば、翻訳画像は同期切れになる
ノートブックが変更されれば、翻訳版も再評価される

形式は違っても、
ライフサイクルは同じです。

翻訳を資産として扱うことで、
すべてのコンテンツに一貫したルールを適用できます。

この設計が可能にしたこと

この設計によって、次のことが可能になりました。

推測に頼らない同期ズレ検出
テキスト・画像・ノートブックの一貫した扱い
システムは状態を報告し、人が判断する分離
更新頻度の高いリポジトリでの持続可能な運用

大規模なドキュメントでは、
この違いが運用の可否を左右します。

これは何ではないか

この仕組みは、

翻訳品質を評価するものではなく
意味的な正しさを保証するものでもなく
自動承認を行うものでもありません

答えるのは、ただ一つです。

この翻訳成果物は、
現在のソースと同期しているか？

対象読者

この考え方は、次のようなチームに向いています。

多言語ドキュメントを運用している
コンテンツの更新頻度が高い
何が最新かを正確に把握したい

ドキュメントの進化が翻訳を上回る環境では、
翻訳を資産として扱うことは
最適化ではなく必然になります。

おわりに

翻訳をソフトウェア資産として扱うと、
長年曖昧だった問題が整理されます。

状態が見えるようになり
メンテナンスが管理可能になり
翻訳は自然にソフトウェア開発の流れに組み込まれます

そのとき問われるのは、
翻訳ズレが存在するかどうかではありません。

それを、あなたは可視化できているか。