I18n class

Setup

Add a single I18n widget in your widget tree, above your MaterialApp (or CupertinoApp) widget.
Make sure the I18n widget is NOT declared in the same widget as the MaterialApp (or CupertinoApp) widget. It must be in a parent widget.
Add locale: I18n.locale to your MaterialApp (or CupertinoApp) widget.

Example

import 'package:i18n_extension/i18n_extension.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  Widget build(BuildContext context) {
    return I18n(
      child: AppCore(),
    );
  }
}

class AppCore extends StatelessWidget {
  Widget build(BuildContext context) {
    return MaterialApp(
      locale: I18n.locale,
      ...
    ),

Note that the I18n widget is above the MaterialApp widget, but declared in a parent widget. If you declare it in the same widget as the MaterialApp widget, it will not work. This is WRONG:

Widget build(BuildContext context) {
  return I18n(
    child: MaterialApp( // Wrong!
      locale: I18n.locale,
    ),

Configuration

When your app opens, it will use the current system-locale (set in the device settings). If you want to force a specific locale, you can do so by setting the initialLocale parameter in the I18n widget:

return I18n(
  initialLocale: locale('es', 'ES'),
  child: AppCore(),

The autoSaveLocale parameter is an optional boolean, and the default is false. If you set autoSaveLocale to true, the locale will be saved and recovered between app restarts. This is useful if you want to remember the user's language preference.

return I18n(
  autoSaveLocale: true,
  child: AppCore(),

Note, if your app only ever uses the current system locale, or if you save the locale in another way, you can keep autoSaveLocale as false.

Inheritance

Constructors

I18n.new({required Widget child, Locale? initialLocale, Iterable<Locale> supportedLocales = const [], Iterable<LocalizationsDelegate> localizationsDelegates = const [], bool autoSaveLocale = false}): Setup

Properties

autoSaveLocale → bool: If autoSaveLocale is true, the locale will be saved and recovered between app restarts. This is useful if you want to remember the user's language preference. If your app only ever uses the current system locale, or if you save the locale in another way, keep autoSaveLocale as false:
final
child → Widget: final
hashCode → int: The hash code for this object.
no setterinherited
initialLocale → Locale?: Optionally, you can set initialLocale to force a specific locale when the app opens. If you don’t set it, the current system-locale, read from the device settings, will be used.
final
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → _I18nState: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

forcedLocale → Locale?: If a locale was explicitly set in the app (forced), this method returns it. In other words, the forcedLocale overrides the system-locale. There are 3 ways to force a locale:
no setter
isUsingSystemLocale → bool: Returns true if the system locale is being used. In this case, the app will change the locale when the system locale changes.
no setter
languageOnly → String: The language code of the current locale, as a lowercase string. Note this is just the language itself, without region/country, script etc. For example, if the language tag is en-US, then it returns 'en'.
no setter
languageTag → String: Returns the current locale as a syntactically valid IETF BCP47 language tag (compatible with the Unicode Locale Identifier (ULI) syntax).
no setter
loaders → List<I18nLoader Function()>: Returns a list of loaders to be used by the i18n_extension. By default, it loads from JSON (.json) and PO (.po) files. This list may be changed statically, to add or remove loaders, and you may create your own loaders by extending I18nLoader.
final
locale → Locale: Return the current locale of the app.
no setter
localeStr → String: The locale, as a lowercase string with underscore as separators, like "en_us".
no setter
localizationsDelegates → Iterable<LocalizationsDelegate>: Returns the localization delegates of the app, as set in the I18n widget.
no setter
observeLocale ↔ void Function({required Locale newLocale, required Locale oldLocale}): This global callback is called whenever the locale changes. Notes:
getter/setter pair
preInitializationLocale ↔ Locale: When the app starts, the systemLocale is read from the system as soon as possible. The system locale might be unavailable for a brief period. Usually, this is not an issue and won’t be noticeable, but in rare cases, this locale will be used until the actual system locale is determined. You can change this to your preferred locale if needed. Otherwise, leave it as is.
getter/setter pair
supportedLocales → Iterable<Locale>: Returns the supported locales of the app, as set in the I18n widget.
no setter
systemLocale → Locale: The the system-locale, as set in the device settings. The only way to change this is opening the device settings and changing the language there. The app will change the locale when the system locale changes, but only if no locale was explicitly set (in other words, if forcedLocale is null).
no setter

Static Methods

define(Locale? locale) → void: Use this for tests only.
deleteLocale() → Future<void>: Deletes the locale previously saved with saveLocale, from the shared preferences of the device.
getDecimalSeparator(Locale locale) → String: Given a locale, return the decimal separator used in that locale. For example, for en-US it's ".", but for pt-BR it's ","
getLanguageOnlyFromLocale(Locale locale) → String: Return the lowercase language-code of the given locale. Note this is just the language itself, without region/country, script etc. For example, if the locale is Locale('en', 'US'), then it returns 'en'.
loadLocale() → Future<Locale?>: Load the locale previously saved with saveLocale, from the shared preferences of the device. Note this only returns the saved locale, but it doesn’t set it.
localeStringAsLowercaseAndUnderscore(Locale locale) → String: Return the string representation of the locale, normalized like so:
of(BuildContext context) → _I18nState: Getter: print(I18n.of(context).locale);
rebuild() → void: Forces the rebuild of I18n and all its descendant widgets.
reset() → void: Calling I18n.reset will remove the entire widget tree inside I18n for one frame, and then restore it, rebuilding everything. This can be helpful in rare circumstances, when some widgets are not responding to locale changes. This is a brute-force method, and it's probably not necessary in the vast majority of cases. A side effect is that the all stateful widgets below I18n will be recreated, and their state reset by calling their initState() method. This means you should only use this method if you don't mind loosing all this state, or if you have mechanisms to recover it, like for example having the state come from above the I18n widget.
saveLocale(Locale? locale) → Future<void>: Saves the given locale to the shared preferences of the device.