Sync Wording

This tool allows you to manage your app's wording with a simple Google Sheets file. Just create a sheet with columns for keys and wording. This tool will generate wording files. Your product owner will be able to edit the application's wording themselves.

Quick Start

You can find a sample sheet here, but it's just a simple sheet with one column for keys and columns for languages like this:

Keys	English	French
user.firstname	Firstname	Prénom
user.lastname	Lastname	Nom

Installation

• Install sync-wording as a dev dependency: flutter pub add dev:sync_wording
• Create a wording config file named wording_config.yaml at the project root location.

sheetId: "your.sheet.id"
output_dir: "lib/localizations"
languages:
  en:
    column: 2
  fr:
    column: 3
    # column : 1='A', 2='B', ...

Running

This tools accepts 2 modes : download wording from GoogleSheet, or upload local wordings to GoogleSheet.

To download wordings from a GoogleSheet, you can run this command:

dart pub run sync_wording

To upload the local wordings to the GoogleSheet, run this command:

dart pub run sync_wording --upload

You will be asked to grant access to Google Sheets:

> Task :app:downloadWording
Please open the following address in your browser:
  https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=...

• Open the URL in your browser
• Grant access

[Authorization Sample]

Downloading the wordings will update the wording files: ${output_dir}/intl_en.arb and ${output_dir}/intl_fr.arb (in this example)

Uploading the wordings will update the GoogleSheet according to these wording files.

Placeholders

You can specify placeholders in your translations, with their type and format:

Hello {name} => Creates a default placeholder
Hello {name|String} => Creates a 'String' placeholder
It is {now|DateTime|hh:mm:ss} => Creates a 'DateTime' placeholder that will be formatted like '14:09:15'

(separator is |)

This also works with plurals, for example:

{days, plural, zero{today} one{tomorrow} other{in {days|int} days}}

Configuration options

Sheet names

If your Google Sheets document contains many sheets, all sheets will be considered as valid input sheets. If you only want to use a subset of these sheets, you can specify the sheet names needed as input:

sheetNames: ["Commons", "MyApp"]

Key column

By default, the column containing the translation keys is the first column (column 'A'), but you can specify another key column if your Google Sheets document has a different format.

key_column: 2 # default : 1

Starting row for values

By default, the first row is considered as a header, and valid keys and translations start at the second row. If your Google Sheets document is not in this format, you can specify the row from which translations will be taken into account:

sheet_start_index: 3 # default : 2

Wording validation

In your Google Sheets, you can add a column to indicate that it's a valid translation:

Keys	English	French	Validation
user.firstname_title	Firstname	Prénom	OK
user.lastname_title	Lastname	Nom	NOT OK

Then add this to your configuration file:

validation:
  column: 5
  expected: "OK"

If no validation is specified, everything is considered as valid.

Fallback translations

When a translation is missing in one language, you can configure the tool to automatically use the translation from a default language as fallback. This is useful to ensure all languages have complete translations.

fallback:
  enabled: true
  default_language: "en"
  # When a translation is missing in a language, use the translation from default_language

If fallback is not specified, no fallback behavior is applied and missing translations will be reported as warnings.

Localization classes generation

Executing this program will generate the .arb localization files. But it can go further: If your Flutter project is configured to use localizations, with a proper l10n.yaml file, this program can automatically generate the localization Dart classes by running the flutter gen-l10n command itself, or even fvm flutter gen-l10n if you chose fvm as the Flutter version manager for your project. You can simply add this to your wording_config.yaml file:

gen_l10n:
  auto_call: true
  with_fvm: true

Use your own Google Application

By default, the tool uses a pre-configured Google Application. If you want to use your own Google Application:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API for your project
4. Go to "Credentials" and create a new OAuth 2.0 Client ID
5. Configure the OAuth consent screen if not already done
6. Download the client credentials or copy the client ID and client secret

Then add these credentials to your wording_config.yaml:

credentials:
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  credentials_file: ".google_access_token.json" # Optional: defaults to .google_access_token.json

The credentials_file is where the OAuth tokens will be stored. Make sure to add this file to your .gitignore to keep your tokens secure.

Options

This tool supports 2 options:

• --config : Configuration file path (Optional: defaults to ./wording_config.yaml)
• --help : Display help info
• --upload : Run the upload wording process

Configuration examples

Minimal configuration of a wording_config.yaml file:

sheetId: "your.sheet.id"
output_dir: "lib/localizations"
languages:
  en:
    column: 2
  fr:
    column: 3

Complete configuration of a wording_config.yaml file:

sheetId: "your.sheet.id"
output_dir: "lib/localizations"
sheetNames: ["Commons", "MyApp"] # (Optional)
sheet_start_index: 2 # (Optional) defaults to 2

# column values : 1='A', 2='B', ...
key_column: 1 # (Optional) defaults to 1
languages:
  en:
    column: 2
  fr:
    column: 3
validation: # (Optional)
  column: 4
  expected: "OK"

fallback: # (Optional)
  enabled: true
  default_language: "en"

credentials: # (Optional)
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  credentials_file: ".google_access_token.json" # (Optional: defaults to .google_access_token.json)

gen_l10n: # (Optional)
  auto_call: true
  with_fvm: true # (Optional)