gen_l10n_utils 1.0.4

A CLI tool for merging, flattening, and managing gen_l10n translation files.

gen_l10n_utils

A command-line tool for managing Flutter application localization resources.

Overview

Here's a quick overview of the available commands:

• create-config: Creates a configuration file (gen_l10n_utils.yaml) in your project's root directory.
• translate: Creates or updates translation files for specified languages based on the base language.
• gen-arb: Generates ARB files by merging translation files from your project.

Features

• Configuration Management: Create and update localization configuration files
• ARB Generation: Generate ARB (Application Resource Bundle) files for translations
• Language Support: Configure multiple languages with a default language
• Simple CLI Interface: Easy-to-use commands with helpful options
• Nested JSON Support: Merge nested JSON structures into flat dot notation
• Duplicate Key Detection: Automatically detect and resolve duplicate translation keys within each language
• Translation Management: Create or update translation files for a specific language based on the base language

Installation

Add the package to your pubspec.yaml:

dependencies:
  gen_l10n_utils: ^1.0.4

Or install it in your project:

dart pub add gen_l10n_utils

Or install it globally:

dart pub global activate gen_l10n_utils

Usage

Note: A configuration file (gen_l10n_utils.yaml) is required at your project's root level.

Creating a configuration file gen_l10n_utils create-config

dart run gen_l10n_utils create-config --base-language en --languages en,de,fr
# or
dart run gen_l10n_utils create-config -b en -l en,de,fr

This creates an gen_l10n_utils.yaml file in your project root with your specified languages:

base_language: en
languages:
  - en
  - de
  - fr

Options:

• --base-language or -b: Base language code (ISO 639-1) [default: **en**]
• --languages or -l: Language codes to support (comma separated) [default: **en**]

Translating ARB files gen_l10n_utils translate

dart run gen_l10n_utils translate
# or
dart run gen_l10n_utils translate --language fr
# or
dart run gen_l10n_utils translate -l fr

This command:

• Creates or updates translation files for a specific language based on the base language.
• Adds missing keys from the base language to the target language files.
• Removes keys from the target language files that no longer exist in the base language files.
• Can automatically add the language to the config file if it is not already present.
• If no language is specified, the command will run for all languages defined in the configuration file.
• ℹ️ Displays the language currently being processed in the console output.

Options:

• --language or -l: The language code to create translations for (optional). If not specified, all languages in the config will be processed.

Generating ARB files gen_l10n_utils gen-arb

dart run gen_l10n_utils gen-arb

This command:

• Finds all .arb files in your project
• Detects languages based on directory paths
• Merges translations into combined ARB files (app_en.arb, etc.) in the lib/l10n directory
• Detects duplicate keys within each language and resolves conflicts (first occurrence wins)

The command automatically:

• Identifies language by checking directory paths containing language codes
• Merges multiple ARB files for the same language
• Detects and reports duplicate key conflicts within each language
• Creates output files in the lib/l10n directory

Generating Flutter Localization Files

After running gen_l10n_utils gen-arb to create your merged ARB files, you need to run Flutter's localization code generation tool to create the Dart classes:

flutter gen-l10n

This command will process the ARB files in your lib/l10n directory and generate the necessary Dart code according to your Flutter project's configuration.

Alternatively, if you're using the flutter_localizations package with generate: true in your pubspec.yaml, this generation will happen automatically when you build or run your app.

For more information on Flutter's internationalization system, see the [official documentation](https://docs.flutter.dev/development/accessibility-and-localization/internationalization).

Directory Structure Requirements

This package works with any common Flutter project structure, as long as your translation files follow these rules:

• All `.arb` files must be within the `/lib` folder
• Files must be placed in language-specific directories matching the ISO language codes from your config
• The directory path must include the language code (e.g., `/en/`, `/de/`, etc.)

Examples of supported structures:

• lib/features/feature1/l10n/en/translations.arb
• lib/core/l10n/en/common.arb
• lib/modules/auth/assets/en/auth_strings.arb
• lib/en/app_translations.arb

The tool will:

1. Find all `.arb` files under `/lib`
2. Determine the language by checking directory paths
3. Merge all files for each language
4. Generate combined output files named app_[lang].arb (e.g., app_en.arb, app_de.arb)
5. Place generated files in the lib/l10n directory

Duplicate Key Detection

When merging multiple ARB files for the same language, the tool automatically detects duplicate keys with different values. When duplicates are found:

• The first occurrence of each key is used in the final output
• A warning is displayed showing all conflicts detected
• Each conflict report shows the source files and values involved

Example warning:

⚠️ Warning: Found 1 key conflicts in en files:

Key "settings.title" has conflicts:

Used value: "Settings" from lib/features/settings/l10n/en/settings.arb

Ignored value: "App Settings" from lib/features/app/l10n/en/app.arb

First occurrence of each key was used in the merged files.

Nested JSON Support

This tool allows you to use nested JSON structures in your translation files, which makes organization easier. When merging files, the tool will appropriately handle these structures and produce properly formatted ARB files compatible with Flutter's localization system.

For example, you can organize your translations like this:

{
    "auth": {
        "buttons": {
            "login": "Login",
            "register": "Register"
        },
        "forgotPassword": "Forgot Password"
    }
}

The tool will merge and maintain these nested structures in the final output files, enabling you to keep your translations organized by feature or section.

Integration with Flutter Localization

The generated ARB files are compatible with Flutter's [flutter_localizations](https://api.flutter.dev/flutter/flutter_localizations-library.html) package and the [gen_l10n](https://pub.dev/packages/intl_translation) tool.

After generating your ARB files, you can use them with Flutter's localization system by configuring your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter

flutter:
  generate: true
  uses-material-design: true

flutter_intl:
  enabled: true
  arb_dir: lib/l10n
  output_dir: lib/generated

Configuration

The package requires gen_l10n_utils.yaml in your project root:

base_language: en
languages:
  - en
  - de
  - fr

License

BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.