多语言

多语言（internationalization, i18n）是 Linlang 为插件提供多种语言文本的统一机制。语言文件、命令提示和运行时内建消息都以当前 Linlang 实例的全局语言为依据。

需要注意的是，多语言不等同于本地化（localization, l10n）：

Linlang 以插件为单位设置语言。文档中的「全局语言」指当前插件使用的语言，除非另有说明。

全局语言

每一个插件获得的 Linlang Facade 都维护一个全局语言代码。语言代码遵循 language_REGION 形式，例如 zh_CN、en_GB。

设置全局语言的公开入口是：

lin.settings()
        .totalLocale("zh_CN")
        .apply();

settings().apply() 原地更新当前 Facade 的语言对象和命令显示，不重建服务，也不清空注册内容。

初始化顺序

最常见的初始化流程是：

public final class MyPlugin extends JavaPlugin {

    private Linlang lin;
    private MainConfig config;
    private MainLanguage lang;

    @Override
    public void onEnable() {
        lin = Lin.init(this);

        MainConfig bootConfig = lin.linFile().config().bind(MainConfig.class);

        lin.settings()
                .totalLocale(bootConfig.language)
                .apply();

        config = lin.linFile().config().bind(MainConfig.class);
        lang = lin.linFile().language().bind(MainLanguage.class);
    }
}

应用运行参数后，配置、语言和命令服务保持原实例。已取得的语言引用继续读取新语言；此前取出的普通字符串仍是旧值，需要重新读取字段。

如果启动选项本身由配置文件决定，也可以使用 Lin.setup(...)：

lin = Lin.setup(this, current -> {
    MainConfig cfg = current.linFile().config().bind(MainConfig.class);
    return new LinOptions().totalLocale(cfg.language);
});

lang = lin.linFile().language().bind(MainLanguage.class);

语言文件

语言对象只声明字段结构，具体文本来自 resources/langservice/<filePath>/<locale>.yml 或对应的 JSON 文件。

@LangPack(filePath = "main", format = FileType.YAML)
public class MainLanguage {
    public Message message = new Message();

    public static class Message {
        public String prefix = "";
        public String reloaded = "";
    }
}

资源文件示例：

message:
  prefix: "§7[§dMyPlugin§7] "
  reloaded: "配置文件重新加载成功"

语言文件的注释应直接写在内建 YAML 资源中，不需要在语言对象上声明多语言注释注解。

绑定时只需要传入语言对象类：

MainLanguage lang = lin.linFile().language().bind(MainLanguage.class);

Linlang 会按照当前全局语言选择资源文件，并将字段写入返回的语言对象。需要把语言字段交给命令或 GUI 长期持有时，可以使用动态解析的 LangText、LangList 或 LangMap 字段。具体目录、补齐和保存规则请见：语言文件 ⇱ 与 语言引用 ⇱。

运行流程

flowchart LR
    Config["配置中的语言代码"] --> Settings["settings().totalLocale()"]
    Settings --> Restart["原地更新语言状态"]
    Restart --> Lang["语言文件服务"]
    Restart --> Command["命令消息"]
    Restart --> Message["运行时内建消息"]
    Lang --> Resource["对应 locale 的资源文件"]

归一化

语言代码遵循 language_REGION 的格式，以下列出一些易错的语言代码：

以下缩写无法被归一化规则识别：

支持多语言的模块

多语言是一项基本服务，其在 Linlang 启动流程靠前的位置加载，仅在配置文件模块之后。您可以在除了配置文件之外的所有模块中使用多语言。