多言語辞書の一元管理アーキテクチャ設計
イベント・アクション・コンポーネント名の多言語辞書を notes で一元管理し、engine から抽出 → 差分チェック → 試作確認 → parlourite 同期のフローを設計。
多言語辞書の一元管理アーキテクチャ設計
1. 目的
以下の用途で 同じ語彙 を使いたい:
| 用途 | 例 |
|---|---|
| イベントソーシング | draw_cards → “カードを引いた” |
| UI アクション | end_turn → “ターン終了” |
| マニュアル生成 | gain_resource → “{resource}を{amount}得る” |
| ログ表示 | place_worker → “ワーカーを配置” |
| コンポーネント名 | PlayerHand → “手札” |
一元管理 により:
- 表記ゆれ防止
- 翻訳漏れ検出
- 新構文追加時の対応漏れ防止
2. SSOT の配置
engine (構文定義の源流) │ ▼ 抽出notes/src/tools/dict/ (SSOT: 翻訳管理) │ ▼ syncparlourite/src/dict/ (コピー: 参照のみ)| レイヤー | 役割 | 編集 |
|---|---|---|
| engine | 構文の定義元(effect / action / command) | 開発時 |
| notes | 翻訳テキストの管理 | 人間が編集 |
| parlourite | 実行時に参照 | 編集しない |
3. ディレクトリ構成
notes/├── src/tools/dict/│ ├── schema.ts # 型定義│ ├── effects.yaml # イベント/エフェクト│ ├── actions.yaml # UI アクション│ ├── commands.yaml # コマンド│ ├── components.yaml # コンポーネント名(フォールバック)│ └── _extracted/ # 機械生成(git 管理、編集しない)│ ├── effects.yaml│ ├── actions.yaml│ └── commands.yaml├── scripts/│ ├── extract-dict-terms.mjs # engine から抽出│ └── check-dict-diff.mjs # 差分チェック4. YAML スキーマ
4-1. 基本構造
_meta: version: 1 extracted_from: "engine@commit:abc1234" extracted_at: "2026-10-19T02:00:00Z"
draw_cards: en: "Draw {count} {count|card|cards}" ja: "{count}枚引く" params: count: number
discard: en: "Discard {target}" ja: "{target}を捨てる" params: target: string
gain_resource: en: "Gain {amount} {resource}" ja: "{resource}を{amount}得る" params: amount: number resource: string4-2. 複数形の記法
ICU MessageFormat 簡易版:
{count|card|cards} ↓count === 1 → "card"count !== 1 → "cards"日本語は複数形がないためそのまま。
4-3. TypeScript 型定義
export interface DictEntry { en: string; ja: string; params?: Record<string, 'string' | 'number' | 'boolean'>;}
export interface DictMeta { version: number; extracted_from?: string; extracted_at?: string;}
export interface DictFile { _meta: DictMeta; [key: string]: DictEntry | DictMeta;}5. 抽出スクリプト
5-1. 調査が必要な点
| 項目 | 候補 |
|---|---|
| 抽出対象ファイル | effects.ts / dsl/parser.ts / 定数配列 |
| パース方法 | TypeScript AST / 正規表現 / エクスポート定数 |
| CI 自動実行 | engine 変更時に自動抽出するか |
5-2. スクリプト雛形
import { writeFileSync } from 'fs';import { resolve } from 'path';import { stringify } from 'yaml';
// TODO: engine のパスと抽出ロジックは調査後に実装const ENGINE_PATH = '../parlourite/packages/engine';
async function extractEffects() { // 調査後に実装: // - TypeScript AST から Effect union を抽出 // - または構文定義ファイルをパース // - またはエクスポートされた定数配列を読む
const effects = []; // 抽出結果
return Object.fromEntries( effects.map(name => [name, { en: '', ja: '', params: {} }]) );}
async function main() { const effects = await extractEffects(); const actions = await extractActions(); const commands = await extractCommands();
const outDir = resolve('src/tools/dict/_extracted'); const meta = { version: 1, extracted_from: `engine@commit:${getGitCommit(ENGINE_PATH)}`, extracted_at: new Date().toISOString(), };
writeFileSync( resolve(outDir, 'effects.yaml'), stringify({ _meta: meta, ...effects }) ); // actions, commands も同様}
function getGitCommit(dir) { // git rev-parse HEAD を実行}
main();6. 差分チェックスクリプト
import { readFileSync } from 'fs';import { parse } from 'yaml';
const CATEGORIES = ['effects', 'actions', 'commands'];
function loadYaml(path) { return parse(readFileSync(path, 'utf-8'));}
function checkCategory(name) { const extracted = loadYaml(`src/tools/dict/_extracted/${name}.yaml`); const manual = loadYaml(`src/tools/dict/${name}.yaml`);
const extractedKeys = Object.keys(extracted).filter(k => k !== '_meta'); const manualKeys = Object.keys(manual).filter(k => k !== '_meta');
const missing = extractedKeys.filter(k => !manualKeys.includes(k)); const unused = manualKeys.filter(k => !extractedKeys.includes(k)); const matched = extractedKeys.filter(k => manualKeys.includes(k));
const untranslated = matched.filter(k => !manual[k].en || !manual[k].ja );
return { missing, unused, matched, untranslated };}
function main() { let hasError = false;
for (const cat of CATEGORIES) { const { missing, unused, matched, untranslated } = checkCategory(cat);
console.log(`\n=== ${cat} ===`);
if (missing.length) { console.log(`\n❌ Missing (add to ${cat}.yaml):`); missing.forEach(k => console.log(` + ${k}`)); hasError = true; }
if (unused.length) { console.log(`\n⚠️ Unused (maybe remove):`); unused.forEach(k => console.log(` - ${k}`)); }
if (untranslated.length) { console.log(`\n⚠️ Untranslated:`); untranslated.forEach(k => console.log(` ? ${k}`)); }
console.log(`\n✅ Matched: ${matched.length} terms`); }
process.exit(hasError ? 1 : 0);}
main();7. parlourite 側での使用
7-1. 翻訳関数
import effects from './effects.yaml';import actions from './actions.yaml';import commands from './commands.yaml';import components from './components.yaml';
type Lang = 'en' | 'ja';type Category = 'effects' | 'actions' | 'commands' | 'components';
const dicts = { effects, actions, commands, components };
export function t( category: Category, key: string, lang: Lang = 'ja', params?: Record<string, string | number>): string { const entry = dicts[category]?.[key];
if (!entry || entry === dicts[category]._meta) { console.warn(`Missing dict entry: ${category}.${key}`); return formatKey(key); }
let text = entry[lang] || entry.en || key;
if (params) { text = interpolate(text, params); }
return text;}
function interpolate( text: string, params: Record<string, string | number>): string { return text.replace(/\{(\w+)(?:\|([^|]+)\|([^}]+))?\}/g, (_, key, singular, plural) => { const value = params[key]; if (singular && plural) { return value === 1 ? singular : plural; } return String(value ?? key); } );}
function formatKey(key: string): string { return key .replace(/_/g, ' ') .replace(/\b\w/g, c => c.toUpperCase());}7-2. 使用例
t('effects', 'draw_cards', 'en', { count: 1 })// → "Draw 1 card"
t('effects', 'draw_cards', 'en', { count: 3 })// → "Draw 3 cards"
t('effects', 'draw_cards', 'ja', { count: 2 })// → "2枚引く"
t('actions', 'end_turn', 'ja')// → "ターン終了"
t('effects', 'unknown_effect', 'ja')// → "Unknown Effect" (警告ログ出力)8. コンポーネント名のフォールバック戦略
コンポーネント名は ゲーム定義側 で決まることが多い。
優先順位
1. ゲーム定義の dict.yaml(ゲーム固有の名前)2. 共通辞書の components.yaml(汎用コンポーネント)3. キーを整形して表示(最終フォールバック)配置場所
parlourite/├── games/{slug}/dict.yaml # ゲーム固有└── src/dict/components.yaml # 共通実装
export function tComponent( key: string, lang: Lang = 'ja', gameDict?: Record<string, DictEntry>): string { // 1. ゲーム固有 if (gameDict?.[key]?.[lang]) { return gameDict[key][lang]; }
// 2. 共通辞書 if (components[key]?.[lang]) { return components[key][lang]; }
// 3. フォールバック return formatKey(key);}9. rulebook-gen 管理者表示の拡張
9-1. 追加する表示機能
| 機能 | 説明 |
|---|---|
| イベント一覧 | 全 effect の key / en / ja を表形式で表示 |
| コマンド一覧 | 全 command の key / en / ja を表形式で表示 |
| コンポーネント一覧 | 全 component の key / en / ja を表形式で表示 |
| 未翻訳ハイライト | en/ja が空のエントリを警告色で強調 |
| パラメータ表示 | 各エントリの params を展開表示 |
| フィルター | キーワードで絞り込み |
9-2. 実装
import type { DictFile, DictEntry } from '../dict/schema';
export function renderDictTable( dict: DictFile, category: string): string { const entries = Object.entries(dict) .filter(([k]) => k !== '_meta') as [string, DictEntry][];
const rows = entries.map(([key, entry]) => { const enClass = entry.en ? '' : 'class="warn"'; const jaClass = entry.ja ? '' : 'class="warn"'; const en = entry.en || '⚠️ empty'; const ja = entry.ja || '⚠️ empty'; const params = entry.params ? Object.entries(entry.params) .map(([k, v]) => `${k}: ${v}`) .join(', ') : '-';
return ` <tr data-key="${key}"> <td><code>${key}</code></td> <td ${enClass}>${escapeHtml(en)}</td> <td ${jaClass}>${escapeHtml(ja)}</td> <td><small>${params}</small></td> </tr> `; }).join('');
return ` <div class="dict-admin"> <input type="text" class="dict-filter" placeholder="Filter by key..." onInput="filterDictTable(this)"> <table class="dict-table"> <thead> <tr> <th>Key</th> <th>English</th> <th>日本語</th> <th>Params</th> </tr> </thead> <tbody>${rows}</tbody> </table> </div> `;}
function escapeHtml(str: string): string { return str .replace(/&/g, '&') .replace(/</g, '<') .replace(/>/g, '>');}9-3. 本番での除外
管理者 UI は dev ビルドのみに含める:
export default defineConfig(({ mode }) => ({ build: { rollupOptions: { input: mode === 'development' ? ['index.html', 'admin.html'] : ['index.html'] } }}));10. 運用フロー
# 1. engine から抽出(engine 更新後に実行)node scripts/extract-dict-terms.mjs
# 2. 差分チェックnode scripts/check-dict-diff.mjs
# 3. 不足分を手動で追加(翻訳)# src/tools/dict/*.yaml を編集
# 4. 試作確認(rulebook-gen の管理者表示)open public/tools/rulebook-gen/admin.html
# 5. parlourite に同期cd ../parlourite && node scripts/sync.mjs --include dict11. 未決定事項
| 項目 | 状態 | 次のアクション |
|---|---|---|
| engine の抽出元 | 要調査 | engine のコード構造を確認 |
| params の型推論 | 要検討 | TypeScript AST から抽出できるか調査 |
| 言語追加 | 未着手 | zh / ko 等を追加する場合のスキーマ拡張 |
| CI 自動抽出 | 未決定 | engine 変更時に hook で実行するか |
12. 実装優先度
| # | タスク | 依存 | 見積もり |
|---|---|---|---|
| 1 | schema.ts 作成 | なし | 30min |
| 2 | 初期 YAML 作成(手動) | #1 | 2h |
| 3 | check-dict-diff.mjs 実装 | #2 | 1h |
| 4 | engine 抽出元の調査 | なし | 2h |
| 5 | extract-dict-terms.mjs 実装 | #4 | 2h |
| 6 | 36-render-dict-admin.ts 実装 | #2 | 2h |
| 7 | parlourite 側 t() 関数実装 | #2 | 1h |