Multilingual

Force a specific language

When you need to provide a language switching option in your app that does not follow the system language, use setLanguage() to explicitly set the language:

// Force the language to English (no longer follows the system language)
PlayerLocale.setLanguage("en");

// Force the language back to Chinese
PlayerLocale.setLanguage("zh");

When setLanguage() is called, the current Activity is automatically recreated for the new language to take effect.

Add a new language

You can add support for new languages, like Japanese or Korean, by using the standard Android resource mechanism. After you add the new language resources, AliPlayerKit will automatically follow the system language for that language.

1. Create the corresponding resource directory in your app module.

   your-app/src/main/res/
   ├── values/strings.xml          ← Chinese (default)
   ├── values-en/strings.xml       ← English
   ├── values-ja/strings.xml       ← New: Japanese
   └── values-ko/strings.xml       ← New: Korean

2. Copy the default values/strings.xml file and translate all its entries.

   <!-- res/values-ko/strings.xml --><?xml version="1.0" encoding="utf-8"?><resources><string name="setting_item_speed">재생 속도</string><string name="setting_item_quality">화질</string><string name="setting_item_loop">반복 재생</string><string name="setting_item_mute">음소거</string><string name="player_brightness">밝기</string><string name="player_volume">볼륨</string><!-- ... translate all entries ... --></resources>

3. Apply the new language.

   • Automatic System Follow: When a user sets their system language to Korean, the player UI text switches automatically without any API calls.

   • Force Language: To switch the language manually within your app, call PlayerLocale.setLanguage("ko").

Listen for language changes

Use a listener to detect language changes. This is useful for refreshing a custom UI or for logging purposes:

// Create the listener
PlayerLocale.OnLanguageChangedListener listener = (oldLanguage, newLanguage) -> {
    Log.i(TAG, "Language changed: " + oldLanguage + " → " + newLanguage);
    // Refresh your custom UI
    refreshMyCustomUI();
};

// Register the listener
PlayerLocale.addOnLanguageChangedListener(listener);

// Remove the listener when it is no longer needed (e.g., in Activity.onDestroy())
PlayerLocale.removeOnLanguageChangedListener(listener);

Text lookup mechanism

PlayerLocale.get() obtains the text for the current language through the standard Android resource mechanism:

• If a values-xx/strings.xml file exists for the current language, the system returns the translation from that file.

• If no corresponding resource directory exists for the current language, the system falls back to the default language (Chinese, from values/strings.xml).

Thread safety

Language switching mechanism

The internal implementation of setLanguage() uses AppCompatDelegate.setApplicationLocales():

• On Android 13+, the system natively supports per-app language preferences, so no special handling is required.

• On Android 12 and earlier, a Context with the correct locale is created using createConfigurationContext.

• This call recreates the current Activity, which automatically refreshes the UI.

Version compatibility

Choosing the right approach

Important notes

Example features

Run the example

In the Demo App, select the Locale example to see it in action.