Flutter Clear Cache Localization: Fix Translation Issues with Cache Clearing

Having trouble with Flutter translations not updating? Stuck with old translations after making changes? This guide covers every caching issue you'll encounter in Flutter localization and how to fix them.

Common Symptoms of Localization Cache Issues

Before diving into solutions, here are signs you have a caching problem:

• Translations don't update after modifying ARB files
• flutter gen-l10n completes but changes aren't visible
• Hot reload shows old translations
• Different translations on simulator vs real device
• Production app shows outdated strings

Quick Fix Commands

Here's every cache-clearing command you might need:

# Clear Flutter's pub cache
flutter pub cache repair

# Clean the project
flutter clean

# Get dependencies fresh
flutter pub get

# Regenerate localizations
flutter gen-l10n

# Full nuclear option
flutter clean && rm -rf .dart_tool && rm -rf build && flutter pub get && flutter gen-l10n

Understanding Flutter's Localization Cache Layers

Flutter localizations can be cached at multiple levels:

1. Dart Tool Cache (.dart_tool/)

The .dart_tool/ directory contains generated code, including your localization files:

# View generated localization files
ls .dart_tool/flutter_gen/gen_l10n/

# Output:
# app_localizations.dart
# app_localizations_en.dart
# app_localizations_es.dart
# app_localizations_fr.dart

To clear this cache:

rm -rf .dart_tool
flutter pub get
flutter gen-l10n

2. Build Cache (build/)

The build directory contains compiled artifacts:

# Clear build cache
flutter clean

# This removes:
# - build/
# - .dart_tool/
# - Generated files

3. Pub Cache (~/.pub-cache/)

The global pub cache stores downloaded packages:

# Repair pub cache (fixes corrupted packages)
flutter pub cache repair

# Clear entire pub cache (use sparingly)
flutter pub cache clean

# Re-download all dependencies
flutter pub get

4. IDE Cache

Your IDE may cache old generated code:

VS Code:

• Restart the Dart Analysis Server: Cmd+Shift+P → "Dart: Restart Analysis Server"
• Reload window: Cmd+Shift+P → "Developer: Reload Window"

Android Studio / IntelliJ:

• File → Invalidate Caches / Restart
• Build → Clean Project

Step-by-Step Cache Clearing Guide

Step 1: Identify the Problem

First, check if your ARB files are correct:

# Verify ARB file content
cat lib/l10n/app_en.arb

# Should show your updated translations:
{
  "@@locale": "en",
  "hello": "Hello World",
  "@hello": {
    "description": "Greeting message"
  }
}

Step 2: Regenerate Localizations

# Force regeneration
flutter gen-l10n

# Check the output
cat .dart_tool/flutter_gen/gen_l10n/app_localizations_en.dart

Step 3: Clean and Rebuild

# Clean project
flutter clean

# Get dependencies
flutter pub get

# Regenerate localizations
flutter gen-l10n

# Run the app
flutter run

Step 4: Full Reset (If Nothing Else Works)

#!/bin/bash
# full-reset.sh - Complete Flutter project reset

echo "🧹 Cleaning Flutter project..."
flutter clean

echo "🗑️ Removing generated files..."
rm -rf .dart_tool
rm -rf build
rm -rf ios/Pods
rm -rf ios/.symlinks
rm -rf ios/Flutter/Flutter.framework
rm -rf ios/Flutter/Flutter.podspec

echo "📦 Getting dependencies..."
flutter pub get

echo "🍎 Installing iOS pods..."
cd ios && pod install && cd ..

echo "🌍 Generating localizations..."
flutter gen-l10n

echo "✅ Reset complete! Run 'flutter run' to start."

Fixing Specific Cache Issues

Issue: Hot Reload Doesn't Update Translations

Hot reload doesn't regenerate localizations. You need hot restart:

// In your terminal while app is running:
// Press 'R' for hot restart (not 'r' for hot reload)

Or add this development helper:

class LocalizationDebugger extends StatelessWidget {
  final Widget child;

  const LocalizationDebugger({required this.child});

  @override
  Widget build(BuildContext context) {
    return Banner(
      message: Localizations.localeOf(context).toString(),
      location: BannerLocation.topEnd,
      child: child,
    );
  }
}

Issue: gen-l10n Doesn't Detect Changes

Check your l10n.yaml configuration:

# l10n.yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
synthetic-package: false  # Try changing this

Force regeneration:

# Delete existing generated files
rm -rf lib/l10n/generated/
rm -rf .dart_tool/flutter_gen/gen_l10n/

# Regenerate
flutter gen-l10n --verbose

Issue: Production App Shows Old Translations

This happens when you update translations but users have cached the old app:

// Add version checking for remote translations
class TranslationVersionChecker {
  static const String currentVersion = '1.2.0';

  static Future<void> checkForUpdates() async {
    final prefs = await SharedPreferences.getInstance();
    final cachedVersion = prefs.getString('translation_version');

    if (cachedVersion != currentVersion) {
      // Clear translation cache
      await _clearTranslationCache();
      await prefs.setString('translation_version', currentVersion);
    }
  }

  static Future<void> _clearTranslationCache() async {
    // Clear any locally cached translations
    final prefs = await SharedPreferences.getInstance();
    final keys = prefs.getKeys().where((k) => k.startsWith('translation_'));
    for (final key in keys) {
      await prefs.remove(key);
    }
  }
}

Issue: Different Translations on Different Devices

This often happens with remote/OTA translations:

class TranslationSyncService {
  static Future<void> forceSync() async {
    // 1. Clear local cache
    final cacheDir = await getTemporaryDirectory();
    final translationCache = Directory('${cacheDir.path}/translations');
    if (await translationCache.exists()) {
      await translationCache.delete(recursive: true);
    }

    // 2. Re-fetch from server
    await fetchLatestTranslations();

    // 3. Update last sync time
    final prefs = await SharedPreferences.getInstance();
    await prefs.setInt('last_translation_sync', DateTime.now().millisecondsSinceEpoch);
  }
}

Preventing Cache Issues

1. Use Consistent ARB File Structure

{
  "@@locale": "en",
  "@@last_modified": "2025-12-25T10:00:00Z",

  "greeting": "Hello",
  "@greeting": {
    "description": "Simple greeting"
  }
}

2. Add CI/CD Validation

# .github/workflows/localization.yml
name: Localization Check

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.0'

      - name: Clean and regenerate
        run: |
          flutter clean
          flutter pub get
          flutter gen-l10n

      - name: Verify no uncommitted changes
        run: |
          git diff --exit-code .dart_tool/flutter_gen/gen_l10n/

3. Add Development Shortcuts

// lib/dev/localization_tools.dart
import 'package:flutter/foundation.dart';

class LocalizationDevTools {
  static void printCurrentLocale(BuildContext context) {
    if (kDebugMode) {
      final locale = Localizations.localeOf(context);
      print('📍 Current locale: $locale');
      print('📍 Language: ${locale.languageCode}');
      print('📍 Country: ${locale.countryCode}');
    }
  }

  static void printAllTranslations(AppLocalizations l10n) {
    if (kDebugMode) {
      // Reflection isn't available, but you can list key translations
      print('🌍 Sample translations:');
      print('  - hello: ${l10n.hello}');
      // Add more as needed
    }
  }
}

Common Mistakes That Cause Cache Issues

Mistake 1: Editing Generated Files

Never edit files in .dart_tool/flutter_gen/gen_l10n/. They get overwritten.

❌ Wrong:

// Editing .dart_tool/flutter_gen/gen_l10n/app_localizations_en.dart
String get hello => 'Hello Modified'; // This will be lost!

✅ Right:

// Edit lib/l10n/app_en.arb instead
{
  "hello": "Hello Modified"
}

Mistake 2: Forgetting to Run gen-l10n

After modifying ARB files:

# Always run this after ARB changes
flutter gen-l10n

Or enable automatic generation in l10n.yaml:

# l10n.yaml
synthetic-package: true  # Generates on flutter pub get

Mistake 3: Incorrect l10n.yaml Path

# Wrong - path doesn't exist
arb-dir: src/l10n

# Right - matches your actual structure
arb-dir: lib/l10n

Debugging Checklist

When translations aren't updating, go through this checklist:

□ ARB file is saved and contains correct JSON
□ ARB file path matches l10n.yaml arb-dir
□ Template ARB file has @@locale key
□ Ran flutter gen-l10n
□ Generated files exist in .dart_tool/flutter_gen/gen_l10n/
□ Generated files contain updated translations
□ Ran flutter clean && flutter pub get
□ Restarted the app (not just hot reload)
□ IDE analysis server restarted
□ Device/simulator cache cleared (uninstall and reinstall app)

Conclusion

Most localization cache issues in Flutter come from:

1. Not running flutter gen-l10n after ARB changes
2. Using hot reload instead of hot restart for translation updates
3. Stale .dart_tool cache that needs clearing
4. IDE caching old generated code

The nuclear option that fixes 99% of issues:

flutter clean && rm -rf .dart_tool && flutter pub get && flutter gen-l10n && flutter run

Keep this command handy, and you'll never be stuck on a caching issue again.

Related Resources

• Flutter l10n.yaml Configuration Guide
• Common Flutter Localization Errors
• Flutter Localization Debugging Guide