Note: This description is bilingual. The Chinese section is provided below the English section.
说明：本描述为中英双语版本，中文内容位于英文内容下方。

---

Sunkenland Localization API (English)

Sunkenland Localization API is a shared localization library for Sunkenland mods.

What This Mod Does

• Lets compatible mods load their own external JSON language files.
• Uses Sunkenland's active language and refreshes registered mod text after a language change.
• Supports localized config sections, setting names, descriptions, dropdown values, ordering, and slider steps.

For Players

This mod is an API/dependency. It does not add gameplay features by itself.
Install it only when another mod lists Sunkenland Localization API as a requirement.

For Mod Authors

Reference SunkenlandLocalizationAPI.dll and add a hard BepInEx dependency:

using BepInEx;
using BepInEx.Configuration;
using SunkenlandLocalizationAPI.Api;

[BepInDependency(SunkenlandLocalizationAPI.PluginInfo.PLUGIN_GUID)]
public sealed class MyPlugin : BaseUnityPlugin
{
    private void Awake()
    {
        Config.Bind("General", "Enabled", true, I18n.Localizer.Config("config.enabled", 10, "General", "config.general", 10));
        LocalizationApi.LanguageChanged += OnLanguageChanged;
    }

    private static void OnLanguageChanged(string language)
    {
        // Refresh this mod's existing UI text here.
    }
}

Load the JSON file from the directory containing your mod DLL. This also works with generated r2modman and mod-manager folder names:

using System.IO;
using System.Reflection;
using SunkenlandLocalizationAPI.Api;

internal static class I18n
{
    private const string FileName = "MyMod.Localization.json";
    private static readonly ModLocalizer _localizer = Load();

    internal static ModLocalizer Localizer
    {
        get { return _localizer; }
    }

    internal static string Text(string key, params object[] args)
    {
        return _localizer.GetLocalizedText(key, args);
    }

    private static ModLocalizer Load()
    {
        string directory = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
        ModLocalizer localizer = LocalizationApi.For(PluginInfo.PLUGIN_GUID);
        localizer.RegisterJson(Path.Combine(directory, FileName));
        return localizer;
    }
}

The Config call uses <key>.name and <key>.description. Enum and acceptable-list values use a normalized lowercase suffix, so SafeMode resolves to <key>.safe_mode automatically:

Config.Bind("General", "Mode", MyMode.SafeMode, I18n.Localizer.Config("config.mode", 20, "General", "config.general", 10));

Pass an AcceptableValueRange and sliderStep to declare a custom range-slider step in the same call:

Config.Bind("Display", "Scale", 100, I18n.Localizer.Config("config.scale", 10, "Display", "config.display", 20, new AcceptableValueRange<int>(50, 200), sliderStep: 5d));

Single JSON file example:

{
  "en": {
    "config.general": "General",
    "config.enabled.name": "Enabled",
    "config.enabled.description": "Enable this mod.",
    "config.mode.name": "Mode",
    "config.mode.description": "Select the operating mode.",
    "config.mode.safe_mode": "Safe"
  },
  "zh-Hans": {
    "config.general": "常规",
    "config.enabled.name": "启用",
    "config.enabled.description": "启用此模组。",
    "config.mode.name": "模式",
    "config.mode.description": "选择运行模式。",
    "config.mode.safe_mode": "安全"
  }
}

Every localization file must contain an en object. If the current language or requested key is missing, the API tries en; if the key is still missing, it returns the key itself.

Supported Locale Codes

• English: en
• Chinese (Simplified): zh-Hans
• French: fr
• German: de
• Japanese: ja
• Korean: ko
• Russian: ru
• Spanish: es
• Turkish: tr

Compatibility

• Game version: Beta 0.8.41+

Bug Reports & Feature Suggestions

If you have any questions or feature suggestions, please submit them through GitHub Issues, contact me on Discord at iceboxcool, or email me at [email protected] or [email protected].

---

---

Sunkenland Localization API (中文)

Sunkenland Localization API 是为 Sunkenland 模组提供的共享本地化库。

主要功能

• 让兼容模组加载各自独立的外置 JSON 语言文件。
• 读取 Sunkenland 当前语言，并在语言切换后刷新已注册的模组文本。
• 支持配置分类、配置名称、说明、下拉选项值、排序和滑条步进。

给玩家

这是一个 API/依赖模组，本身不会添加玩法内容。
只有其他模组要求安装 Sunkenland Localization API 时才需要安装它。

给模组作者

在项目中引用 SunkenlandLocalizationAPI.dll，并添加 BepInEx 硬依赖：

using BepInEx;
using BepInEx.Configuration;
using SunkenlandLocalizationAPI.Api;

[BepInDependency(SunkenlandLocalizationAPI.PluginInfo.PLUGIN_GUID)]
public sealed class MyPlugin : BaseUnityPlugin
{
    private void Awake()
    {
        Config.Bind("General", "Enabled", true, I18n.Localizer.Config("config.enabled", 10, "General", "config.general", 10));
        LocalizationApi.LanguageChanged += OnLanguageChanged;
    }

    private static void OnLanguageChanged(string language)
    {
        // 在这里刷新模组已经创建的 UI 文本。
    }
}

从模组 DLL 自己所在的目录加载 JSON。这样即使 r2modman 或其他模组管理器生成了不同的插件文件夹名，也能正确找到语言文件：

using System.IO;
using System.Reflection;
using SunkenlandLocalizationAPI.Api;

internal static class I18n
{
    private const string FileName = "MyMod.Localization.json";
    private static readonly ModLocalizer _localizer = Load();

    internal static ModLocalizer Localizer
    {
        get { return _localizer; }
    }

    internal static string Text(string key, params object[] args)
    {
        return _localizer.GetLocalizedText(key, args);
    }

    private static ModLocalizer Load()
    {
        string directory = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
        ModLocalizer localizer = LocalizationApi.For(PluginInfo.PLUGIN_GUID);
        localizer.RegisterJson(Path.Combine(directory, FileName));
        return localizer;
    }
}

Config 会读取 <key>.name 和 <key>.description。枚举和可接受值列表会自动把值转成小写下划线后缀，例如 SafeMode 会读取 <key>.safe_mode：

Config.Bind("General", "Mode", MyMode.SafeMode, I18n.Localizer.Config("config.mode", 20, "General", "config.general", 10));

传入 AcceptableValueRange 和 sliderStep，即可在同一行声明自定义范围滑条步进：

Config.Bind("Display", "Scale", 100, I18n.Localizer.Config("config.scale", 10, "Display", "config.display", 20, new AcceptableValueRange<int>(50, 200), sliderStep: 5d));

单 JSON 文件示例：

{
  "en": {
    "config.general": "General",
    "config.enabled.name": "Enabled",
    "config.enabled.description": "Enable this mod.",
    "config.mode.name": "Mode",
    "config.mode.description": "Select the operating mode.",
    "config.mode.safe_mode": "Safe"
  },
  "zh-Hans": {
    "config.general": "常规",
    "config.enabled.name": "启用",
    "config.enabled.description": "启用此模组。",
    "config.mode.name": "模式",
    "config.mode.description": "选择运行模式。",
    "config.mode.safe_mode": "安全"
  }
}

每个语言文件都必须包含 en 对象。当前语言或目标 key 缺失时，API 会尝试 en；如果英语中仍缺少该 key，则直接返回 key 本身。

支持的语言代码

• 英语：en
• 简体中文：zh-Hans
• 法语：fr
• 德语：de
• 日语：ja
• 韩语：ko
• 俄语：ru
• 西班牙语：es
• 土耳其语：tr

兼容性

• 游戏版本：Beta 0.8.41+

Bug 提交 & 新功能建议

如果你有任何问题或新功能建议，请通过 GitHub Issues 提交，也可以通过 Discord：iceboxcool，或邮箱 [email protected]、[email protected] 联系我。