多语言

概念介绍

什么是 LocaleManager？

LocaleManager 是 AliPlayerKit 的内置国际化管理单例，负责播放器所有 UI 文案（按钮文本、错误提示、设置项标题等）的本地化查询。它采用解析链（Resolution Chain）机制，按优先级逐级查找翻译：

Custom Provider → activeBundle（手动/系统） → sdkBundle fallback → Key 本身

核心价值

语言模式

功能特性

默认行为（零配置）

AliPlayerKit 开箱即用，无需编写任何代码即可支持多语言：

• 内置简体中文和英文两种语言。

• 播放器 UI 文案自动跟随系统语言切换，无需任何初始化或 API 调用。

• 用户在系统「设置 → 通用 → 语言与地区」中切换语言后，播放器文案自动切换。

• 如果系统语言不在内置支持范围内，自动回退到默认语言（简体中文）。

内置语言

内置文案Key分类

使用方式

跟随系统语言（默认，无需代码）

集成 AliPlayerKit 后，播放器文案自动根据系统语言显示对应翻译：

// 无需任何配置，播放器 UI 文案自动跟随系统语言
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
[controller configure:model];
// 此时如系统为英文，所有 UI 文案自动显示英文

手动指定语言

当需要在应用内提供语言切换入口、不跟随系统语言时：

// 强制切换到英文
[AliPlayerKit setLanguageCode:@"en"];

// 强制切换到简体中文
[AliPlayerKit setLanguageCode:@"zh-Hans"];

恢复跟随系统

手动指定语言后，如需恢复为跟随系统：

// 清除手动设定，localeMode 恢复为 LocaleModeSystem
[AliPlayerKit resetLocaleToSystemLanguage];

查询当前语言

// 获取当前生效的语言代码
NSString *currentLang = [AliPlayerKit currentLanguageCode];
NSLog(@"当前语言: %@", currentLang); // 如 "zh-Hans" 或 "en"

监听语言变更

通过 NSNotification 监听语言切换事件：

// 注册通知
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(localeDidChange:)
                                             name:LocaleDidChangeNotification
                                           object:nil];

// 处理语言变更
- (void)localeDidChange:(NSNotification *)notification {
    NSString *newLanguage = notification.userInfo[LocaleLanguageCodeKey];
    NSLog(@"语言已切换为: %@", newLanguage);
    // 刷新自定义 UI 文案
    [self refreshCustomUI];
}

// 不再需要时移除
- (void)dealloc {
    [[NSNotificationCenter defaultCenter] removeObserver:self
                                                    name:LocaleDidChangeNotification
                                                  object:nil];
}

自定义开发

LocaleProvider 协议

LocaleProvider 定义了自定义翻译的注入接口：

@protocol LocaleProvider <NSObject>

@optional

/// 为指定 key 返回本地化字符串。
/// 返回 nil 表示不处理此 key，由 SDK 内部 fallback 继续解析。
- (nullable NSString *)localizedStringForKey:(NSString *)key;

@end

注入自定义 Provider

通过实现 LocaleProvider 协议，可以在不修改资源文件的情况下自定义任何翻译：

// 1. 定义自定义 Provider
@interface MyLocaleProvider : NSObject <LocaleProvider>
@end

@implementation MyLocaleProvider

- (nullable NSString *)localizedStringForKey:(NSString *)key {
    // 自定义特定 key 的翻译
    if ([key isEqualToString:LocaleKeyPlayStateLoading]) {
        return @"视频缓冲中，请稍候...";
    }
    if ([key isEqualToString:LocaleKeySettingSpeed]) {
        return @"播放倍率";
    }
    // 返回 nil 表示不处理此 key，由 SDK fallback 链继续解析
    return nil;
}

@end

// 2. 注入 Provider
MyLocaleProvider *provider = [[MyLocaleProvider alloc] init];
[AliPlayerKit setLocaleProvider:provider];

新增语言支持

当需要新增 AliPlayerKit 尚未内置的语言（如日语）时，通过自定义 Provider 实现全量翻译：

@interface JapaneseLocaleProvider : NSObject <LocaleProvider>
@property (nonatomic, strong) NSDictionary<NSString *, NSString *> *translations;
@end

@implementation JapaneseLocaleProvider

- (instancetype)init {
    self = [super init];
    if (self) {
        _translations = @{
            LocaleKeyPlayStateLoading: @"読み込み中...",
            LocaleKeyPlayStateErrorCodeLabel: @"エラーコード",
            LocaleKeyPlayStateErrorMessageLabel: @"エラーメッセージ",
            LocaleKeyBottomBarSpeed: @"速度",
            LocaleKeyBottomBarQuality: @"画質",
            LocaleKeySettingMenuTitle: @"設定",
            LocaleKeySettingSpeed: @"再生速度",
            LocaleKeySettingLoop: @"ループ再生",
            LocaleKeySettingMute: @"ミュート",
            LocaleKeySettingQuality: @"画質",
            // ... 全量翻译所有 LocaleKeys.h 中的 key
        };
    }
    return self;
}

- (nullable NSString *)localizedStringForKey:(NSString *)key {
    return self.translations[key];
}

@end

// 注入日语 Provider（需自行持有实例）
self.jaProvider = [[JapaneseLocaleProvider alloc] init];
[AliPlayerKit setLocaleProvider:self.jaProvider];

覆盖已有翻译

仅需覆盖部分翻译时，Provider 只返回需要修改的 key，其余返回 nil 由 SDK 处理：

- (nullable NSString *)localizedStringForKey:(NSString *)key {
    // 仅覆盖"加载中"提示文案
    if ([key isEqualToString:LocaleKeyPlayStateLoading]) {
        return @"精彩即将呈现...";
    }
    return nil; // 其他 key 使用 SDK 内置翻译
}

移除自定义 Provider

// 移除 Provider，恢复使用 SDK 内置翻译
[AliPlayerKit setLocaleProvider:nil];

设计说明

字符串解析链（Resolution Chain）

LocaleManager 内部按以下优先级查找翻译：

线程安全

LocaleManager 内部使用串行队列（dispatch_queue_t）保护所有状态读写：

通知机制

触发场景：

• 调用 setLanguageCode: 切换手动语言

• 调用 resetLocaleToSystemLanguage 恢复系统跟随

• 调用 setLocaleProvider: 注入/移除 Provider

API 速查

AliPlayerKit 类方法

LocaleManager实例方法

LocaleProvider 协议

SDK内部使用的宏

通知常量

相关文件

完整API请参见API参考。

最佳实践

选择合适的方案

注意事项

示例参考

PlayerKitUsages/UsageLocaleSystem 模块提供了完整的本地化系统使用示例，包含语言切换、自定义 Provider 注入和变更通知监听。