KLocalizations

Pub Version

Wrapper around flutter_localizations, adding some extra functionality and abstracting some of the common logic.

Features

  • Easy setup
  • Parameter interpolation
  • Access translations with dot notation (home.title)
  • Change locale from anywhere
  • LocalizedText widget

How to use

1. Create translations files

The first this we need to do is to create the files containing our translations for each of the supported languages.

By default KLocalizations expects them to be located under 'assets/translations', but can be specified on setup. The configuration files must be in JSON format.

Example:

// assets/translations/es.json
{
  "welcome": "Bienvenido a klocalizations demo!",
  "home": {
    "title": "KLocalizations demo!",
    "counter": "Has clicado {{count}} veces"
  },
}

2. Setup

void main() {
  runApp(
    KLocalizations.asChangeNotifier(
      locale: supportedLocales[0],
      defaultLocale: supportedLocales[0],
      supportedLocales: supportedLocales,
      localizationsAssetsPath: 'assets/translations',
      child: MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final localizations = KLocalizations.of(context);

    return MaterialApp(
      locale: localizations.locale,
      supportedLocales: localizations.supportedLocales,
      localizationsDelegates: [
        localizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate
      ],
      home: MyApp(),
    );
  }
}

2.1. Add assets to pubspec

The path to the translation files assets must be declared in the pubspec.yml so that Flutter lets us access them:

flutter:
  assets:
    - assets/translations/

The asset path must be the same as the one passed in localizationsAssetsPath.

3. Translating

Now we are ready to start translating in the app. KLocalizations offers 2 ways of doing this, by using KLocalizations.translate() or using the LocalizedText widget.

KLocalizations.translate()

This method receives a string (or key) and returns the translated string. This is how you would use it:

@override
Widget build(BuildContext context) {
  final localizations = KLocalizations.of(context);

  return Column(
    children: [
      Text(localizations.translate('welcome')),
      Text(localizations.translate('home.title')),
      Text(localizations.translate('home.counter', { 'count': 12 })),
    ]
  );
}

LocalizedText

KLocalizatons offers a text widget that behaves exactly like Flutter's Text widget but tries to translate the given string using KLocalizatons. It also accepts params for interpolation. Used like this:

@override
Widget build(BuildContext context) {
  return Column(
    children: [
      LocalizedText('welcome'),
      LocalizedText('home.title', selectable: true),
      LocalizedText.selectable('home.counter', params: { 'count': 12 }),
    ]
  );
}

LocalizedText accepts the same arguments as Text plus some additional parameters. You can find the complete documentation here.

4. Changing locale

Changing locale is not a big deal, we just need to tell KLocalizatons to change it:

KLocalizations.of(context).setLocale(locale);

This will rebuild the widget tree and apply the selected locale across the app.

Additional info

  • Complete example here
  • Docs can be found here

If you encounter any problems or fancy a feature to be added please head over to the GitHub repository and drop an issue.

Libraries

klocalizations_flutter