API Reference
Complete API documentation for the better_i18n Flutter SDK.
Complete API reference for the better_i18n Flutter/Dart SDK.
BetterI18nProvider
The top-level widget. Manages the BetterI18nController lifecycle and provides translations to all descendant widgets via BetterI18nScope.
BetterI18nProvider(
project: 'acme/app',
defaultLocale: 'en',
storage: SharedPrefsStorage(),
loadingBuilder: (_) => const CircularProgressIndicator(),
child: const MyApp(),
)Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
project | String | Yes | — | Project identifier in "org/project" format |
defaultLocale | String | Yes | — | Fallback locale used when no locale is set |
child | Widget | Yes | — | Root widget of your app |
locale | String? | No | null | Externally controlled locale (e.g., from a Cubit/BLoC) |
cdnBaseUrl | String? | No | https://cdn.better-i18n.com | CDN URL override |
ttl | int? | No | 300000 | Memory cache TTL in milliseconds (5 min) |
timeout | int? | No | 10000 | CDN fetch timeout in milliseconds |
retry | int? | No | 1 | Number of retry attempts on CDN failure |
storage | TranslationStorage? | No | null | Persistent storage adapter — use SharedPrefsStorage() |
staticData | Map<String, Messages>? | No | null | Bundled fallback translations for airplane mode first launch |
loadingBuilder | WidgetBuilder? | No | null | Widget shown while translations are loading (initial load only) |
errorBuilder | Widget Function(BuildContext, Object)? | No | null | Widget shown when a fatal error occurs |
When locale is set externally (e.g., from a Cubit), BetterI18nProvider detects changes via didUpdateWidget and calls controller.setLocale() automatically.
BuildContext Extensions
Available on any BuildContext below BetterI18nProvider in the widget tree.
BetterI18nController
Manages i18n state — locale, messages, and languages. Extends ChangeNotifier so widgets rebuild when state changes.
final controller = BetterI18nController(
config: const I18nConfig(
project: 'acme/app',
defaultLocale: 'en',
),
initialLocale: 'tr',
);
await controller.initialize();Constructor
| Parameter | Type | Required | Description |
|---|---|---|---|
config | I18nConfig | Yes | Core configuration |
initialLocale | String? | No | Starting locale — defaults to config.defaultLocale |
Getters
| Getter | Type | Description |
|---|---|---|
locale | String | Current active locale |
messages | Messages? | Loaded translation messages (null until ready) |
languages | List<LanguageOption> | Available languages from CDN manifest |
isLoading | bool | Whether translations are currently loading |
isReady | bool | Whether the controller is initialized and ready |
error | Object? | Last error that occurred during loading, if any |
Methods
I18nCore
The pure Dart core engine — no Flutter dependency. Implements the 4-tier fallback chain. Used internally by BetterI18nController.
final core = I18nCore(
config: NormalizedConfig(
project: 'acme/app',
defaultLocale: 'en',
cdnBaseUrl: 'https://cdn.better-i18n.com',
manifestCacheTtlMs: 300000,
timeout: 10000,
retry: 1,
),
);Methods
BetterI18nScope
Low-level InheritedNotifier that provides BetterI18nController to the widget tree. Used internally by BetterI18nProvider — use directly only for testing or advanced scenarios.
BetterI18nScope(
controller: myController,
child: MyWidget(),
)