Awesome Open Source
Awesome Open Source

Flutter Google Sheet localizations generator

Generates a localizations delegate from an online Google Sheet file.


Add the following to your pubspec.yaml:

  flutter_sheet_localization: <latest>
    sdk: flutter

  flutter_sheet_localization_generator: <latest>
  build_runner: <latest>


1. Create a Google Sheet

Create a sheet with your translations (following the bellow format, an example sheet is available here) :


Make sure that your sheet is shared :


Extract from the link the DOCID and SHEETID values :<DOCID>/edit#gid=<SHEETID>) :

2. Declare a localization delegate

Declare the following AppLocalizationsDelegate class with the SheetLocalization annotation pointing to your sheet in a lib/localization.dart file :

import 'package:flutter/widgets.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter_sheet_localization/flutter_sheet_localization.dart';

part 'localization.g.dart';

@SheetLocalization("DOCID", "SHEETID", 1) // <- See 1. to get DOCID and SHEETID
// the `1` is the generated version. You must increment it each time you want to regenerate
// a new version of the labels.
class AppLocalizationsDelegate
    extends LocalizationsDelegate<AppLocalizationsData> {
  const AppLocalizationsDelegate();

  bool isSupported(Locale locale) => localizedLabels.containsKey(locale);

  Future<AppLocalizationsData> load(Locale locale) =>
  bool shouldReload(AppLocalizationsDelegate old) => false;

3. Generate your localizations

Run the following command to generate a lib/localization.g.dart file :

flutter packages pub run build_runner build

4. Configure your app

Update your Flutter app with your newly created delegate :

    locale: AppLocalizations.languages.keys.first, // <- Current locale
    localizationsDelegates: [
    const AppLocalizationsDelegate(), // <- Your custom delegate
        AppLocalizations.languages.keys.toList(), // <- Supported locales
    // ...

5. Display your labels

final labels = AppLocalizations.of(context);
print(labels.templated.hello(firstName: "World"));
print(, lastName: "John"));


Because of the caching system of the build_runner, it can't detect if there is a change on the distant sheet and it can't know if a new generation is needed.

The version parameter of the @SheetLocalization annotation solves this issue.

Each time you want to trigger a new generation, simply increment that version number and call the build runner again.

Google Sheet format

You can see an example sheet here.

Global format

The file should have :

  • A first header row
    • Column 0 : "Key"
    • then each supported language code ("en", "fr", ...)
  • Following rows for labels
    • Column 0 : the label key (can be a hierarchy, separated by dots)
    • then each translation based on language code of the column

Ignoring a column

Sometimes you may need to add comments for translators. For this, simply add a column with a name between parenthesis and the column will be completely ignored by the generator.

Example :

Key (Comments) fr en This is a man title on home page homme man This is a woman title on home page femme woman


It is pretty common to have variants of a label based on a condition (for example: Genders, Plurals, ...).

Simply duplicate your entries and end them with (<ConditionName>.<ConditionCase).

Example :

Key fr en homme man femme woman

See example for more details.


The conditionals can be used the same way for plurals :

Example :

Key fr en hommes man homme man hommes men

From your Dart code, you can then define an extension :

extension PluralExtension on int {
  Plural plural() {
    if (this == 0) return;
    if (this == 1) return;
    return Plural.multiple;

See example for more details.

Dynamic labels

You can insert a {{KEY}} template into a translation value to have dynamic labels.

A Dart function will be generated to be used from your code.

/// Sheet
values.hello, "Hello {{first_name}}!"

/// Code
print(labels.values.hello(firstName: "World"));

Typed parameters

You can also add one of the compatible types (int, double, num, DateTime) to the parameter by suffixing its key with :<type>.

/// Sheet
values.price, "The price is {{price:double}}\$"

/// Code
print(labels.values.price(price: 10.5));

Formatted parameters

You can indicate how the templated value must be formatted by ending the value with a formatting rule in brackets [<rule-key>]. This can be particulary useful for typed parameters.

The available formatting rules depend on the type and generally rely on the intl package.

Type rule-key Generated code
double, int, num decimalPercentPattern, currency, simpleCurrency, compact, compactLong, compactSimpleCurrency, compactCurrency, decimalPattern, percentPattern, scientificPattern NumberFormat.<rule-key>(...)
DateTime Any date format valid pattern DateFormat('<rule-key>', ...).format(...)


/// Sheet
values.price, "Price : {{price:double[compactCurrency]}}"

/// Code
print(labels.values.price(price: 2.00));
/// Sheet, "Today : {{date:DateTime[EEE, M/d/y]}}"

/// Code

Why ?

I find the Flutter internationalization tools not really easy to use, and I wanted a simple tool for sharing translations. Most solutions also use string based keys, and I wanted to generate pure dart code to improve permormance.

Alternatives To Flutter_sheet_localization
Select To Compare

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Dart (56,272
Google (36,663
Flutter (30,978
Csv (15,128
Label (11,539
Excel (7,286
Localization (5,348
Internationalization (3,345
Localize (33