# ICU timezone data

This document describes Fuchsia's support for loading ICU timezone data from
ICU data files (`icudtl.dat`). Programs load timezone data dynamically based on
the resources most appropriate for their application.

For more details on the general use of ICU APIs in Fuchsia, see
[International Components for Unicode use in Fuchsia](icu.md)


## Make the ICU data available

In order for the system default ICU data files to be visible to a program in
Fuchsia, you must include the resource dependency in your package:

```gn
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/BUILD.gn" region_tag="icudata_resource" adjust_indentation="auto" %}
```

### Timezone configuration data

To provide a specific version of the timezone data files to your component,
request the appropriate [directory capability][directory-capability]
in your component manifest:

```json5
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/meta/tz_version_parrot.cml" region_tag="tzdata-capability" adjust_indentation="auto" %}
```

## Load the ICU data

You *must* load the ICU data in your program to make the locale data available.
Otherwise, no locale data will be available and your ICU code will behave as if
the set of i18n data is empty.

1.  Include the ICU data library dependency in your `BUILD.gn` file:

    * {C++}

      ```gn
      {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/BUILD.gn" region_tag="icudata_library" adjust_indentation="auto" %}
      ```

      Note: You can find the C++ library source at
      [`//src/lib/icu_data/cpp`](/src/lib/icu_data/cpp)

    * {Rust}

      ```gn
      {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/BUILD.gn" region_tag="icudata_library" adjust_indentation="auto" %}
      ```

      Note: You can find the Rust library source at
      [`//src/lib/icu_data/rust`](/src/lib/icu_data/rust)

1.  Import the ICU data library into your source files:

    * {C++}

      ```cpp
      {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/test.cc" region_tag="imports" adjust_indentation="auto" %}
      ```

    * {Rust}

      ```rust
      {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/src/lib.rs" region_tag="imports" adjust_indentation="auto" %}
      ```

1.  Initialize the ICU data loader:

    * {C++}

      ```cpp
      {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/test.cc" region_tag="loader_example" adjust_indentation="auto" %}
      ```

    * {Rust}

      ```rust
      {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/src/lib.rs" region_tag="loader_example" adjust_indentation="auto" %}
      ```

      Note: At least one instance of `icu_data::Loader` must be kept alive for
      as long as your code needs ICU data. To simplify things, consider keeping
      a reference to the instance for the lifetime of the program.

You are now ready to use ICU data in your program.

### Load from tzdata directory

To load the ICU data, initialize the loader with the path to the data directory
and revision file:

* {C++}

  ```cpp
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/test.cc" region_tag="loader_config_example" adjust_indentation="auto" %}
  ```

* {Rust}

  ```rust
  {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/src/lib.rs" region_tag="loader_config_example" adjust_indentation="auto" %}
  ```

## Appendices

### Modifying the system time zone information

During development, use the `ffx setui` plugin to check or set the current
time zone ID on a Fuchsia target. For more information about the available
options, run the following commands:

```posix-terminal
ffx config set setui true // only need to run once
ffx setui intl --help
```

<!-- xrefs -->
[product-config]: /docs/development/components/configuration/config_data.md
[directory-capability]: /docs/concepts/components/v2/capabilities/directory.md