기기 언어 설정

연결된 기기에서 사용할 언어를 설정합니다. 대상 언어는 SDK의 DeviceLanguage enum으로 지정합니다.

사전 요구 사항

기기 언어를 설정하기 전에 다음을 확인하세요.

• 기기가 연결되어 안정적인 상태입니다.
• 기기가 DeviceInfoAPI 프로토콜을 지원합니다.
• 선택한 언어가 기기의 supportedLanguages 목록에 포함되어 있습니다.

API 참고

프레임워크

AIBuds.xcframework

가져오기

SDK를 사용할 파일에서 메인 프레임워크를 가져옵니다.

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

프로토콜

setDeviceLanguage 메서드는 DeviceInfoAPI에 정의되어 있으며 이 프로토콜은 기본 기기 API 프로토콜을 상속합니다.

Swift

Swift

protocol DeviceInfoAPI: DeviceAPI {
    /// Current language setting of the device.
    var languageSetting: DeviceLanguage { get }

    /// List of languages supported by the device, each element is an
    /// `NSNumber` wrapping the raw value of `DeviceLanguage`.
    var supportedLanguages: [NSNumber] { get }

    /// Sets the device language.
    /// - Parameters:
    ///   - language: The target language to set.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func setDeviceLanguage(
        _ language: DeviceLanguage,
        completion: AIBudsCompletionHandler?
    )
}

Objective-C

Objective-C

@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
/// Current language setting of the device.
@property(nonatomic, readonly) enum AIBudsDeviceLanguage languageSetting;

/// List of languages supported by the device, each element is an
/// `NSNumber` wrapping the raw value of `DeviceLanguage`.
@property(nonatomic, readonly, copy) NSArray<NSNumber *> *_Nonnull supportedLanguages;

/// Sets the device language.
/// - Parameters:
///   - language: The target language to set.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)setDeviceLanguage:(enum AIBudsDeviceLanguage)language
               completion:(AIBudsCompletionHandler _Nullable)completion;
@end

인스턴스 메서드

기기 언어를 지원되는 DeviceLanguage 값으로 설정합니다.

Swift

Swift

/// Sets the device language.
/// - Parameters:
///   - language: The target language to set.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func setDeviceLanguage(
    _ language: DeviceLanguage,
    completion: AIBudsCompletionHandler?
)

Objective-C

Objective-C

/// Sets the device language.
/// - Parameters:
///   - language: The target language to set.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)setDeviceLanguage:(enum AIBudsDeviceLanguage)language
               completion:(AIBudsCompletionHandler _Nullable)completion;

매개변수

매개변수	타입	설명
language	DeviceLanguage / AIBudsDeviceLanguage	설정할 대상 언어입니다.
completion	AIBudsCompletionHandler?	작업이 끝날 때 호출되는 선택적 completion handler입니다.

콜백 매개변수:

이름	타입	설명
success	Bool / BOOL	작업이 성공하면 true, 실패하면 false입니다.
error	NSError?	작업 실패 상세 정보이며 성공하면 nil입니다.

반환 값

이 메서드는 값을 직접 반환하지 않습니다. 결과는 completion handler로 전달됩니다.

사용 예제

Swift

Swift

import AIBuds

final class DeviceManager {
    weak var device: DeviceConvertible?

    func setDeviceLanguage(_ language: DeviceLanguage) {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support language settings")
            return
        }

        let isSupported = device.supportedLanguages.contains {
            $0.intValue == language.rawValue
        }
        guard isSupported else {
            print("The selected language is not supported by this device")
            return
        }

        device.setDeviceLanguage(language) { success, error in
            if !success {
                print("Failed to set language: \(error?.localizedDescription ?? "Unknown error")")
                return
            }

            print("Device language set successfully")
        }
    }
}

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

@interface DeviceManager ()
@property(weak, nonatomic) id<AIBudsDeviceConvertible> device;
@end

@implementation DeviceManager

- (void)setDeviceLanguage:(AIBudsDeviceLanguage)language {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;
    if (![device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        NSLog(@"Device does not support language settings");
        return;
    }

    if (![device.supportedLanguages containsObject:@(language)]) {
        NSLog(@"The selected language is not supported by this device");
        return;
    }

    [device setDeviceLanguage:language
                   completion:^(BOOL success, NSError *_Nullable error) {
                       if (!success) {
                           NSLog(@"Failed to set language: %@",
                                 error.localizedDescription ?: @"Unknown error");
                           return;
                       }

                       NSLog(@"Device language set successfully");
                   }];
}

@end

오류 처리

1. 새 언어가 적용된 것으로 처리하기 전에 success를 확인하세요.
2. 작업이 실패하면 error에서 상세 정보를 확인하세요.
3. 지원하지 않는 값은 명령을 보내기 전에 거부하세요.
4. 대상 기기에 정의되지 않은 오류 코드를 임의로 가정하지 마세요.

권장 사항

1. SDK enum 사용: ISO 언어 코드 문자열 대신 DeviceLanguage 값을 전달하세요.
2. 지원 언어 확인: 메서드 호출 전에 enum raw value를 supportedLanguages와 비교하세요.
3. 프로토콜 확인: 기기가 DeviceInfoAPI를 지원하는지 확인하세요.
4. 메인 큐에서 UI 변경: completion에서 수행하는 UIKit 변경은 메인 큐로 전달하세요.

참고

• supportedLanguages에는 NSNumber 값이 포함되며 각 값은 DeviceLanguage raw value를 담고 있습니다.
• languageSetting은 기기의 현재 언어 설정을 제공합니다.
• 지원되는 언어는 기기 모델과 펌웨어에 따라 다를 수 있습니다.
• SDK Demo는 언어를 AIBudsDeviceLanguageEnglish로 설정하지만 실제 앱에서는 기기가 제공한 값 중에서 선택해야 합니다.