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;
    }
}