Designing package:intl4x

[mosuem]

tl;dr

Replacing a Dart package by a Rust package using FFI and hooks for more features and reduced maintenance cost.

How it started

Basics

Internationalization (i18n) and localization (l10n) are at the heart of accessibility and success for many apps. Only ~20% of the worlds population speak English and only ~5% are native speakers. Most countries have their own languages, often multiple ones, with their own rules on how to display numbers, dates, how to sort lists of words etc.

All this made it clear that the Dart team must ship a library to handle this: package:intl. It is one of the most used packages on pub.dev and can handle most operations needed from such a library.

Problem

I18n is unfortunately quite complex, with data being updated twice a year, and many edge cases resulting in hard to write code. This results in a steady stream of bugs and missing features accumulating over time. All this results in a poor experience and high maintenance costs, exacerbated by the pre-Dart 1.0 code in package:intl.

Solution Options

1. Keep updating package:intl 🔴

This has the obvious drawbacks of continuing the existing problems, but the advantage of not starting from zero and a clear path forwards.

2. Write a new Dart library 🔴

Very high initial costs and some ongoing maintenance in the future but being able to do nice green field development with the associated freedoms in design.

3. Re-use existing libraries 🟢

There are many libraries for i18n, such as ICU4J (Java), ICU4C (C), or the new ICU4X (Rust). These are built and maintained by i18n teams and it would be great to be able to reuse their efforts to bring down maintenance.

Being a small team with many responsibilities, and wanting to use the i18n teams' expertise, we went with option 3.

Challenges

To reuse an existing package, we must solve some issues:

1. Bridge to the target language
2. Not increase code size
3. Translate into a Dart-y API
4. Keep all challenges invisible to users

Solutions

We selected ICU4X as a new modular library optimized for code size, helping with 2.. This gave the challenge of having to bridge to a Rust library via FFI solved using the diplomat codegen tool.
To ship the compiled Rust code with the Dart code, we introduced build hooks as a new Dart feature. To not increase code size, we need to treeshake the native code, which is done in the new link hooks. And finally, we needed to write a layer around the ICU4X generated API to make it feel comfortable for Dart users, keeping it as thin as possible to reduce maintenance.
To further reduce code size on the web, the library uses the existing ECMA Intl object in the browser bringing down the code size to virtually zero.

All this should happen in the background, giving users no indication performance-wise that they are using a package not written in Dart.

Technical details

When a user wants to format a date in year month day format, in Dart they will type (ref)

import 'package:intl4x/datetime_format.dart';
void main() {
  final date = DateTime(2021, 12, 17, 4, 0, 42);
  print(DateTimeFormat.yearMonthDay().format(date)); // Output: 'Dec 17, 2021'
}

this translates to an interface shared by native and web code (ref)

FormatterImpl ymd({
  DateTimeAlignment? alignment,
  DateTimeLength? length,
  YearStyle? yearStyle,
});

which is implemented by the native version as (ref)

@override
FormatterImpl ymd({
  DateTimeAlignment? alignment,
  DateTimeLength? length,
  YearStyle? yearStyle,
}) => DateFormatterX.ymd(
  this,
  localeX,
  alignment?.toX,
  length?.toX,
  yearStyle?.toX,
);

. This goes to the diplomat auto-generated wrapper of the C API of ICU4X in package:icu4x (ref)

factory DateFormatter.ymd(Locale locale, {DateTimeLength? length, DateTimeAlignment? alignment, YearStyle? yearStyle}) {
  final result = _icu4x_DateFormatter_create_ymd_mv1(locale._ffi, length != null ? _ResultInt32Void.ok(length.index) : _ResultInt32Void.err(), alignment != null ? _ResultInt32Void.ok(alignment.index) : _ResultInt32Void.err(), yearStyle != null ? _ResultInt32Void.ok(yearStyle.index) : _ResultInt32Void.err());
  if (!result.isOk) {
    throw DateTimeFormatterLoadError.values.firstWhere((v) => v._ffi == result.union.err);
  }
  return DateFormatter._fromFfi(result.union.ok, []);
}

which directs to the autogenerated external method references linking directly to a Rust function (ref). This uses two special features from Dart, @Native and @RecordUse.

• @Native relates the method to the symbol in a dynamic library via the build hooks. In this case, the function corresponds to a symbol called icu4x_DateFormatter_create_ymd_mv1 in a dynamic library attached in the build hook to the code.
• @RecordUse means that creations of this instance are tracked and can be retrieved during the link hook phase, which runs after kernel compilation. So we can retrieve a list of symbols used from the library and treeshake out all the unused symbols, bringing down the binary size from ~37MB to ~1.6MB, depending on the symbols used. The treeshaking works by compiling the Rust library to a static library in the build hook, and then running the link hook with a bunch of flags and the list of recorded symbols to obtain a small dynamic library ready to be shipped with the compiled Dart code.

@meta.RecordUse()
class _DiplomatFfiUse {
  final String symbol;

  // ignore: experimental_member_use
  const _DiplomatFfiUse(@meta.mustBeConst this.symbol);
}

...

@_DiplomatFfiUse('icu4x_DateFormatter_create_ymd_mv1')
@ffi.Native<_ResultOpaqueInt32 Function(ffi.Pointer<ffi.Opaque>, _ResultInt32Void, _ResultInt32Void, _ResultInt32Void)>(isLeaf: true, symbol: 'icu4x_DateFormatter_create_ymd_mv1')
// ignore: non_constant_identifier_names
external _ResultOpaqueInt32 _icu4x_DateFormatter_create_ymd_mv1(ffi.Pointer<ffi.Opaque> locale, _ResultInt32Void length, _ResultInt32Void alignment, _ResultInt32Void yearStyle);

. The corresponding Rust code is then (ref)

        #[cfg(feature = "compiled_data")]
        pub fn create_ymd(
            locale: &Locale,
            length: Option<DateTimeLength>,
            alignment: Option<DateTimeAlignment>,
            year_style: Option<YearStyle>,
        ) -> Result<Box<Self>, DateTimeFormatterLoadError> {
            let prefs = (&locale.0).into();
            let mut options = icu_datetime::fieldsets::YMD::for_length(map_or_default(length));
            options.alignment = alignment.map(Into::into);
            options.year_style = year_style.map(Into::into);
            Ok(Box::new(Self(
                icu_datetime
                    ::DateTimeFormatter
                    ::try_new(
                        prefs,
                        options
                    )?
                .cast_into_fset(),
            )))
        }

Size comparisons

We are comparing two very simple programs. This is in no way representative of a real app - the intl and intl4x packages are hard to compare due to different feature sets.

package:intl:

import 'package:intl/date_symbol_data_local.dart' show initializeDateFormatting;
import 'package:intl/intl.dart' show DateFormat;

Future<void> main() async {
  await initializeDateFormatting();
  final date = DateTime(2021, 12, 17, 4, 0, 42);
  print(DateFormat.yMd('de').format(date));
}

package:intl4x:

import 'package:intl4x/datetime_format.dart';

void main() {
  final date = DateTime(2021, 12, 17, 4, 0, 42);
  print(DateTimeFormat.yearMonthDay(locale: Locale.parse('de')).format(date));
}

Web

package:intl results in

mosum@mosum2:~/projects/i18n/pkgs/intl/example$ dart compile js -O4 ./bin/example.dart
Compiled 11,431,509 input bytes (6,440,796 characters source) to 257,450 characters JavaScript in 0.63 seconds
mosum@mosum2:~/projects/i18n/pkgs/intl/example$ dart run ./bin/example.dart
17.12.2021

while package:intl4x only shows

mosum@mosum2:~/projects/i18n/pkgs/intl4x/example$ dart compile js -O4 example.dart 
Compiled 10,491,216 input bytes (5,490,729 characters source) to 64,522 characters JavaScript in 0.50 seconds
mosum@mosum2:~/projects/i18n/pkgs/intl4x/example$ dart run example.dart 
Running build hooks... 
17.12.21

which is only ¼ of the size.

Native

Here it is slightly different, for package:intl we get

mosum@mosum2:~/projects/i18n/pkgs/intl/example$ dart build cli --target ./bin/example.dart
The `dart build cli` command is in preview at the moment.
See documentation on https://dart.dev/interop/c-interop#native-assets.

Deleting output directory: /home/mosum/projects/i18n/pkgs/intl/example/build/cli/linux_x64/.
Generated: /home/mosum/projects/i18n/pkgs/intl/example/build/cli/linux_x64/bundle/bin/example
mosum@mosum2:~/projects/i18n/pkgs/intl/example$  tree --du -h build/
[6.6M]  build/
└── [6.6M]  cli
    └── [6.6M]  linux_x64
        └── [6.6M]  bundle
            └── [6.6M]  bin
                └── [6.6M]  example

 6.6M used in 5 directories, 1 file

while package:intl4x results in

mosum@mosum2:~/projects/i18n/pkgs/intl4x/example$ dart --enable-experiment=record-use build cli --target ./example.dart 
The `dart build cli` command is in preview at the moment.
See documentation on https://dart.dev/interop/c-interop#native-assets.

Deleting output directory: /home/mosum/projects/i18n/pkgs/intl4x/example/build/cli/linux_x64/.
Running build hooks... 
Running link hooks... 
Copying 1 build assets:
package:icu4x/src/bindings/lib.g.dart
Generated: /home/mosum/projects/i18n/pkgs/intl4x/example/build/cli/linux_x64/bundle/bin/example
mosum@mosum2:~/projects/i18n/pkgs/intl4x/example$ tree --du -h build/
[7.9M]  build/
└── [7.9M]  cli
    └── [7.9M]  linux_x64
        └── [7.9M]  bundle
            ├── [6.3M]  bin
            │   └── [6.3M]  example
            └── [1.5M]  lib
                └── [1.5M]  libicu4x.so

 7.9M used in 6 directories, 2 files

which is slightly larger, due to the overhead of the ICU4X library from its larger feature set.