i18n 国际化系统

概述

EnderRealm 使用集中化 i18n 系统管理所有多语言文本。文本存储在 PostgreSQL 数据库中，通过 Python API 端点提供服务，Java 核心模块从 API 同步并缓存到内存。

架构

┌─────────────────────────────────────────────────────────────┐
│                     PostgreSQL                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  i18n_texts (key, zh_cn, zh_tw, en_us, ja, ru)       │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│              EnderRealmServerApi (Python)                     │
│  GET /v1/i18n/          → 全量数据 + 时间戳                   │
│  GET /v1/i18n/latest    → 仅返回时间戳                        │
│  CRUD /v1/i18n/keys/    → 管理端点                            │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│            EnderRealmServerCore (Java)                        │
│  LanguageService: 启动时全量拉取，每小时检查时间戳             │
│  EnderRealmServerCore.getLanguageAPI()                        │
└──────────────────────────────┬───────────────────────────────┘
                               │
           ┌───────────────────┼───────────────────┐
           ▼                   ▼                   ▼
       bedwars             disaster         BlockedInCombat

数据库表结构

CREATE TABLE i18n_texts (
    key    VARCHAR(255) PRIMARY KEY,  -- 文本标识符
    zh_cn  TEXT,                       -- 简体中文
    zh_tw  TEXT,                       -- 繁体中文
    en_us  TEXT,                       -- 英语
    ja     TEXT,                       -- 日语
    ru     TEXT                        -- 俄语
);

API 端点

方法	路径	说明
GET	/v1/i18n/	全量获取 { timestamp, texts }
GET	/v1/i18n/latest	仅返回 { timestamp }
GET	/v1/i18n/keys	列出所有 key
GET	/v1/i18n/keys/{key}	获取单条
POST	/v1/i18n/keys	创建
PUT	/v1/i18n/keys/{key}	更新
DELETE	/v1/i18n/keys/{key}	删除

所有端点需要 API Key 认证：Authorization: Bearer <api_key>

Java API 使用方式

获取 LanguageAPI

LanguageAPI lang = EnderRealmServerCore.getLanguageAPI();

获取文本

// 基本用法
String text = lang.getText("bedwars.team.red", player);

// 带占位符
String text = lang.getText("stage.player.join-message", player, playerName, count, max);

// 获取列表文本（用 \n 分隔的多行文本）
List<String> lines = lang.getTextList("disaster.scoreboard.items", player);

回退机制

获取文本时按以下顺序回退：

1. 用户语言（如 ja_jp）
2. 英语 en_us
3. 返回原始 key

语言代码映射

Minecraft 语言代码	数据库字段名
zh_CN	zh_cn
zh_TW	zh_tw
en_US	en_us
ja_JP	ja
ru_RU	ru

同步机制

• Java 端：启动时全量拉取，之后每小时检查 /v1/i18n/latest 时间戳
• 时间戳相同：跳过同步
• 时间戳不同：全量拉取更新缓存
• Python 端：启动时加载数据库，每小时重建缓存

迁移工具

将现有 YML 语言文件导入数据库：

命令行版

python scripts/i18n_migrate.py

GUI 版

python scripts/i18n_migrate_gui.py

支持拖拽 YML 文件、冲突检测、生成可重复执行的 SQL。

添加新文本

1. 通过 API 端点 POST /v1/i18n/keys 添加
2. 或通过迁移脚本导入 YML 文件
3. Java 端会在下次同步时自动获取