2025年6月27日·2 分
ローカリゼーションと翻訳を管理するウェブアプリの作り方
翻訳ワークフロー、ロケールデータ、レビュー、QA チェック、リリースを管理するウェブアプリを計画する。データモデル、UX、連携を含む。
翻訳ワークフロー、ロケールデータ、レビュー、QA チェック、リリースを管理するウェブアプリを計画する。データモデル、UX、連携を含む。
ローカリゼーション管理とは、プロダクトのテキスト（場合によっては画像、日付、通貨、フォーマットルール）を壊さずに翻訳、レビュー、承認、出荷する日常作業です。
プロダクトチームにとっての目標は「すべてを翻訳すること」ではなく、プロダクトの変更に合わせて各言語版を正確かつ一貫して最新に保つことです。
ほとんどのチームは良い意図で始めて混乱に陥ります：
有用なローカリゼーション管理ウェブアプリは複数の役割をサポートします：
MVP は文字列を集中管理し、ロケールごとにステータスを追跡し、基本的なレビューとエクスポートをサポートします。完成度の高いシステムは自動化（同期、QA チェック）、より豊富なコンテキスト、用語集や翻訳メモリのようなツールを追加します。
テーブルや画面を設計する前に、アプリが何を担うかを決めます。範囲を絞ることで最初のバージョンを使いやすくし、後で全て作り直す必要を減らせます。
翻訳は一箇所にしか存在しないことは稀です。初日からサポートすべきものを書き出します：
MVP では 1–2 形式 を選び、後で拡張します。一般的な選択肢は JSON, YAML, PO, CSV。実務的にはアプリ文字列用に JSON または YAML を選び、スプレッドシート依存がある場合にのみ CSV を追加するのが良いでしょう。
複数形、ネストされたキー、コメントの扱いなど要件を明確にしてください。これらはロケールファイル管理と将来のインポート/エクスポートの信頼性に影響します。
基準となるソース言語（多くは en）を定義し、フォールバック動作を設定します：
pt-BR → pt → en）。\n
また、ロケールごとに「完了」の定義（100% 翻訳済み、レビュー済み、出荷済み）を決めます。MVP では翻訳レビューと基本的な i18n ワークフロー（作成/編集、作業割り当て、レビュー、エクスポート）に集中します。
後で追加する予定の機能は スクリーンショット/コンテキスト, 用語集, 翻訳メモリの基礎, 機械翻訳の統合 などですが、コアワークフローを実データで検証するまでは作らないでください。
翻訳アプリはデータモデル次第で成功も失敗も決まります。エンティティとフィールドが明確なら、UI、ワークフロー、連携の実装が格段に簡単になります。
多くのチームは少数のテーブル/コレクションで 80% をカバーできます：
各翻訳にステータスを追加して、人間の案内をしやすくします：
draft → in_review → approved\n- レガルレビューやコンテキスト不足などで出荷すべきでない場合は blocked を使うステータス変更はイベント（または履歴テーブル）として残し、「誰がいつ承認したか」を後で答えられるようにします。
翻訳は単なるテキスト以上の情報を必要とします。次をキャプチャしてください：
{name}, %d）とソースとの整合性ルール\n- 最大文字数（ボタン等の UI 制約）\n- コンテキストノート（出現場所、意味、トーン）\n- タグ（機能領域、プラットフォーム、緊急度）最低でも created_by, updated_by, タイムスタンプ、短い change_reason を保存します。これによりレビューが早くなり、アプリに何が搭載されたかを比較するときの信頼が得られます。
ストレージの決定は編集 UX、インポート/エクスポートの速度、差分表示、出荷の確実性に影響します。
Row-per-key（キー毎に行）はダッシュボードやワークフローに向きます。フィルタで「フランス語が欠けている」や「レビューが必要」を簡単に抽出できる利点があります。欠点はエクスポート時にファイルの再構成やソートが必要になる点です。
Document-per-file（各ロケールファイルを JSON/YAML ドキュメントとして保存）はリポジトリの構造と親和性が高く、フォーマット維持が容易です。しかし検索やフィルタが難しくなるため、キーやステータスのインデックスを別に持つ必要があります。
多くのチームはハイブリッドを採用：row-per-key を真実のソースにし、エクスポート用に生成されたファイルスナップショットを保持します。
翻訳ユニットレベルのリビジョン（キー＋ロケール）を保持します。変更は前の値、新しい値、作者、タイムスタンプ、コメントを記録します。これによりレビューやロールバックが容易になります。
別に リリーススナップショット を管理します："v1.8 に実際に搭載されたもの" のように、承認済みリビジョンの一貫したセットを指すタグです。これにより、後からの編集が出荷内容を静かに変えてしまうのを防げます。
「複数形」を単純なブール値で扱わないでください。ICU MessageFormat や CLDR のカテゴリ（one, few, many, other）を使って、ポーランド語やアラビア語のような言語が英語ルールに押し込められないようにします。
性別や他のバリエーションは、同じキー（またはメッセージ）のバリアントとしてモデル化し、翻訳者が全体のコンテキストを見られるようにします。
キー、ソーステキスト、翻訳、開発者ノートに対して全文検索を実装します。現実の作業に合わせたフィルタ：status（新規/翻訳済み/レビュー済み）、tags、file/namespace、missing/empty を用意します。
これらのフィールドは早い段階でインデックス化してください—検索は毎日何百回も使われる機能です。
ローカリゼーション管理アプリは、最初はシンプルですが、製品やロケール、リリースが増えると複雑になります。柔軟にする最も簡単な方法は関心事の分離です。
一般的でスケーラブルな構成は API + Web UI + バックグラウンドジョブ + データベース：
この分割により、重い処理に対してワーカーを追加するだけで拡張できます。
開発初期に素早く動かすなら、Koder.ai のようなプロトタイピングプラットフォームで React の UI、Go の API、PostgreSQL スキーマをチャットでスキャフォールドしてからソースコードをエクスポートして本番用に移行する手もあります。
コアリソースに集中させます：
エンドポイントは人間向け編集と自動化両方をサポートするように設計します。たとえばキーの一覧は "missing in locale"、"changed since"、"needs review" のようなフィルタを受け取れるべきです。
自動化は非同期作業として扱います。典型的には：
ジョブは冪等にし、再試行が安全であること、プロジェクト毎にジョブログを残すことを心がけます。
小さなチームでも大きなデータセットを作れます。リスト（キー、履歴、ジョブ）にはページネーションを入れ、よく使う読み取りはキャッシュし（プロジェクトのロケール統計など）、インポート/エクスポートや公開トークンを保護するためにレート制限を適用します。
これらの地味な対策が、採用が進んだときにシステムが遅くなるのを防ぎます。
ソース文字列や翻訳履歴を保存するなら、アクセス制御は任意ではなく必須です。これは偶発的な編集を防ぎ、決定の追跡性を確保します。
シンプルな役割セットで多くのチームをカバーできます：
各アクションを権限として扱い、将来的に進化できるようにします。一般的なルール：
これは翻訳管理システムに自然にマッピングし、外部の契約者にも柔軟に対応できます。
Google Workspace、Azure AD、Okta を既に使っているなら SSO によりパスワードリスクを減らし、退職時のアクセス失効を即時にできます。小規模チームならメール／パスワードで十分ですが、強力なパスワードとリセットフローを必須にしてください。
HTTP-only クッキー、短寿命セッション、CSRF 保護、レート制限、可能なら 2FA を導入します。
誰がいつ何を変更したかを記録します：編集、承認、ロケール変更、エクスポート、権限更新。このログとバージョン履歴を組み合わせて "元に戻す" 機能を提供するとロールバックが安全で速くなります（詳細は /blog/plan-storage-and-versioning を参照）。
UI はローカリゼーション作業の現場です。往復作業を減らし、ステータスを一目で分かるようにする画面を優先してください。
ダッシュボードは次の 3 点に素早く答えるべきです：何が終わっているか、何が不足しているか、何がブロックされているか。
ロケールごとの進捗（翻訳率、レビュー率）、"欠落文字列" カウント、承認待ちのレビューキュー、最近の変更フィードを表示します。フィルタ（ロケール、プロダクト領域、ステータス、担当者、"前回リリース以降の変更"）はチャートより重要です。
良いエディタはサイドバイサイド：左にソース、右にターゲット、常にコンテキストが見えること。
コンテキストにはキー、スクリーンショット（ある場合）、文字数制限、プレースホルダ（例：{name}, %d）を含めます。履歴とコメントも同一ビューに入れて、翻訳者が別画面に行かなくて済むようにします。
ステータス変更はワンクリックで：Draft → In review → Approved。
ローカリゼーション作業は "多くの小さな変更" です。複数選択で担当割当、ステータス変更、ロケールやモジュール単位のエクスポート/インポートなどを実行できるようにします。
一括操作は権限で制御してください（詳細は /blog/roles-permissions-for-translators を参照）。
重労働の翻訳者はエディタを長時間使います。フルキーボードナビゲーション、フォーカス状態の可視化、次のようなショートカットを提供します：
スクリーンリーダー対応やハイコントラストモードも提供してください。アクセシビリティは全員の速度を上げます。
ローカリゼーション管理アプリはワークフローで成功するか失敗するかが決まります。次に何を翻訳すべきか、誰の決定か、何がブロックされているかが不明瞭だと遅延と品質低下を招きます。
作業単位を明確にします：特定バージョンのロケールに対するキーの集合。プロジェクトマネージャーやリードは ロケール, ファイル/モジュール, 優先度、任意で期限を指定して作業を割り当てられるようにします。
「マイワーク」受信箱で何が割り当てられているか、期限切れのものは何か、他者待ちのものは何かを表示します。大規模チーム向けに作業量シグナル（アイテム数、単語数見積もり、最終アクティビティ）を追加すると公平な割り当てができます。
シンプルなステータスパイプラインを構築します：Untranslated → In progress → Ready for review → Approved。
レビューは単なる二者択一ではありません。インラインの コメント、提案編集、承認/却下理由 をサポートします。却下された場合は履歴を残し、上書きしないでください。
これにより翻訳レビューは監査可能になり、繰り返しのミスが減ります。
ソーステキストは変わります。変更があった場合、既存の翻訳に Needs update を付けて差分や "何が変わったか" の概要を表示します。古い翻訳は参照用として残し、明示的な判断なしに再承認できないようにします。
進行を止めるイベントに対して通知します：新しい割り当て、レビュー要求、却下、期限接近、ソース変更による影響など。
通知は深いリンク（例：/projects/{id}/locales/{locale}/tasks）を含め、ワンクリックで解決に移れるようにします。
手作業によるファイル操作はローカリゼーションがずれる原因です。翻訳者が古い文字列で作業したり、開発者が更新を取り込むのを忘れ、リリースに半分しか完成していないロケールが混入します。
インポート/エクスポートは一度きりの作業ではなく、再現可能なパイプラインとして扱うべきです。
チームが実際に使うパスをサポートします：
エクスポート時は プロジェクト、ブランチ、ロケール、ステータス（例："approved only"）でフィルタできるようにして、部分的にレビューされた文字列が本番に漏れないようにします。
同期が機能するにはキーが安定している必要があります。文字列生成の方針を早めに決めてください：
checkout.button.pay_now）を使うなら、意図せぬリネームから守る。\n- ハッシュベースキーを使う場合は、ソース文字列とコンテキストを保存して、更新で重複が生じないようにする。ソース文字列が変わったがキーは同じ場合、翻訳を上書きするのではなく needs review にマークする機能が必要です。
自動同期のために Webhook を追加します：
main への新しいコミット → ソース文字列をインポート。\n- リリースタグ作成 → 承認済み翻訳をエクスポートして PR を開く。Webhook は冪等で（再試行しても安全）、何が変わったか、何がスキップされたか、理由を分かりやすくログに残すべきです。
実装するなら、最もシンプルなエンドツーエンドのセットアップ（リポジトリ権限 + Webhook + PR エクスポート）を UI から参照できるようにし、/docs/integrations へのリンクを貼って案内します。
ローカリゼーション QA は単なるエディタを超え、本番バグを防ぐ機能です。目的は、特定のロケールファイルでのみ現れる問題を出荷前に検出することです。
UI を壊したりフォーマットを崩したりするチェックから始めます：
{count} がフランス語になければエラー）\n- 無効な HTML（許可されるマークアップでの破損）\n- ファイル形式に対するエスケープ不備（JSON 内の引用符、printf スタイルの %、ICU メッセージの破損）これらはデフォルトで "リリースをブロックする" とし、該当するキーとロケールへの明確なポインタを表示します。
品質やブランド一貫性に関わるが直ちに壊れないもの：
テキストが正しくても見た目が不適切なことがあります。キーごとに スクリーンショットコンテキスト を要求できる仕組みを作るか、キーにスクリーンショットを添付して、翻訳者やレビュアーが切れや改行、トーンを UI 上で検証できるようにします。
リリース前にロケールごとの QA サマリを自動生成します：エラー、警告、未翻訳文字列、上位の問題点。
このサマリはエクスポートや内部リンク（例：/releases/123/qa）が簡単にできるようにして、チームが一つの "go/no-go" ビューを持てるようにします。
用語集、翻訳メモリ（TM）、機械翻訳（MT）はローカリゼーションを大幅に高速化しますが、アプリはそれらを "最終出力" ではなくガイダンスや補助として扱うべきです。
用語集は用語ごとにロケール別の承認翻訳を持つキュレートされたリストです。
エントリを term + locale + approved translation + notes + status として保存します。
翻訳エディタ内で用語一致をハイライトし、承認済みの訳語を提案する、あるいはプロジェクト設定で逸脱を警告/ブロックする、といった機能を追加します。変化形や小文字大文字の扱いは緩やかなルールで対応してください。
TM は以前承認された翻訳を再利用します。シンプルに保ちます：
TM は提案システムとして扱い、ユーザーが受け入れ、編集、否定できるようにします。受け入れた翻訳のみ TM にフィードバックします。
MT は草稿やバックログの処理に有効ですが、デフォルトで最終出力にするべきではありません。
プロジェクトやジョブ単位で MT をオプトインにし、MT で埋めた文字列は通常のレビュー工程を通すようにします。
チームにはそれぞれ制約があります。管理者がプロバイダを選べるようにし（あるいは MT を完全に無効化）、使用量制限を設定し、送信データ（機密キーを除外するなど）を選べるようにします。
コスト可視化と監査のためリクエストをログに残し、/settings/integrations にオプションの説明を載せます。
ローカリゼーションアプリは単に翻訳を保存するだけでなく、安全に出荷する支援をするべきです。
キーとなる考えは リリース：承認済み文字列の凍結スナップショットで、配備時に何が送られたかを再現できることです。
リリースを不変のバンドルとして扱います：
これにより「v2.8.1 の fr-FR で何を出荷したか」を確実に答えられます。
出荷前に翻訳を検証したいケースが多いです。エクスポートを環境別にモデル化します：
エクスポートのエンドポイントは明示的にし（例：/api/exports/production?release=123）、レビューされていないテキストが誤って流出するのを防ぎます。
リリースが不変であればロールバックは容易です。問題が起きたら：
"本番で直接編集する" のは避けてください—監査トレイルが壊れ、インシデント解析が困難になります。
Koder.ai のようなプラットフォームはスナップショットとロールバックをファーストクラスワークフローとして扱っており、この不変のリリース思考はローカリゼーション設計にも有効です。
デプロイ後は小さな運用チェックを行います：
UI にリリース履歴を表示するなら、前回リリースとの差分ビューを付けてリスクの高い変更を素早く発見できるようにします。
セキュリティと可視性は、使えるツールと信頼されるツールの差です。ワークフローが安定したらロックダウンし、計測を始めます。
最小権限の原則をデフォルトに：翻訳者がプロジェクト設定を変えられない、レビュアーが請求情報にアクセスできない等。役割を明確にし、監査可能にします。
秘密情報は安全に保存します。データベース資格情報、Webhook 署名鍵、サードパーティトークンはシークレットマネージャや暗号化環境変数に保管し、リポジトリに置かないでください。人が退職したら鍵のローテーションを行います。
バックアップは必須です。データベースやオブジェクトストレージ（ロケールファイル、添付）を自動でバックアップし、リストアをテストし、保持期間を定義します。"復元できないバックアップ" は単なる無駄なストレージです。
文字列にユーザー生成コンテンツ（サポートチケット、名前、住所など）が含まれうる場合、翻訳システムに直接保存しない方が良いです。プレースホルダや参照を使い、ログからは機密値を削除します。
どうしても処理する必要があるなら、保持ルールとアクセス制限を定義します。
ワークフローの健全性を示す数件の指標を追いましょう：
シンプルなダッシュボードと CSV エクスポートで十分に役立ちます。
基盤が安定したら検討する項目：
これをプロダクトとして提供する予定があれば、明確なアップグレードパスと CTA（例：/pricing）を用意します。
即座にワークフローを実ユーザーで検証したいなら、Koder.ai で MVP をプロトタイプするのも有効です：ロール、ステータスフロー、インポート/エクスポート形式を設計モードで記述し、チャットを通じて React UI と Go API を反復し、準備ができたらコードベースをエクスポートして本格運用に移せます。
ローカリゼーション管理ウェブアプリは、文字列を一元化し、それらの翻訳、レビュー、承認、エクスポートにまつわるワークフローを管理します。これにより、壊れたキー、欠落したプレースホルダ、不明瞭なステータスが原因でリリースが失敗するリスクを減らせます。
まず次を明確にします：
pt-BR → pt → en）範囲を絞ることで「すべてに一律のワークフロー」になる失敗を防ぎ、MVP を実用的に保てます。
多くのチームは次のエンティティでコアワークフローをカバーできます：
本番の間違いを防ぐために保存すべきメタデータ：
目的に応じて選びます：
多くのチームはハイブリッドを採用します：row-per-key を真実のソースにし、エクスポート用に生成されたファイルスナップショットを持つ方式です。
2 層構成を推奨します：
実務に則した役割を用意します：
将来的に柔軟にするため、アクション単位でのパーミッション設計をおすすめします（例：誰がソースを編集できるか、誰が承認できるか、など）。
API は主要リソースを中心に設計します：
Projects、Locales、Keys、Translationsリスト取得エンドポイントは実務的なフィルタを受け取れるようにします：
初期に用意すべき非同期ジョブ：
ジョブは**冪等（idempotent）**にして再試行可能にし、プロジェクト単位でログを残して自己診断しやすくします。
出荷をブロックすべきチェック優先度：
{count}, %d など）や複数形の未対応これらはデフォルトでリリースブロッキングにし、用語集の不一致や空白・句読点の問題はソフトな警告として扱うとバランスが良いです。
en, en-GB, pt-BR）。\n- Key：コードで使う安定した識別子（例：checkout.pay_button）。\n- Source string：キーに紐づく参照テキスト（基準言語）。\n- Translation：キー＋ロケールに対するローカライズされた値。\n- Version：リリース、インポート、ファイル改訂のスナップショット。\n
関係性を明示的にモデル化します：Project は複数の Locales を持ち、Key は Project に属し、Translation は Key と Locale に属します。draft → in_review → approved）これらが整理されていれば、UI、権限、連携はずっと作りやすくなります。
{name}, %d）とソースとの一致ルールcreated_by, updated_by, タイムスタンプ、変更理由）これらがあることで「単なるテキストエディタ」ではなく、チームが信頼できるシステムになります。
これにより UI と CLI/CI の自動化双方をサポートできます。