目次
APIファースト・ローカライゼーション：翻訳を開発ワークフローに組み込む
主なポイント
- APIファースト・ローカライゼーションは、手動のファイルのやり取りを、コードベースと翻訳管理システム間の自動同期に置き換える
- CLIツールとCI/CD統合により、デプロイのたびに翻訳を同期し続けるpush/pullワークフローが実現する
- Webhookベースの通知は、翻訳が更新されたときにビルドをトリガーし、継続的なローカライゼーションを可能にする
- APIファーストのアプローチにより、新しい言語の市場投入時間が数週間から数時間に短縮される
APIファースト・ローカライゼーションとは？
APIファースト・ローカライゼーションとは、翻訳管理システム（TMS）がREST API、CLIツール、Webhookを通じてすべての翻訳ワークフローへのプログラマティックなアクセスを提供するアプローチです。翻訳ファイルを手動でエクスポート・インポートする代わりに、開発者はビルドおよびデプロイパイプラインに翻訳同期を直接統合します。
従来のワークフローとAPIファーストの比較
従来（ファイルベース）
- 開発者がソース文字列をファイル（JSON、XLIFFなど）にエクスポートする
- ファイルをTMSにアップロードするか、メールで翻訳者に送る
- 翻訳されたファイルが数日〜数週間後に返ってくる
- 開発者がファイルをダウンロードして適切なディレクトリに配置する
- 開発者がコミットしてデプロイする
問題点： 手動の手順、バージョンのずれ、マージの競合、遅いサイクルタイム。
APIファースト
- 開発者がCLIで新しい文字列をプッシュする：
better-i18n push - TMSが翻訳者に新しいコンテンツを通知する
- 翻訳者はTMSエディターで完全なコンテキストを持って作業する
- 翻訳が完了するとWebhookがCI/CDをトリガーする
- ビルドが最新の翻訳を取得する：
better-i18n pull - デプロイメントに更新された翻訳が自動的に含まれる
メリット： 手動のファイル操作が不要、継続的な同期、より速いサイクルタイム。
APIファースト・ローカライゼーションのコアコンポーネント
REST API
TMS APIは以下のエンドポイントを提供します：
POST /api/keys — 新しい翻訳キーを作成する GET /api/translations — ロケールの翻訳を取得する PUT /api/translations — 翻訳を更新する GET /api/projects — プロジェクトとその状態を一覧表示する POST /api/upload — ソースファイルをアップロードする GET /api/download — 翻訳済みファイルをダウンロードする
CLIツール
開発者の利便性のためにAPIをラップするコマンドラインツール：
# 新しいソース文字列をTMSにプッシュする better-i18n push # 最新の翻訳を取得する better-i18n pull --locale=de,fr,ja # 翻訳のステータスを確認する better-i18n status # 未翻訳の文字列をコードベースからスキャンする better-i18n scan
Webhook
翻訳が変更されたときのイベント駆動型通知：
{
"event": "translations.completed",
"project": "my-app",
"locale": "de",
"completed_keys": 142,
"total_keys": 142
}
Webhookを使ってCI/CDパイプライン、Slack通知、または自動デプロイをトリガーしましょう。
CI/CD統合
ビルドパイプラインに翻訳同期を統合する：
# GitHub Actionsの例
- name: Pull translations
run: better-i18n pull --all
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Build
run: npm run build
APIファースト・ローカライゼーションのメリット
| メリット | 効果 |
|---|---|
| 自動同期 | 手動のファイル管理が不要 |
| バージョン管理 | 翻訳をコードと並行して追跡 |
| 継続的デリバリー | 新しい翻訳がデプロイのたびにリリースされる |
| 開発者体験 | 使い慣れたCLI/APIワークフロー |
| 市場投入の迅速化 | 新しい言語が数週間ではなく数時間で対応可能 |
| エラーの削減 | ファイルフォーマットの問題や配置ミスが発生しない |
実装パターン
パターン1：ビルド時Pull
ビルドステップ中に翻訳を取得する。翻訳はビルド時にアプリにバンドルされる。
最適な用途： 静的サイト、プリレンダリングされたページ、モバイルアプリ。
パターン2：ランタイムFetch
実行時にAPIから翻訳を取得する。再デプロイなしで即時更新が可能。
最適な用途： SPA、動的Webアプリ、リアルタイムコンテンツ。
パターン3：ハイブリッド
初回ロード用にビルド時に翻訳を取得し、ホットフィックス用に実行時に更新を取得する。
最適な用途： パフォーマンスと柔軟性の両方が必要な本番アプリ。
よくある質問
APIファースト・ローカライゼーションを使用するためにファイル形式を変更する必要がありますか？ いいえ。ほとんどのAPIファーストTMSプラットフォームは標準形式（JSON、XLIFF、YAML、.strings、.xml）をサポートしており、フォーマット変換を自動的に処理します。
名前が変更または削除された翻訳キーはどのように扱いますか？ CLIのscanコマンドが未使用のキーを検出します。APIエンドポイントはキーの一括操作を可能にします。ほとんどのTMSプラットフォームはキーのライフサイクルを追跡し、孤立した翻訳にフラグを立てます。
ビルド中にAPIがダウンした場合はどうなりますか？ キャッシュされた翻訳をフォールバックとして使用してください。APIにアクセスできない場合でもビルドが常にベースラインを持てるよう、最後に成功したpullをバージョン管理に保存しておきましょう。
複数の環境の翻訳はどのように管理しますか？ プロジェクトレベルまたはブランチレベルのネームスペースを使用してください。一部のTMSプラットフォームは、同じプロジェクトに対して環境固有のオーバーライド（ステージング、本番）をサポートしています。
APIファースト・ローカライゼーションは小規模プロジェクトに適していますか？ はい。CLIのpush/pullワークフローは、数百の文字列を持つプロジェクトでも手動のファイル管理よりもシンプルです。API統合のセットアップにかかるオーバーヘッドは、節約できる時間と比べると最小限です。
