Set Device Language

Set the language used by a connected device. The target language is represented by the SDK's DeviceLanguage enum.

Prerequisites

Before setting the device language, ensure:

• The device is connected and in a stable state
• The device supports the DeviceInfoAPI protocol
• The selected language appears in the device's supportedLanguages list

API Reference

Framework

AIBuds.xcframework

Import

In the files where you want to use the SDK, import the main framework:

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

Protocol

The setDeviceLanguage method is defined in DeviceInfoAPI. The protocol inherits from the base device API protocol.

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

Instance Method

Sets the device language to a supported DeviceLanguage value.

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;

Parameters

Parameter	Type	Description
language	DeviceLanguage / AIBudsDeviceLanguage	The target language to set.
completion	AIBudsCompletionHandler?	Optional completion handler called when the operation finishes.

Callback Parameters:

Name	Type	Description
success	Bool / BOOL	true if the operation succeeded; otherwise false.
error	NSError?	Error details if the operation failed; otherwise nil.

Return Value

This method does not return a value directly. The result is provided through the completion handler.

Usage Examples

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

Error Handling

1. Check success before treating the new language as applied.
2. Use error for failure details when the operation does not succeed.
3. Reject unsupported values before sending the command.
4. Do not assume a specific error code unless it is documented for the target device.

Best Practices

1. Use the SDK Enum: Pass a DeviceLanguage value instead of an ISO language-code string.
2. Check Supported Languages: Compare the enum's raw value with supportedLanguages before calling the method.
3. Check Protocol Conformance: Confirm that the device supports DeviceInfoAPI.
4. Update UI on the Main Queue: Dispatch completion-driven UIKit updates to the main queue.

Notes

• supportedLanguages contains NSNumber values that wrap DeviceLanguage raw values.
• languageSetting exposes the device's current language setting.
• Supported languages can vary by device model and firmware.
• The SDK Demo sets the language to AIBudsDeviceLanguageEnglish; production applications should select from the device's advertised values.