i18n.md

Documentation

---

国际化

配置启用的语言

在入口文件中通过 setEnabledLanguages 指定当前应用支持的语言列表：

import { translator } from "sapi-pro";

translator.setEnabledLanguages(["en_US", "zh_CN", "zh_TW", "ja_JP", "ko_KR"]);

默认语言列表

若不配置，将默认启用以下 8 种语言：

["zh_CN", "zh_TW", "en_US", "ja_JP", "fr_FR", "pt_BR", "ko_KR", "es_ES"];

定义语言文本结构

使用 defineLangTree 函数以 对象结构 形式定义多语言文本。

💡 设计说明
sapi-pro 摒弃了传统的字符串键方式，采用对象映射结构，可直接利用 IDE 的跳转定义与自动补全功能，大幅提升开发体验与可维护性。

import { defineLangTree } from "sapi-pro";

export const LangUIText = defineLangTree({
    title: {
        zh_CN: "语言设置",
        zh_TW: "語言設定",
        en_US: "Language Settings",
        ja_JP: "言語設定",
        fr_FR: "Paramètres de langue",
        de_DE: "Spracheinstellungen",
        es_ES: "Configuración de idioma",
        ko_KR: "언어 설정",
    },
    dropdown_label: {
        zh_CN: "选择语言",
        zh_TW: "選擇語言",
        en_US: "Select Language",
        ja_JP: "言語を選択",
        fr_FR: "Choisir la langue",
        de_DE: "Sprache auswählen",
        es_ES: "Seleccionar idioma",
        ko_KR: "언어 선택",
    },
    confirm: {
        zh_CN: "确认",
        zh_TW: "確認",
        en_US: "Confirm",
        ja_JP: "確認",
        fr_FR: "Confirmer",
        de_DE: "Bestätigen",
        es_ES: "Confirmar",
        ko_KR: "확인",
    },
});

实现翻译

为指定玩家创建临时的翻译函数 t：

import { translator } from "sapi-pro";

const t = translator.createFor(player);

调用 t(默认文本, 语言对象) 完成翻译：

const form = new ModalFormData()
    .title(t("语言设置", LangUIText.title))
    .dropdown(t("选择语言", LangUIText.dropdown_label), enabledLanguages, {
        defaultValueIndex: curIndex,
    })
    .submitButton(t("确认", LangUIText.confirm));

📌 关于默认文本
翻译函数要求显式传入默认文本（如 "语言设置"），目的是增强代码可读性。对于中文开发者而言，直观的汉字占位符可让代码逻辑一目了然，无需频繁跳转查看语言文件。

也可以使用translator.createPureFor以创建不使用默认文本的翻译函数

内置语言选择表单

sapi-pro 提供了现成的语言设置表单，可直接调用：

import { LangSettingForm } from "sapi-pro";

formManager.open(player, LangSettingForm);

内置语言选择命令

sapi-pro 提供了 langCmd 命令对象，需要手动使用 pcommand 注册后，玩家才可通过命令交互式切换语言：

import { langCmd, pcommand } from "sapi-pro";

pcommand.registerCommand(langCmd);

注册后，在游戏中输入 .lang 即可使用。

表单中的使用

CommonForm已全面升级以支持多语言，表单文本支持传入string|LangText|RawMessage

例如:

const clockMenu: ButtonFormData = {
    title: clockMenuText.title,
    body: clockMenuText.body,
    buttons: [
        {
            icon: "gui/newgui/Language18.png",
            label: clockMenuText.langSetting, //翻译文本
            func: (ctx) => {
                ctx.push(LangSettingForm);
            },
        },
    ],
};