sheet_localization 1.0.2
sheet_localization: ^1.0.2 copied to clipboard

Annotations for the sheet_localization_generator package.

Flutter Google Sheet Localizations #

A library for Dart developers.

Thanks so much for Publisher!

Note: We've been inspired by your package (flutter_sheet_localization package).

Created from templates made available by Stagehand under a BSD-style license.

Usage #

A simple usage example:

import 'package:sheet_localization/sheet_localization.dart';

main() {
  var sheetLocalization = SheetLocalization();

Install #

Add the following to your pubspec.yaml:

  sheet_localization: <latest>
    sdk: flutter

  sheet_localization_generator: <latest>
  build_runner: <latest>

Usage #

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:sheet_localization/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"));

Regeneration #

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)fren is a man title on home pagehommeman is a woman title on home pagefemmewoman

Conditionals #

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 :


See example for more details.


The conditionals can be used the same way for plurals :

Example :


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.

Typerule-keyGenerated code
double, int, numdecimalPercentPattern, currency, simpleCurrency, compact, compactLong, compactSimpleCurrency, compactCurrency, decimalPattern, percentPattern, scientificPatternNumberFormat.<rule-key>(...)
DateTimeAny date format valid patternDateFormat('<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.

pub points


Annotations for the sheet_localization_generator package.

Repository (GitHub)
View/report issues


API reference






Packages that depend on sheet_localization