62 lines
3.0 KiB
C#
62 lines
3.0 KiB
C#
using System;
|
||
|
||
namespace BaseGames.Localization
|
||
{
|
||
/// <summary>
|
||
/// 本地化服务接口。通过 ServiceLocator 注册，供 UI 和游戏系统获取本地化文本。
|
||
/// </summary>
|
||
public interface ILocalizationService
|
||
{
|
||
/// <summary>当前激活的语言。</summary>
|
||
Language CurrentLanguage { get; }
|
||
|
||
/// <summary>
|
||
/// 获取本地化字符串。查找顺序：当前语言 → 回退语言（English）→ 直接返回 key。
|
||
/// 表名建议使用 <see cref="LocalizationTable"/> 中的常量。
|
||
/// </summary>
|
||
string Get(string key, string table = LocalizationTable.UI);
|
||
|
||
/// <summary>
|
||
/// 尝试获取本地化字符串。返回 false 表示 key 在所有语言（含回退）中均不存在。
|
||
/// 与 <see cref="Get"/> 不同：key 不存在时不会将 key 本身作为值返回。
|
||
/// 适用于需要区分"key 存在但值为空"和"key 完全不存在"的场景。
|
||
/// </summary>
|
||
bool TryGet(string key, out string value, string table = LocalizationTable.UI);
|
||
|
||
/// <summary>
|
||
/// 获取带格式化参数的本地化字符串（<c>string.Format</c> 风格）。
|
||
/// 例：<c>GetFormat("REWARD_GOLD", LocalizationTable.UI, amount)</c> → "获得 100 灵珠"。
|
||
/// 格式化失败时静默返回原始模板字符串，不抛出异常。
|
||
/// </summary>
|
||
string GetFormat(string key, string table, params object[] args);
|
||
|
||
/// <summary>切换游戏语言并通知所有订阅者刷新文本。</summary>
|
||
void SetLanguage(Language language);
|
||
|
||
/// <summary>
|
||
/// 同步预热指定语言的所有已知本地化表，避免首次访问时产生帧卡顿。
|
||
/// 在主线程阻塞执行，建议改用 <see cref="PreloadTablesAsync"/> 分帧加载。
|
||
/// </summary>
|
||
void PreloadTables(Language language);
|
||
|
||
/// <summary>
|
||
/// 异步分帧预热指定语言的所有本地化表（每帧加载一个表，不阻塞主线程）。
|
||
/// 建议在 Loading Screen 的协程中调用。
|
||
/// </summary>
|
||
/// <param name="language">要预热的语言。</param>
|
||
/// <param name="onComplete">全部表加载完成后的回调（可为 null）。</param>
|
||
void PreloadTablesAsync(Language language, Action onComplete = null);
|
||
|
||
/// <summary>
|
||
/// 获取带数量的复数形式本地化字符串。
|
||
/// 规则：先查找 "{key}_one"（count==1）或 "{key}_other"（count≠1），找不到则回退到基础 key。
|
||
/// 查找到的模板以 <c>string.Format(template, count)</c> 展开，{0} 代入 count。
|
||
/// 示例：key="ITEM_COUNT"，表中配置 "ITEM_COUNT_other"="获得 {0} 个物品" → "获得 5 个物品"。
|
||
/// </summary>
|
||
string GetPlural(string key, int count, string table = LocalizationTable.UI);
|
||
|
||
/// <summary>语言切换时触发。</summary>
|
||
event Action<Language> OnLanguageChanged;
|
||
}
|
||
}
|