Auto Easy Localization

🌐 A powerful Dart/Flutter tool for automated translation and localization management using Google Translate's free API.

Features

  • ✨ Smart Translation Mode: Only translates missing keys, preserving existing translations
  • πŸš€ Batch Processing: Efficient batch translation with configurable delays
  • πŸ“Š Progress Tracking: Real-time progress bar with ETA and statistics
  • πŸ”„ Auto-retry: Configurable retry mechanism for failed translations
  • πŸ“ JSON Support: Works with nested JSON translation files
  • βš™οΈ pubspec.yaml Configuration: All configuration is managed through pubspec.yaml
  • 🌍 70+ Languages: Support for all Google Translate supported languages
  • πŸ›‘οΈ Error Handling: Robust error handling with fallback to original text

Installation

As a Development Dependency

Add to your pubspec.yaml:

dev_dependencies:
  auto_easy_localization: ^1.0.1

Or run the following command:

flutter pub add auto_easy_localization --dev

Quick Start

  1. Create your source translation file (assets/translations/en.json):
{
  "navigation": {
    "home": "Home",
    "profile": "Profile",
    "settings": "Settings"
  },
  "forms": {
    "validation": {
      "required": "This field is required",
      "email": "Please enter a valid email"
    }
  }
}
  1. Configure in pubspec.yaml:
auto_easy_localization:
  source_locale: en
  target_locales: [es, fr, de, tr]
  translations_path: assets/translations
  delay_between_requests: 100
  max_retries: 3
  1. Run the tool:
dart run auto_easy_localization
  1. Generated files will be created automatically:
    • assets/translations/es.json (Spanish)
    • assets/translations/fr.json (French)
    • assets/translations/de.json (German)
    • assets/translations/tr.json (Turkish)

Configuration

All configuration is managed through your pubspec.yaml file. Add the auto_easy_localization section with your desired settings:

auto_easy_localization:
  source_locale: en # Source language (required)
  target_locales: [tr, es, fr, de, it] # Target languages (required) - can also use presets: european, global, asian
  translations_path: assets/translations # Path to translation files (optional, default: assets/translations)
  delay_between_requests: 100 # Delay between API calls in ms (optional, default: 100)
  max_retries: 3 # Maximum retry attempts (optional, default: 3)

Configuration Options

Option Type Required Default Description
source_locale String βœ… en The source language code
target_locales List βœ… [tr, es, fr, de] List of target language codes OR preset keyword (european, global, asian)
translations_path String ❌ assets/translations Path to translation files directory
delay_between_requests int ❌ 100 Delay between API requests (milliseconds)
max_retries int ❌ 3 Maximum number of retry attempts for failed translations
excluded_keys_path String ❌ assets/excluded_keys.json Path to excluded keys file

Default Configuration

If no configuration is found in pubspec.yaml, the tool will use these defaults:

auto_easy_localization:
  source_locale: en
  target_locales: [tr, es, fr, de]
  translations_path: assets/translations
  delay_between_requests: 100
  max_retries: 3
  excluded_keys_path: assets/excluded_keys.json

Preset Configurations

The tool includes predefined locale sets for common use cases. You can use these presets in two ways:

Simply use preset keywords as string values for target_locales:

auto_easy_localization:
  source_locale: en
  target_locales: european # Uses predefined European language set
  translations_path: assets/translations

Available Presets:

European Languages (european)

auto_easy_localization:
  source_locale: en
  target_locales: european
  # Includes: es, fr, de, it, pt, nl, sv, da, no, tr

Global Languages (global)

auto_easy_localization:
  source_locale: en
  target_locales: global
  # Includes: es, fr, de, it, pt, ru, ja, ko, zh, ar, hi, tr

Asian Languages (asian)

auto_easy_localization:
  source_locale: en
  target_locales: asian
  # Includes: zh, ja, ko, th, vi, id, ms, hi, bn

Option 2: Manual List Configuration

Alternatively, you can specify locales manually as a list:

auto_easy_localization:
  source_locale: en
  target_locales: [es, fr, de, it, pt, nl, sv, da, no, tr]
  translations_path: assets/translations

Advanced Features

Smart Translation Mode

The tool automatically detects:

  • Missing locale files and creates them
  • Missing translation keys in existing files and adds them
  • Preserves existing translations to avoid overwriting manual edits

Progress Tracking

Real-time progress display shows:

  • Current locale being processed
  • Completion percentage
  • Elapsed time and ETA
  • Number of keys processed
  • Animated spinner for visual feedback

Error Handling

  • Automatic retry with exponential backoff
  • Fallback to original text if translation fails
  • Detailed error messages and validation
  • Service availability checking

Supported Languages

The tool supports 70+ languages including:

Code Language Code Language Code Language
en English es Spanish fr French
de German it Italian pt Portuguese
ru Russian ja Japanese ko Korean
zh Chinese ar Arabic hi Hindi
tr Turkish nl Dutch sv Swedish

View full language list

File Structure

assets/
└── translations/
    β”œβ”€β”€ en.json          # Source locale
    β”œβ”€β”€ es.json          # Auto-generated
    β”œβ”€β”€ fr.json          # Auto-generated
    β”œβ”€β”€ de.json          # Auto-generated
    └── tr.json          # Auto-generated

JSON Structure Support

The tool handles nested JSON structures:

{
  "app": {
    "title": "My App",
    "navigation": {
      "home": "Home",
      "settings": "Settings"
    }
  },
  "errors": {
    "network": "Network error occurred",
    "validation": {
      "required": "This field is required",
      "email": "Invalid email format"
    }
  }
}

Performance & Rate Limiting

  • Default delay: 100ms between requests
  • Configurable retries: 3 attempts by default
  • Batch processing: Processes all keys for each locale
  • Intelligent waiting: Respects Google's rate limits

Examples

Basic Usage

# Run with pubspec.yaml configuration
dart run auto_easy_localization

Configuration Examples

Minimal Configuration

# pubspec.yaml
auto_easy_localization:
  source_locale: en
  target_locales: [es, fr, de, it]

Using Presets

# pubspec.yaml
auto_easy_localization:
  source_locale: en
  target_locales: european # Automatically includes 10 European languages

Advanced Configuration

# pubspec.yaml
auto_easy_localization:
  source_locale: en
  target_locales: global # Includes 12 major world languages
  translations_path: lib/l10n
  delay_between_requests: 1500
  max_retries: 5

Custom Source Locale

# pubspec.yaml
auto_easy_localization:
  source_locale: es
  target_locales: [en, fr, de, pt]
  translations_path: assets/translations

Troubleshooting

Common Issues

  1. "Source locale file not found"

    • Ensure your source locale file exists (e.g., assets/translations/en.json)
    • Check the translations_path in your pubspec.yaml configuration

  2. "No auto_easy_localization configuration found"

    • Add the auto_easy_localization section to your pubspec.yaml
    • Ensure proper YAML indentation and syntax

  3. "Google Translate service not available"

    • Check internet connection
    • Verify you're not being rate limited
    • Try increasing delay_between_requests in your configuration

  4. "Translation failed"

    • Tool automatically falls back to original text
    • Check logs for specific error details
    • Verify target language codes are valid

Rate Limiting

If you encounter rate limiting, adjust your configuration:

auto_easy_localization:
  delay_between_requests: 2000 # Increase delay
  max_retries: 5 # More retry attempts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Acknowledgments

  • Uses Google Translate's free API
  • Built for Flutter/Dart localization workflows
  • Inspired by the need for automated translation tools

Made with ❀️ for the Flutter community

Libraries

auto_easy_localization