sheet_loader_localization

Sheet Localization Generator

Download a CSV file and generate localization keys from an online Google Sheet to work with easy_localization and easy_localization_loader.

This tool is inspired by flutter_sheet_localization_generator and the original author RinLV.

🔩 Installation

Add to your pubspec.yaml:

dependencies:
  easy_localization: <latest_version>
  easy_localization_loader: <latest_version>

dev_dependencies:
  build_runner: <latest_version>
  sheet_loader_localization: <latest_version>

🔌 Usage

1. Create a CSV Google Sheet

Create a sheet with your translations (follow the format below; example sheet here):

CSV example

2. Share the Sheet

There are two options:

  • If your Google Sheet is public, keep the setup as-is.
  • If your Google Sheet is private, follow these steps:

    1. Enable Google Drive API and Generate an API Key
      Follow this guide: How to Use Google Drive API and Get an API Key

    2. Set the apiKey parameter in the @SheetLocalization annotation.

3. Declare the Localization Delegate

Create a Dart file (lib/utils/multi-languages/locale_keys.dart) with the following content:

import 'dart:ui';
import 'package:sheet_loader_localization/sheet_loader_localization.dart';

part 'locale_keys.g.dart';

@SheetLocalization(
  docId: 'DOCID',
  version: 1,
  outDir: 'resources/langs',
  outName: 'langs.csv',
  preservedKeywords: [],
  // OPTIONAL: Only required if your sheet is private
  apiKey: 'YOUR_GOOGLE_API_KEY',
)
class _LocaleKeys {}

4. Generate the Localizations

Run the command below to generate the localization file:

flutter pub run build_runner build
# or
flutter pub run build_runner build --delete-conflicting-outputs

5. Configure Your App

Follow the setup guide from the easy_localization README.

🚀 Google Sheets Automation (Recommended)

To eliminate the manual toil of translating keys, we provide an Automation Script that runs directly inside your Google Sheet. This bridges the gap between creating a key and having it ready for the Dart generator.

Why use the automation script?

  • Instant Multi-Language Support: Translate an entire sheet into 10+ languages (Vietnamese, French, Japanese, etc.) with one click.
  • Incremental Updates: Only translate new keys ("Fill Missing"), preserving your existing manual adjustments.
  • Error Highlighting: Automatically flags rows that fail to translate in red background for easy debugging.
  • Zero Configuration: Automatically detects language codes from your headers (e.g., vi_VN → vi).

Setup Automation

  1. In your Google Sheet, go to Extensions > Apps Script.
  2. Copy the code from localization_script.gs and paste it into the editor.
  3. Save the project, Click Run button and refresh your Spreadsheet browser tab.
  4. A new menu "🌐 Localization Hub" will appear in your toolbar.

Localization Hub Config

🛡️ Security & Privacy (For Engineers)

We prioritize data sovereignty and local execution:

  • Local Execution: This script runs entirely within your Google Workspace environment (Apps Script). No data is ever sent to third-party servers.
  • No Data Collection: We do not collect or track your sheet IDs, translation content, or user identity.
  • Direct API Usage: The script uses Google's built-in LanguageApp, communicating directly between your sheet and the translation service.
  • Transparent Code: 100% open-source. We encourage you to audit the code before adding it to your workflow.

⏱️ Productivity Comparison

Task Manual Workflow With This Tool & Script
Adding a new key (5 languages) ~10 mins (Manual Copy/Paste) < 10 seconds
Fixing translation errors Manual search & fix "Translate Selected" (2 clicks)
Handling placeholders High risk of breaking {var} Preserved via script logic
Security Audit Unknown 3rd party apps 100% Transparent Script

🛠 Troubleshooting

Ghosting Menus: If you see duplicate menus (like "Translation Tools" and "Localization Hub") after updating the script, simply refresh your browser tab. Google Sheets caches UI elements; a reload clears the old definitions.

⚡ Regeneration

To force regeneration of the CSV and localization files (due to caching), simply increment the version field in @SheetLocalization and rerun the build command.

❓ Why This Tool?

easy_localization supports code generation, but not directly from Google Sheets. This tool simplifies localization workflows by using Google Sheets (ideal for collaboration with non-devs) and supports Flutter null safety.

Libraries

sheet_builder
sheet_loader_localization