Search packages, repositories and app categories

Package detailsv0.11.1

arb_utils

A set of tools to work with .arb files (the preferred Dart way of dealing with i18n/l10n/translations)

AndroidiOSWebmacOSWindowsLinux
30-day downloads
12.6K
Likes
23
Pub points
140

Install package

flutter pub add arb_utils

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

A collection of utilities designed to streamline working with .arb files in Flutter applications, enabling efficient management of internationalization and localization. It supports parsing, validating, and converting arb files, making it easier to maintain translations across multiple languages. The package integrates seamlessly with Dart's i18n workflow and enhances developer productivity by automating repetitive tasks related to translation files. It is particularly useful for teams managing large-scale multilingual apps.

Use cases

  • Managing translation files in Flutter apps
  • Converting between ARB and other formats
  • Validating translation keys
  • Automating localization workflows
  • Generating code from ARB files

Key features

  • Supports ARB file parsing and validation
  • Converts ARB to JSON and other formats
  • Integrates with Flutter's i18n system
  • Command-line interface for automation
  • Ensures consistent key naming and structure

Suitable for

  • Flutter developers using ARB for localization
  • Teams managing multiple language translations
  • CI/CD pipelines for i18n
  • Projects requiring automated translation handling

Considerations

  • Requires familiarity with ARB file format
  • Limited to ARB-based workflows
  • May need additional setup for CI integration
  • Not a full i18n framework but a toolset

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

arb_utils

Common actions to perform over .arb formatted strings

Usage

A simple usage example:

import 'package:arb_utils/arb_utils.dart';

main() {
  print('Generating .arb for translators...');
  var chkout = 'latestTranslationsProcessedBranch'; // or a49630b726c or HEAD^3 etc
  Process.runSync('git', 'checkout $chkout'.split(' '));
  var mainARBOld = File('lib/l10n/intl_en.arb').readAsStringSync();
  Process.runSync('git', 'checkout master'.split(' '));
  var mainARBNew = File('lib/l10n/intl_en.arb').readAsStringSync();
  File('lib/l10n/new_translations/intl_en.arb')
      .writeAsStringSync(sortARB(processNewKeys(mainARBNew, mainARBOld)));
  print('lib/l10n/new_translations/intl_en.arb generated');
}

Features

Manual language switching helpers

Normally there's the need of providing a way of manually changing the locale on runtime. Here is a super easy way of doing so depending on the state manager you use:
translation on runtime demo
The solution handles the persistance of the user selection for app restarts and so.

Provider/BLoC

Given that BLoC relies on Provider for working this solution will work easily for both state managers:

//make sure this line is written, your IDE may not add it automatically
import 'package:provider/provider.dart';
import 'package:arb_utils/state_managers/l10n_provider.dart';

//prefix your MaterialApp(//... with the following:
ChangeNotifierProvider(
      create: (_) => ProviderL10n(),
      child: Builder(builder: (context) {
        return MaterialApp(
          locale: context.watch<ProviderL10n>().locale,
          supportedLocales: AppLocalizations.supportedLocales,

//now add this widget wherever you want:
import 'package:arb_utils/arb_utils_flutter.dart';

LanguageSelectorDropdown(
  supportedLocales: AppLocalizations.supportedLocales,
  provider: context.read<ProviderL10n>(),
)
MobX/GetX/GetIt/Riverpod/Binder/Redux/etc

Pull Requests are always welcome :-D!

ArbClient

A way of getting your ARB translations dynamically, not hardcoded like S.of(context).key / AppLocalizations.of(context).key. It has been made with the pretension of supporting a way of getting the .arb files from the backend, on demand, but if it suits your use case, it just works. (PR are always welcome)

var arbClient = ArbClient(englishArbString, locale: 'en', onMissingKey: (key) => print('ARB key not found: $key'), exceptionOnMissingKey: kDebugMode, onMissingKeyValue: (key) => 'value of $key');
print(arbClient['hellowWorld']); // Hello World!
arbClient.reloadJson(json.decode(spanishArbString));
print(arbClient['hellowWorld']); // ¡Hola Mundo!
print(arbClient.get('helloName',{'name':'Nico'})); // ¡Hola Nico!
Standalone functions
sortARB

alters the order of every .arb key alphabetically, putting their @key metadata below every one

{
  "@aKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"simple description"
  },
  "aKey":"a simple key",
}

will be converted to:

{
  "aKey":"a simple key",
  "@aKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"simple description"
  }
}

You can also provide a custom sort function.

var arb1 = '''
{
    "clave":"valor",
    "@clave":{
        "description": "Descripcion"
    },
    "key":"value",
    "@key":{
        "description": "Description"
    }
}''';
var sortedArb1 = sortARB(arb1, (a, b) => a[1].compareTo(b[1]));
print(sortedArb1);
/*
{
    "key":"value",
    "@key":{
        "description": "Description"
    },
    "clave":"valor",
    "@clave":{
        "description": "Descripcion"
    }
}
*/

Know that the most common sortings are implemented out of the box with the following parameters

var sorted = sortARB(arbString, caseInsensitive: false, naturalOrdering: false, descendingOrdering: false);
diffARBs

Will generate a .arb formatted string with the keys that doesn't appear in both the provided .arb formatted arguments

var arb1 = '''
{
    "clave":"valor",
    "@clave":{
        "description": "Descripcion"
    },
    "key":"value",
    "@key":{
        "description": "Description"
    }
}''';
var arb2 = '''
{
    "clave":"valor",
    "@clave":{
        "description": "Descripcion"
    },
    "newKey":"new value",
    "@newKey":{
        "description": "new Description"
    }
}''';
var diffed = diffARBs(arb1, arb2);
print(diffed);
/*
{
    "key":"value",
    "@key":{
        "description": "Description"
    },
    "newKey":"new value",
    "@newKey":{
        "description": "new Description"
    }
}
*/
mergeARBs

Will include the latter .arb keys in the former one and output a .arb formatted string with the merged keys, privileging the latter ones

var former = '''{
  "aKey":"a simple key",
  "@aKey":{
    "description":"simple description"
  },
  "bKey":"a simple key",
  "@bKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"simple description"
  }
''';
var latter = '''{
  "aKey":"a MODIFIED simple key",
  "@aKey":{
    "description":"simple description"
  },
  "cKey":"a simple key",
  "@cKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"simple description"
  }
}''';
var merged = mergeARBs(former,latter);
print(merged);
/*
{
  "aKey":"a MODIFIED simple key",
  "@aKey":{
    "description":"simple description"
  },
  "bKey":"a simple key",
  "@bKey":{
    "description":"simple description"
  },
  "cKey":"a simple key",
  "@cKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"simple description"
  }
}
*/
processNewKeys

Compares an .arb formatted string with a previous version of itself and outputs a new .arb formatted string with the new keys found there (also the edited ones)

var oldVersion = '''{
  "aKey":"a simple key",
  "@aKey":{
    "description":"simple description"
  },
  "bKey":"a simple key",
  "@bKey":{
    "description":"simple description"
  },
  "cKey":"a simple key",
  "@cKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"simple description"
  }
}''';
var newVersion = '''{
  "aKey":"a MODIFIED simple key",
  "@aKey":{
    "description":"simple description"
  },
  "bKey":"a simple key",
  "@bKey":{
    "description":"simple description"
  },
  "cKey":"a simple key",
  "@cKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"A MORE ROBUST description"
  }
}''';
var newARB = processNewKeys(newVersion, oldVersion);
print(newARB);
/*
{
  "aKey":"a MODIFIED simple key",
  "@aKey":{
    "description":"simple description"
  },
  "zKey":"a simple key",
  "@zKey":{
    "description":"A MORE ROBUST description"
  }
}
*/

Bin scripts

Please run

dart pub global activate arb_utils

to enable arb_utils as an executable command on your system.

Sort

To easily sort an arb and update original file, use

arb_utils sort <INPUT FILE>

where <INPUT FILE> is a path to the input file.

Also, there are 3 flags for different sorting:

  • Case insensitive (--case-insensitive / -i): Whether to distinguish between lowercase and uppercase while ordering the keys.
  • Natural ordering (--natural-ordering / -n): Whether to take numbers as a single character and order them according to their numeric value (instead of ASCII one).
  • Descending (--descending / -d): Sort in descending order.

For example, to sort with case insensitive and in descending order, use:

arb_utils sort -i -d <INPUT FILE>
Add Entries

To programmatically add new entries to one or more arb files in one go, use

arb_utils add <key> --description '<description>' [locale:value...]

Example:

arb_utils add welcome --description 'Welcome message' en:'Welcome!' es:'¡Bienvenido!'

Or using a JSON template:

arb_utils add --json '{"welcome": "$VAL$", "@welcome": {"description": "Welcome message"}}' en:'Welcome!' es:'¡Bienvenido!'

The command will recursively find all .arb files in the current directory and its subdirectories by default. To specify specific files, use the --files (or -f) flag. New entries are added to the tail of the files by default. Use the --sort (or -s) flag to sort the files after adding. Note: The command will fail if values for all locales present in the .arb files are not provided.

List Keys

To list keys matching a regexp, use

arb_utils keys <regexp>

This will search in all .arb files found recursively by default. You can also specify files with --files flag.

Add Missing Default Metadata

To easily add missing metadata to an arb and update original file, use

arb_utils generate-meta <INPUT FILE>

where <INPUT FILE> is a path to the input file.

Reference

Check this article for understanding more about i18n with .arb in Flutter: https://phrase.com/blog/posts/flutter-localization/

Categories

Dependencies

Dependency list 6 items

Source repository

Projects using this package