flutter_localization_updater 1.0.0

A Flutter package that automatically updates localizations from Google Sheets and integrates with easy_localization.

flutter_localization_updater

A Flutter package that automatically updates localizations from Google Sheets and integrates seamlessly with easy_localization.

Features

• 🔄 Automatic Updates: Fetch translations from Google Sheets automatically
• 📱 Easy Integration: Works with easy_localization out of the box
• ⏰ Smart Caching: Configurable update intervals to avoid unnecessary API calls
• 🌍 Multi-language Support: Support for multiple locales
• 📁 Dynamic Loading: Load translations from both bundled assets and dynamically updated files

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_localization_updater: ^1.0.0

Setup

1. Google Sheets API Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API
4. Create credentials (API Key)
5. Create a Google Sheet with your translations

2. Google Sheet Structure

Your Google Sheet should have the following structure:

Key	en	nl	es
general_header_title	Welcome	Welkom	Bienvenido
general_searching_location	Searching location...	Locatie zoeken...	Buscando ubicación...

3. Create Localization Files

Before setting up the localization service, you need to create the initial JSON files for your supported locales. You can do this manually or use the provided command-line tool:

# Create default localization files (en, nl)
dart run localize

# Create files for specific locales
dart run localize --locales=en,nl,fr,es

# Specify custom output directory
dart run localize --output-dir=assets/translations

# Use a custom template file
dart run localize --template-file=my_template.json

This will create empty JSON files that you can fill in with your own translations. The files will be created in assets/localizations/ by default (e.g., en.json, nl.json).

Command Options:

• --locales, -l: Comma-separated list of locale codes (default: en,nl)
• --output-dir, -o: Output directory for localization files (default: assets/localizations)
• --template-file, -t: Path to a template JSON file to use as base

4. Basic Usage

import 'package:flutter/material.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter_localization_updater/flutter_localization_updater.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize localization service
  final localizationService = LocalizationService(
    config: LocalizationConfig(
      googleSheetApiKey: 'YOUR_GOOGLE_SHEETS_API_KEY',
      sheetId: 'YOUR_GOOGLE_SHEET_ID',
      supportedLocales: ['en', 'nl', 'es'],
      updateIntervalMs: 24 * 60 * 60 * 1000, // 24 hours
    ),
  );

  // Check and update localizations
  await localizationService.checkAndUpdateLocalizations();

  // Initialize easy_localization
  await EasyLocalization.ensureInitialized();

  runApp(EasyLocalization(
    supportedLocales: const [Locale('en'), Locale('nl'), Locale('es')],
    path: 'assets/localizations',
    fallbackLocale: const Locale('en'),
    assetLoader: CustomAssetLoader(), // Use the custom asset loader
    child: MyApp(),
  ));
}

API Reference

LocalizationConfig

Configuration class for the localization service.

LocalizationConfig({
  required String googleSheetApiKey,
  required String sheetId,
  String baseUrl = "https://sheets.googleapis.com/v4/spreadsheets/",
  int updateIntervalMs = 24 * 60 * 60 * 1000, // 24 hours
  List<String> supportedLocales = const ['en', 'nl'],
  String lastUpdateKey = 'last_localization_update',
})

Parameters:

• googleSheetApiKey: Your Google Sheets API key
• sheetId: The ID of your Google Sheet (found in the URL)
• baseUrl: Base URL for Google Sheets API (usually don't change this)
• updateIntervalMs: How often to check for updates (in milliseconds)
• supportedLocales: List of supported locale codes
• lastUpdateKey: Key for storing last update timestamp

LocalizationService

Main service class for managing localizations.

LocalizationService({
  required LocalizationConfig config,
  Dio? dio,
})

Methods:

• updateLocalizations(): Force update localizations from Google Sheets
• checkAndUpdateLocalizations(): Check if update is needed and update if necessary
• shouldUpdateLocalizations(): Check if localizations need updating
• getLocalizationsPath(): Get the path to localizations directory

CustomAssetLoader

Custom asset loader for easy_localization that loads from both bundled assets and dynamically updated files.

CustomAssetLoader()

Example

See the example/ directory for a complete working example.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.