flutter-localization

flutter-localization

Flutter Localization Setup

Goal

Configures and implements internationalization (i18n) and localization (l10n) in a Flutter application. This skill manages dependency injection (flutter_localizations, intl), code generation configuration (l10n.yaml), root widget setup (MaterialApp, CupertinoApp, or WidgetsApp), .arb translation file management, and platform-specific configurations (iOS Xcode project updates). It ensures proper locale resolution and prevents common assertion errors related to missing localization delegates in specific widgets like TextField and CupertinoTabBar.

Decision Logic

• Determine App Root: Identify if the application uses MaterialApp, CupertinoApp, or WidgetsApp to inject the correct global delegates.

• Identify Target Platforms: If iOS is a target platform, Xcode project files (Info.plist / project.pbxproj) must be updated to expose supported locales to the App Store.

• Analyze Widget Tree: Check for isolated TextField or CupertinoTabBar widgets that might exist outside the root app's localization scope. If found, wrap them in explicit Localizations widgets.

• Determine Locale Complexity: If supporting languages with multiple scripts/regions (e.g., Chinese zh_Hans_CN), use Locale.fromSubtags instead of the default Locale constructor.

Instructions

Configure Dependencies Update pubspec.yaml to include required packages and enable code generation.

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

Configure Code Generation Create an l10n.yaml file in the project root to define the localization tool's behavior.

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: false

Define Supported Locales STOP AND ASK THE USER: "Which languages and regions do you want to support? Please provide a list of language codes (e.g., 'en', 'es', 'zh_Hans_CN')."

Create ARB Files Generate the template .arb file (e.g., lib/l10n/app_en.arb) and corresponding translation files. Implement placeholders, plurals, and selects as needed.

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "Standard greeting"
  },
  "greeting": "Hello {userName}",
  "@greeting": {
    "description": "Greeting with a parameter",
    "placeholders": {
      "userName": {
        "type": "String"
      }
    }
  },
  "nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
  "@nWombats": {
    "placeholders": {
      "count": {
        "type": "num",
        "format": "compact"
      }
    }
  }
}

Initialize Root App Import the generated localizations file and configure the root MaterialApp or CupertinoApp.

import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:your_app_name/l10n/app_localizations.dart'; // Adjust path based on synthetic-package setting

// Inside your root widget build method:
return MaterialApp(
  title: 'Localized App',
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en', ''), // English
    Locale('es', ''), // Spanish
    Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans', countryCode: 'CN'),
  ],
  home: const MyHomePage(),
);

Handle Isolated Widgets (If Applicable) If a TextField or CupertinoTabBar throws a missing MaterialLocalizations or Localizations ancestor error, inject a Localizations widget directly above it.

Localizations(
  locale: const Locale('en', 'US'),
  delegates: const <LocalizationsDelegate<dynamic>>[
    DefaultWidgetsLocalizations.delegate,
    DefaultMaterialLocalizations.delegate,
    DefaultCupertinoLocalizations.delegate,
  ],
  child: CupertinoTabBar(
    items: const <BottomNavigationBarItem>[...],
  ),
)

Configure iOS Project STOP AND ASK THE USER: "Does this project target iOS? If yes, I will provide instructions for updating the Xcode project." If yes, instruct the user to:

Open ios/Runner.xcodeproj in Xcode.

• Select the Runner project in the Project Navigator.

• Go to the Info tab.

• Under Localizations, click + to add all supported languages.

Validate and Fix Run flutter gen-l10n. Verify that app_localizations.dart is generated successfully. If compilation fails with "No MaterialLocalizations found" or "CupertinoTabBar requires a Localizations parent", traverse up the widget tree from the failing widget and ensure localizationsDelegates are properly provided.

Constraints

• No Synthetic Packages: Ensure synthetic-package: false is considered if the user's environment requires direct source generation, or rely on standard generate: true behavior for modern Flutter versions. Do not use package:flutter_gen imports if synthetic-package: false is set.

• Widget Requirements: TextField MUST have a MaterialLocalizations ancestor. CupertinoTabBar MUST have a Localizations ancestor.

• Complex Locales: Always use Locale.fromSubtags for languages requiring script codes (e.g., Chinese zh_Hans, zh_Hant).

• ARB Syntax: Ensure all placeholders used in .arb strings are explicitly defined in the corresponding @ metadata object.

• Escaping: If literal curly braces {} or single quotes ' are needed in .arb files, enable use-escaping: true in l10n.yaml and use consecutive single quotes '' for escaping.

Weekly Installs978Repositoryflutter/skillsGitHub Stars725First Seen14 days agoSecurity AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled oncodex950opencode946cursor946gemini-cli945github-copilot945kimi-cli943