log

多言語辞書の一元管理アーキテクチャ設計

イベント・アクション・コンポーネント名の多言語辞書を notes で一元管理し、engine から抽出 → 差分チェック → 試作確認 → parlourite 同期のフローを設計。

多言語辞書の一元管理アーキテクチャ設計

1. 目的

以下の用途で 同じ語彙 を使いたい:

用途例
イベントソーシングdraw_cards → “カードを引いた”
UI アクションend_turn → “ターン終了”
マニュアル生成gain_resource → “{resource}を{amount}得る”
ログ表示place_worker → “ワーカーを配置”
コンポーネント名PlayerHand → “手札”

一元管理 により:

  • 表記ゆれ防止
  • 翻訳漏れ検出
  • 新構文追加時の対応漏れ防止

2. SSOT の配置

engine (構文定義の源流)
│
▼ 抽出
notes/src/tools/dict/ (SSOT: 翻訳管理)
│
▼ sync
parlourite/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. 基本構造

effects.yaml
_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: string

4-2. 複数形の記法

ICU MessageFormat 簡易版:

{count|card|cards}
↓
count === 1 → "card"
count !== 1 → "cards"

日本語は複数形がないためそのまま。

4-3. TypeScript 型定義

schema.ts
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. スクリプト雛形

scripts/extract-dict-terms.mjs
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. 差分チェックスクリプト

scripts/check-dict-diff.mjs
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. 翻訳関数

parlourite/src/dict/index.ts
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. 実装

src/tools/rulebook-gen/js/36-render-dict-admin.ts
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, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;');
}

9-3. 本番での除外

管理者 UI は dev ビルドのみに含める:

vite.config.ts
export default defineConfig(({ mode }) => ({
build: {
rollupOptions: {
input: mode === 'development'
? ['index.html', 'admin.html']
: ['index.html']
}
}
}));

10. 運用フロー

Terminal window
# 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 dict

11. 未決定事項

項目状態次のアクション
engine の抽出元要調査engine のコード構造を確認
params の型推論要検討TypeScript AST から抽出できるか調査
言語追加未着手zh / ko 等を追加する場合のスキーマ拡張
CI 自動抽出未決定engine 変更時に hook で実行するか

12. 実装優先度

#タスク依存見積もり
1schema.ts 作成なし30min
2初期 YAML 作成(手動)#12h
3check-dict-diff.mjs 実装#21h
4engine 抽出元の調査なし2h
5extract-dict-terms.mjs 実装#42h
636-render-dict-admin.ts 実装#22h
7parlourite 側 t() 関数実装#21h