この記事はCommune Advent Calendar 2024、シリーズ2の24日目の記事です。
Frontend Techleadの野口です。
今回の記事をフルで読むと、
InternationalizationをObject-Oriented User InterfaceでDemocratizationする
です。(長すぎ)
前回の振り返り
前回の記事では、CSVファイルによるi18n辞書の一元管理について解説しました。具体的な実装方法として
- CSVによる階層的なキー構造の管理
- 各種i18nライブラリへの自動変換の仕組み
- VRTを活用した変更管理プロセス
を紹介しました。
本記事では、その技術基盤の上に構築する、より本質的なアプローチとして、Object-Oriented UI（OOUI）による文言管理の考え方を解説します。
😫 よくある国際化対応の課題
多くの開発チームが直面する国際化の悩み：
- 文言キーの命名規則が属人的
- デザイナーとエンジニアの会話が噛み合わない
- 翻訳漏れや重複が頻発
- モデルの変更が文言管理に波及
- 新メンバーの学習コストが高い
前回導入したCSV管理の仕組みは、これらの課題に対する技術的な解決策を提供しましたが、より本質的な解決には、設計思想レベルでのアプローチが必要です。
💡 OOUIによる解決アプローチ
Object-Oriented UIの考え方をi18n管理に適用することで、前回実装したCSV管理の仕組みをより効果的に活用できます。
キー設計の基本
key,ja-JP,en-US,context
user.id,ユーザーID,User ID,ユーザー識別子
user.name,ユーザー名,Username,表示用の名前
user.email,メールアドレス,Email Address,連絡先として使用
user.status.active,有効,Active,アカウントの状態
このUIキー設計は、前回実装したCSV管理の仕組みと完全に整合し、以下の特徴を持ちます：
- モデル名をプレフィックスに
- 属性名を直接反映
- 階層的な構造化
- contextカラムによる使用意図の明確化
🎯 このアプローチで得られる3つの価値
1. デザイナー×エンジニアのシームレスな協業
コミュニケーションの改善
Before:
デザイナー「ユーザー画面のこの部分の文言を変更したいです」
エンジニア「どのファイルのどの部分でしょうか...」
After:
デザイナー「user.email.placeholderを更新しました」
エンジニア「プルリクエスト確認しました。VRTでの変更確認も完了したのでマージします」
この協業体制は、前回実装した以下の機能によってサポートされます：
- CSVファイルの直接編集
- VRTによる変更確認
- CIでの自動変換
2. 自然と生まれる共通言語（ユビキタス言語）
key,ja-JP,en-US,context
order.status.pending,受付中,Pending,注文の初期状態
order.status.confirmed,確認済み,Confirmed,担当者確認完了
order.status.shipping,発送中,Shipping,配送業者に引き渡し済み
ドメインモデルとCSVの構造を一致させることで：
- ビジネスロジックとUIの用語が自然に統一
- 新入社員のオンボーディングが容易に
- 部門間のコミュニケーションが円滑に
3. スケーラブルな文言管理
前回実装したCSV管理の仕組みを基盤として：
- 新機能追加時の命名規則が明確
- 既存の構造を参考に誰でも追加可能
- レビューと変更管理が容易
大規模プロジェクトでのスケーリング
CSVファイルの分割による管理も可能です：
# products/catalog.csv
key,ja-JP,en-US,context
product.name,商品名,Product Name,商品一覧での表示
product.description,商品説明,Description,商品詳細ページのメイン説明文
product.price,価格,Price,商品一覧と詳細での表示
# users/profile.csv
key,ja-JP,en-US,context
user.profile.name,名前,Name,プロフィール表示用
user.profile.bio,自己紹介,Biography,プロフィールページの説明
このアプローチには以下のトレードオフがあります：
メリット：
- 関連する文言をコンテキストごとに整理可能
- チーム間での並行作業が容易に
- 各ファイルの責任範囲が明確
デメリット：
- ファイル間の文言重複の可能性
- 文言の検索・参照時の手間が増加
- ファイル構成の設計・維持にコストが必要
🚀 実践投入のステップ
1. ドメインモデル理解のためのワークショップ
プロジェクトの成功には、チーム全体でのドメインモデルの理解が不可欠です。以下のようなワークショップを実施することを推奨します：
ワークショップの構成（半日〜1日）
-
ドメインの全体像の共有 (1-2時間)
- プロダクトオーナーによるビジネスの説明
- 主要なユースケースの確認
- 既存のモデル構造の説明
-
モデル分析グループワーク (2-3時間)
- 3-4人のグループに分かれる
- 各機能領域のモデル抽出
- 属性の洗い出しとグルーピング
- UI要素との対応付け
-
全体での共有と整理 (1-2時間)
- グループ間での発見の共有
- モデル間の関係性の整理
- 命名規則の検討と決定
- 次のステップの確認
ワークショップのポイント
- デザイナー、エンジニア、プロダクトオーナーが必ず参加
- 具体的なUI画面を見ながらモデルを検討
- 議論の内容をドキュメント化
- 定期的な振り返りの機会を設定
2. 新ルールの策定
# 基本ルール例
モデル名.属性名
モデル名.属性名.種類
モデル名.状態.値
3. 段階的な移行
- 新規機能から適用
- 既存機能は計画的に移行
- 前回実装した変換スクリプトの活用
🎁 波及効果とさらなる可能性
ドメイン駆動設計の実践
ドメインモデルに基づいたキー設計を行うことで、自然とドメイン駆動設計の実践につながりました。UIの文言がドメインの概念を正確に反映するため、ビジネスロジックとUIの一貫性が向上します。
他チームへの展開
キー設計の規則が明確で理解しやすいため、他チームへの展開がスムーズに進みました。同じアプローチを採用することで、プロジェクト間での知見の共有も容易になります。
組織の共通言語
文言キーがドメインモデルを反映することで、自然と組織の共通言語として機能するようになりました。異なる部門間でも、同じ用語で議論できるようになります。
ドキュメントとの統合
一貫したキー構造は、仕様書やドキュメントの作成時にも活用できます。UIの文言とドキュメントで同じ用語を使用することで、より明確なコミュニケーションが可能になります。
📝 まとめ
前回実装したCSV管理の仕組みをベースに、OOUIの考え方を導入することで：
- 🤝 チームコラボレーションの改善
- 📚 ドメイン知識の共有
- ⚡ 開発効率の向上
- 🌍 スケーラブルな国際化対応
を実現できました。
なお、今回はCSVでの実装例を紹介しましたが、このキー設計のアプローチ自体は、JSONやYAML、データベースなど、様々な形式で実現可能です。重要なのは、一貫したキー構造とドメインモデルとの整合性を保つことです。課題はまだ残っていますが、一つの有効なアプローチとして、皆様のプロジェクトの参考になれば幸いです。
ご質問やご意見がありましたら、コメント欄でお待ちしています。
Discussion