csv_localizations

csv_localizations

A minimal CSV localization package for Flutter.

Store translations for multiple languages in a single CSV file.

One language per column - one translation per row.

Install

Add csc_localizations and flutter_localizations to your pubspec.yaml.

dependencies:
  flutter_localizations:
    sdk: flutter
  csv_localizations: <last-version>

Add a single CSV file asset to your pubspec.yaml.

flutter:
  assets:
    - assets/translations.csv

Add CsvLocalizationsDelegate and supported locales to MaterialApp.

MaterialApp(
  localizationsDelegates: [
    // delegate from flutter_localization
    ...GlobalMaterialLocalizations.delegates,
    // delegate from csv_localizations
    CsvLocalizationsDelegate(path: 'assets/translations.csv'),
  ],
  supportedLocales: [
    Locale('en'),
    Locale('nb'),
  ],
}

Note on iOS

Add supported locales to ios/Runner/Info.plist as described here

Example:

<key>CFBundleLocalizations</key>
<array>
	<string>en</string>
	<string>nb</string>
</array>

Format

A CSV file is a simple table-as-a-text-file with comma separated values as columns and new lines as rows.

In our case columns represents translations for a specific language and rows represent translations for a given key.

First row are supported language/country codes. First column are keys for localized values.

Example table:

key	en	nb
Hi	Hi	Hei
Dog	Dog	Hund
Cat	Cat	Cat

Tip (1) wrap multiline strings in quotation marks

Example CSV:

key,en,nb
Hi,Hi,Hei
Dog,Dog,Hund
Cat,Cat,Katt
my_img,assets/en.png,assets/nb.png

Tip (2) keys can point to local assets like images

API

Translate text using:

CsvLocalizations.instance.string('Hi')

Or add a String extension:

extension LocalizedString on String {
  String tr(BuildContext context) => CsvLocalizations.instance.string(this);
}

We don't want to pollute the String API by default

Now you could easily translate strings like this:

'Hi'.tr(context)

Note if a value does not exists for a given key, we return the key itself

We also support num, int and double via:

CsvLocalizations.instance.numValue('my_num')

CsvLocalizations.instance.intValue('my_int')

CsvLocalizations.instance.doubleValue('my_double')

Configurations

We support all the configurations from the csv package.

You can set it via CsvLocalizationsConfigurations when creating the CsvLocalizationsDelegate.

Here are the default configurations:

  const CsvLocalizationsConfigurations({
    this.fieldDelimiter = ',',
    this.textDelimiter = '"',
    this.textEndDelimiter = '"',
    this.eol = '\n',
    this.convertEmptyTo = '',
    this.allowInvalid = true,
    this.shouldParseNumbers = true,
  });

Example

See example