keyboard/Shared/KBLocalizationManager.h

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

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/// 语言码类型（集中管理，避免在各处散落写 @"en"/@"zh-Hans"）
typedef NSString *KBLanguageCode NS_EXTENSIBLE_STRING_ENUM;

/// 项目内统一使用的语言常量
FOUNDATION_EXPORT KBLanguageCode const KBLanguageCodeEnglish;          // @"en"
FOUNDATION_EXPORT KBLanguageCode const KBLanguageCodeSimplifiedChinese; // @"zh-Hans"

/// 默认支持的语言列表（目前为 @[KBLanguageCodeEnglish, KBLanguageCodeSimplifiedChinese]）
FOUNDATION_EXPORT NSArray<KBLanguageCode> *KBDefaultSupportedLanguageCodes(void);

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

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

/// 单例
+ (instancetype)shared;

/// 当前语言代码（如：KBLanguageCodeEnglish、KBLanguageCodeSimplifiedChinese）。
/// 默认会在受支持语言中，按系统首选语言择优匹配。
@property (nonatomic, copy, readonly) KBLanguageCode currentLanguageCode;

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

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

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

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

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

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

- (void)reloadFromSharedStorageIfNeeded;

@end

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

NS_ASSUME_NONNULL_END