Translation Sync Engine — better-i18nのローカリゼーションパイプラインのための信頼性の高い非同期処理
ソースコード、翻訳、CDNを完全に同期させる信頼性の高い非同期翻訳パイプライン — 競合検出、Activity Logging、ゼロデータロスを備えています。
なぜ専用のSync Engineが必要か？
翻訳ワークフローは複数のシステムに関わります — GitリポジトリRepository、翻訳データベース、ランタイム配信用のCDN、コンテキスト分析用のAIサービスです。これらのシステムをリアルタイムで調整することは脆弱です。APIタイムアウトが1回発生するだけで、翻訳が不整合な状態になる可能性があります。
Better i18nは、Cloudflare Queues上に構築された専用のSync Engineでこれを解決します。Keyのインポートから翻訳の公開まで、すべての操作は、リトライ、順序保証、完全な可観測性を備えた非同期ジョブとして処理されます。
結果として、何か問題が発生しても、翻訳はすべてのシステムで一貫した状態を保ちます。
アーキテクチャの概要
Sync Engineは、構造化されたメッセージを処理するCloudflare Queueコンシューマーです。各メッセージは、トリガーするSync、アップロードするファイル、公開するバッチなど、個別の作業単位を表します。
メッセージは明確に定義されたライフサイクルを通じて流れます：
- Producer — アクション（Pushイベント、手動Sync、公開）によりメッセージがエンキューされます
- Queue — Cloudflare Queuesが耐久性のある順序付き配信を提供します
- Consumer — SyncワーカーがメッセージをピックアップしてJobを実行します
- Activity Log — 完全なトレーサビリティのために、すべてのステップがSync活動として記録されます
この分離により、API応答は高速になり（作業はバックグラウンドで行われます）、障害はユーザーの介入なしに自動的に再試行されます。
10種類のメッセージタイプ
Sync Engineは10種類の異なるメッセージタイプを処理し、それぞれが特定の作業クラスを担当します：
| メッセージタイプ | 目的 |
|---|---|
| SYNC_START | 完全または増分GitHubSyncをトリガーします — ファイルを取得し、Keyを比較し、データベースを更新します |
| REPO_PUSH_SYNC | GitHubのPush Webhookイベントを処理します — 高速な増分Syncのために変更されたファイルのみを処理します |
| CDN_SETUP | プロジェクトが初めて設定されたときに初期CDNマニフェストと空の言語ファイルを作成します |
| CDN_UPLOAD | 単一のJSON翻訳ファイルをR2ストレージにアップロードします |
| CDN_MERGE | 変更されていないKeyを上書きせずに、既存のCDNファイルに新しい翻訳コンテンツをマージします |
| CDN_CLEANUP | プロジェクトのすべてのR2ファイルを削除します（プロジェクトの削除またはリセット時に使用） |
| AI_CONTEXT_ANALYSIS | Firecrawl + Geminiを使用してウェブサイトを分析し、翻訳コンテキストを構築します |
| REPO_ANALYSIS | GitHubリポジトリをスキャンしてフレームワークを検出し、用語を抽出し、プロジェクトコンテキストを構築します |
| PUBLISH_BATCH | 承認された翻訳を単一のアトミック操作でCDNとGitHubの両方にプッシュします |
| GLOSSARY_SYNC | 一貫した機械翻訳のためにDeepLと用語集を同期します |
各メッセージタイプには、独自のハンドラー、バリデーション、およびエラー回復ロジックがあります。CDNアップロードの失敗がSync操作をブロックすることはなく、その逆も同様です。
ライフサイクル全体をカバーする12種類のJobタイプ
Jobはより高レベルのワークフローを表し、複数のメッセージを生成する場合があります：
- initial_import — リポジトリからの初回Key抽出
- incremental_sync — 前回の実行以降に変更されたファイルのみをSync
- full_sync — すべての翻訳ファイルの完全な再Sync
- source_sync — ソース言語の変更のみをSync
- bulk_translate — 複数の言語に対して機械翻訳をトリガー
- publish / batch_publish — 承認された翻訳を本番環境にプッシュ
- cdn_upload / cdn_merge / cdn_setup / cdn_cleanup — CDNライフサイクル操作
- glossary_sync — DeepL用語集を最新の状態に保つ
Jobタイプにより、細かい制御が可能です。必要なワークフローを正確にトリガーできます — 不要な処理も無駄な計算もありません。
完全な可観測性のための45以上のActivity Actions
すべてのSync Jobは進行中に構造化されたActivity Actionsを記録します。45以上の異なるアクションタイプにより、何が、いつ、なぜ起きたかの完全な画像が得られます。
典型的なSyncフローはこのActivity追跡を生成します：
SYNC_STARTED → FETCH_FILES → FILES_FETCHED → COMPARE_KEYS →
UPDATE_DATABASE → PR_GENERATION_STARTED → PR_CREATED → SYNC_COMPLETED
Activity Actionsはデバッグのためだけではありません — リアルタイムのSync状態UIを駆動し、チームがSyncのライフサイクルのどこにいるかを正確に確認できます。何か失敗した場合、最後に記録されたアクションが正確に何が問題だったかを教えてくれます。
競合検出と解決
複数のソースが同じ翻訳Keyを変更すると、競合は避けられません。Sync Engineは専用の競合検出および解決システムでこれを処理します。
競合の検出方法
すべてのSyncで、Engineは受信した変更を現在のデータベース状態と比較します。最後のSync以降にリポジトリとデータベースの両方でKeyが変更されている場合、競合としてフラグが立てられます。
競合の解決方法
競合はチームに完全なコンテキストとともに表示されます — ソース値、データベース値、および各変更のタイムスタンプです。競合を個別または一括で解決できます：
- ソースを保持 — リポジトリのバージョンを受け入れる
- データベースを保持 — 既存の翻訳を保持する
- 手動マージ — 最終値を自分で編集する
Engineは翻訳を暗黙的に上書きすることはありません。すべての競合はログに記録され、追跡され、明示的な解決が必要です。
設計による信頼性
Sync Engineはすべての層で信頼性のために構築されています：
- 耐久性のあるメッセージ配信 — Cloudflare Queuesは少なくとも1回の配信を保証します。メッセージはワーカーの再起動やインフラストラクチャの障害を乗り越えます。
- 自動リトライ — 失敗したJobは指数バックオフで再試行されます。一時的なエラー（APIタイムアウト、レート制限）は自動的に解決されます。
- 冪等操作 — すべてのメッセージハンドラーは安全に再実行できるように設計されています。リトライによって重複データが作成されることはありません。
- 順序付き処理 — プロジェクト内のメッセージは順番に処理され、関連操作間のレースコンディションを防ぎます。
- Activity Logging — すべてのステップが記録され、デバッグとコンプライアンスのための完全な監査証跡が得られます。
はじめに
GitHubリポジトリをBetter i18nに接続すると、Sync Engineはすぐに動作します。設定するものは何もありません — Sync、CDNの更新、競合検出はすべて自動的に処理されます。
より多くの制御が必要なチームのために、Sync EngineはJob レベルのAPIを公開しており、特定のワークフローのトリガー、進捗の監視、プログラムによる競合解決が可能です。