# ICU4X for Dart

[ICU4X](https://icu4x.unicode.org) provides components enabling wide range of software internationalization.
It draws deeply from the experience of [ICU4C/J](https://github.com/unicode-org/icu), [ECMA-402](https://github.com/tc39/ecma402/) and relies on data from the [CLDR](https://cldr.unicode.org/) project.

ICU4X's functionality is completely available from Dart via `dart:ffi`, with bindings generated by [Diplomat].

_We are still working on improving the user experience of using ICU4X from other languages. As such, this tutorial may be a bit sparse, but we are happy to answer questions on our [discussions forum] and help you out_

## Using ICU4X

ICU4X can be used like any other `pub.dev` package:

```shell
dart pub add icu4x:2.0.0-dev.0
```

`main.dart`:

```dart
import 'package:icu4x/icu4x.dart'
    show DateFormatter, DateTimeLength, IsoDate, Locale;

void main(List<String> arguments) {
  final locale = Locale.fromString('de-CH');

  final date = IsoDate(2025, 1, 2);

  final formatter = DateFormatter.ymde(locale, length: DateTimeLength.Medium);

  print(formatter.formatIso(date));
}
```

```shell
dart run
# Do., 02.01.2025
```

[discussions forum]: https://github.com/unicode-org/icu4x/discussions
[Diplomat]: https://github.com/rust-diplomat/diplomat

## Optimizing binary size

By default, this package will fetch a platform specific static or dynamic library from the [ICU4X GitHub releases](https://github.com/unicode-org/icu4x/releases) and link it using `package:hooks`. On supported platforms (currently Linux, `dev` Dart with `--enable-experiment=record-use`), `package:hooks` performs tree-shaking, meaning only APIs that are used by the final binary are included. On other platforms, the whole ICU4X dynamic library is included, which can add about 15MB to the resulting binary size. This can, however, be customized by building a tailored ICU4X dylib manually and adding the following to your `pubspec.yaml`:

```yaml
hooks:
  user_defines:
    icu4x:
      buildMode: local
      localPath: path/to/dylib.so
```

## Licensing and Copyright

Copyright © 2020-2024 Unicode, Inc. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other countries.

The project is released under [LICENSE](./LICENSE), the free and open-source [Unicode License](https://www.unicode.org/license.txt), which is based on the well-known MIT license, with the primary difference being that the Unicode License expressly covers data and data files, as well as code. For further information please see [The Unicode Consortium Intellectual Property, Licensing, and Technical Contribution Policies](https://www.unicode.org/policies/licensing_policy.html).
