Internationalization

Overview

The internationalization system offers the following features:

• Built-in Chinese and English - Requires no configuration.

• Automatically follows system language - Matches the system language by default.

• Custom language packs - Lets you register custom languages like Japanese and Korean.

• Override translations - Lets you modify built-in text labels.

• Runtime switching - Lets you switch languages dynamically.

Usage

Default configuration

The player component requires no configuration and automatically follows the system language.

Switch languages

// Switch to English
AliPlayerWidgetGlobalSetting.setLocale(const Locale('en'));

// Switch to Chinese
AliPlayerWidgetGlobalSetting.setLocale(const Locale('zh'));

Getting translations

// Use key constants (recommended)
final text = AliPlayerWidgetGlobalSetting.t(PlayerI18nKeys.volume);

// Interpolate with arguments
final speed = AliPlayerWidgetGlobalSetting.t(
  PlayerI18nKeys.speedFormat,
  {'speed': '1.5'},
);

Register new language

Implement the PlayerTranslations interface and register it:

// 1. Define the language pack
class PlayerTranslationsKo with PlayerTranslationsMixin {
  @override
  Locale get locale => const Locale('ko');

  @override
  Map<String, dynamic> get translations => {
    'player': {
      'settings': {
        'volume': '볼륨',
        'brightness': '밝기',
        // ...
      },
    },
  };
}

// 2. Register and use the new language
AliPlayerWidgetGlobalSetting.registerTranslations(PlayerTranslationsKo());
AliPlayerWidgetGlobalSetting.setLocale(const Locale('ko'));

Override translations

To modify specific translations for a language:

AliPlayerWidgetGlobalSetting.overrideTranslations('zh', {
  'player': {
    'settings': {
      'volume': 'volume',
      'quality': 'quality',
    },
  },
});

Listen for locale changes

ValueListenableBuilder<Locale>(
  valueListenable: AliPlayerWidgetGlobalSetting.localeNotifier,
  builder: (context, locale, _) {
    return Text(AliPlayerWidgetGlobalSetting.t(PlayerI18nKeys.volume));
  },
)

Integrate with MaterialApp

MaterialApp(
  localizationsDelegates: const [
    PlayerLocalizationsDelegate(),
    GlobalMaterialLocalizations.delegate,
  ],
  supportedLocales: AliPlayerWidgetGlobalSetting.supportedLocales,
)

Built-in languages

Translation keys

All translation keys are defined in the PlayerI18nKeys constants class.

For translation examples, see the following directories:

• Built-in translations: lib/i18n/translations/.

• Custom translations: example/lib/pages/i18n/translations/.

API

AliPlayerWidgetGlobalSetting

Example

Refer to example/lib/pages/i18n/i18n_demo_page.dart for a complete example that includes:

• Runtime language switching.

• Registering a new language pack (Japanese).

• Overriding built-in translations.