Localization (L10n)
Relevant source files
The following files were used as context for generating this wiki page:
Localization (L10n) in the MoodTune application provides a framework for multi-language support, specifically targeting English (en) and Spanish (es) locales. The system leverages Flutter's built-in internationalization tools and ARB (Application Resource Bundle) files to manage UI strings, ensuring that audio analysis results, mood descriptors, and navigation elements are accessible to a global audience.
The architecture follows the standard Flutter localization workflow where source ARB files are used to generate Dart code. This process is integrated into the build pipeline, allowing for automatic updates to the generated localization classes whenever the application runs or when specific generation commands are executed.
Sources: README.md:88-100, CLAUDE.md:85-86
Framework Configuration
The localization system is primarily configured through a root-level l10n.yaml file. This file defines the directory structure for translation resources and specifies the template for English as the primary language.
| Key | Value | Description |
|---|---|---|
arb-dir | lib/l10n/arb | The directory containing the .arb translation files. |
template-arb-file | app_en.arb | The source of truth for all localization keys. |
output-localization-file | app_localizations.dart | The name of the generated Dart class. |
output-dir | lib/l10n/gen | Where the generated localization code is stored. |
nullable-getter | false | Ensures that localization getters do not return null values. |
Sources: l10n.yaml:1-6
The pubspec.yaml file further enables this system by setting generate: true and including the flutter_localizations SDK package as a dependency.
Sources: pubspec.yaml:20-21, pubspec.yaml:41
Development Workflow
Localization involves a three-step process to add or update UI strings. The application utilizes the intl package to handle formatting and pluralization within these translations.
- Define Strings: New keys are added to
lib/l10n/arb/app_en.arb. - Translate: Corresponding entries are added to locale-specific files, such as
app_es.arb. - Generate: The Flutter tool generates the necessary Dart classes.
The following sequence diagram illustrates the code generation flow:
Localization tools are also integrated into the project's build commands. Developers can trigger generation manually using flutter gen-l10n --arb-dir="lib/l10n/arb", though the process runs automatically during flutter run.
Sources: README.md:88-98, CLAUDE.md:52-54, pubspec.yaml:29
Platform Integration
Localization settings must be registered at the platform level to ensure the operating system recognizes the supported languages.
iOS Configuration
For iOS, the CFBundleLocalizations key in ios/Runner/Info.plist must be updated to include new locales. This allows the system to correctly handle language preferences and font rendering.
Sources: README.md:100
Android Configuration
Android handles locale changes through the AndroidManifest.xml. The MainActivity is configured to listen for locale and layoutDirection changes, preventing the activity from restarting when the user switches system languages.
<activity
android:name=".MainActivity"
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
android:hardwareAccelerated="true">
Sources: android/app/src/main/AndroidManifest.xml:7-14
Project Tooling & Standards
The project uses a global cspell.json configuration to ensure localization-related terms and generated files are handled correctly by spell checkers.
- Exclusions: Generated localization files in
**/gen/**are ignored by the spell checker to avoid false positives on translated content. - Dictionary: The term
localizationsis added to the project's custom word list to maintain consistency across the codebase.
Sources: cspell.json:16, cspell.json:28
Localization files are also excluded from coverage reporting and formatting via a custom header defined in the l10n.yaml file:
header: "// dart format off\n// coverage:ignore-file"
Sources: l10n.yaml:10
Summary
Localization in MoodTune is a structured system centered around ARB files and automated code generation. By centralizing strings in lib/l10n/arb and leveraging the flutter_localizations framework, the app maintains a clean architecture that separates UI logic from translated content, facilitating the addition of new languages like Spanish alongside the default English implementation.