//
//  KBLocalizationManager.h
//  多语言管理（App 与键盘扩展共用）
//  功能：
//  - 运行时切换语言（不依赖系统设置）
//  - 可选跨 Target 同步（共享钥匙串），让 App 与扩展语言一致
//  - 提供便捷宏 KBLocalized(key)
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/// 当前语言变更通知（不附带 userInfo）
extern NSString * const KBLocalizationDidChangeNotification;

/// 轻量多语言管理器：支持运行时切换、跨 Target 同步
@interface KBLocalizationManager : NSObject

/// 单例
+ (instancetype)shared;

/// 当前语言代码（如："en"、"zh-Hans"、"ja"）。
/// 默认会在受支持语言中，按系统首选语言择优匹配。
@property (nonatomic, copy, readonly) NSString *currentLanguageCode;

/// 支持的语言代码列表。默认 @[@"en", @"zh-Hans"]。
/// 建议在启动早期设置；或设置后再调用 `-setCurrentLanguageCode:persist:` 以刷新。
@property (nonatomic, copy) NSArray<NSString *> *supportedLanguageCodes;

/// 设置当前语言。
/// @param code 语言代码
/// @param persist 是否持久化到共享钥匙串（以便 App 与扩展共享该选择）
- (void)setCurrentLanguageCode:(NSString *)code persist:(BOOL)persist;

/// 清除用户选择，恢复为系统最佳匹配。
- (void)resetToSystemLanguage;

/// 从默认表（Localizable.strings）取文案。
- (NSString *)localizedStringForKey:(NSString *)key;

/// 指定表名（不含扩展名）取文案。
- (NSString *)localizedStringForKey:(NSString *)key
                               table:(nullable NSString *)table
                                value:(nullable NSString *)value;

/// 基于一组“偏好语言”计算最佳支持语言。
- (NSString *)bestSupportedLanguageForPreferred:(NSArray<NSString *> *)preferred;

@end

/// 便捷宏：与 NSLocalizedString 类似，但遵循 KBLocalizationManager 当前语言
#ifndef KBLocalized
#define KBLocalized(key) [[KBLocalizationManager shared] localizedStringForKey:(key)]
#endif

NS_ASSUME_NONNULL_END