flutter_sheet_localization_generator

Description:

flutter sheet localization generator

Flutter Google Sheet localizations generator #
Generates a localizations delegate from an online Google Sheet file.
Install #
Add the following to your pubspec.yaml:
dependencies:
flutter_sheet_localization: <latest>
flutter_localizations:
sdk: flutter

dev_dependencies:
flutter_sheet_localization_generator: <latest>
build_runner: <latest>
copied to clipboard
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 : https://docs.google.com/spreadsheets/d/<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();

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

@override
Future<AppLocalizationsData> load(Locale locale) =>
SynchronousFuture<AppLocalizationsData>(localizedLabels[locale]!);
@override
bool shouldReload(AppLocalizationsDelegate old) => false;
}

copied to clipboard
3. Generate your localizations
Run the following command to generate a lib/localization.g.dart file :
flutter packages pub run build_runner build
copied to clipboard
4. Configure your app
Update your Flutter app with your newly created delegate :
MaterialApp(
locale: AppLocalizations.languages.keys.first, // <- Current locale
localizationsDelegates: [
const AppLocalizationsDelegate(), // <- Your custom delegate
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
],
supportedLocales:
AppLocalizations.languages.keys.toList(), // <- Supported locales
// ...
);
copied to clipboard
5. Display your labels
final labels = AppLocalizations.of(context);
print(labels.dates.month.february);
print(labels.templated.hello(firstName: "World"));
print(labels.templated.contact(Gender.male, lastName: "John"));
copied to clipboard
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)
fr
en




example.man(Gender.male)
This is a man title on home page
homme
man


example.man(Gender.female)
This is a woman title on home page
femme
woman




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 :




Key
fr
en




example.man(Gender.male)
homme
man


example.man(Gender.female)
femme
woman




See example for more details.
Plurals
The conditionals can be used the same way for plurals :
Example :




Key
fr
en




example.man(Plural.zero)
hommes
man


example.man(Plural.one)
homme
man


example.man(Plural.multiple)
hommes
men




From your Dart code, you can then define an extension :
extension PluralExtension on int {
Plural plural() {
if (this == 0) return Plural.zero;
if (this == 1) return Plural.one;
return Plural.multiple;
}
}
copied to clipboard
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"));
copied to clipboard
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));
copied to clipboard
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(...)




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

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

/// Code
print(labels.values.today(date: DateTime.now()));
copied to clipboard
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.