icu_provider is one of the [ICU4X] components.
Unicode's experience with ICU4X's parent projects, ICU4C and ICU4J, led the team to realize that data management is the most critical aspect of deploying internationalization, and that it requires a high level of customization for the needs of the platform it is embedded in. As a result ICU4X comes with a selection of providers that should allow for ICU4X to naturally fit into different business and technological needs of customers.
icu_provider defines traits and structs for transmitting data through the ICU4X locale
data pipeline. The primary trait is [DataProvider]. It is parameterized by a
[KeyedDataMarker], which contains the data type and a [DataKey]. It has one method,
[DataProvider::load], which transforms a [DataRequest]
into a [DataResponse].
DataKey] is a fixed identifier for the data type, such as "plurals/cardinal@1".DataRequest] contains additional annotations to choose a specific variant of the key,
such as a locale.DataResponse] contains the data if the request was successful.In addition, there are three other traits which are widely implemented:
AnyProvider] returns data as dyn Any trait objects.BufferProvider] returns data as [u8] buffers.DynamicDataProvider] returns structured data but is not specific to a key.The most common types required for this crate are included via the prelude:
rust
use icu_provider::prelude::*;
All nontrivial data providers can fit into one of two classes.
AnyProvider]: Those whose data originates as structured Rust objectsBufferProvider]: Those whose data originates as unstructured [u8] buffers✨ Key Insight: A given data provider is generally either an [AnyProvider] or a
[BufferProvider]. Which type depends on the data source, and it is not generally possible
to convert one to the other.
See also [crate::constructors].
These providers are able to return structured data cast into dyn Any trait objects. Users
can call [as_downcasting()] to get an object implementing [DataProvider] by downcasting
the trait objects.
Examples of AnyProviders:
CldrJsonDataProvider] reads structured data from CLDR JSON source files and returns
structured Rust objects.AnyPayloadProvider] wraps a specific data struct and returns it.BakedDataProvider which encodes structured data directly in Rust sourceThese providers are able to return unstructured data typically represented as
[serde]-serialized buffers. Users can call [as_deserializing()] to get an object
implementing [DataProvider] by invoking Serde Deserialize.
Examples of BufferProviders:
FsDataProvider] reads individual buffers from the filesystem.BlobDataProvider] reads buffers from a large in-memory blob.ICU4X offers several built-in modules to combine providers in interesting ways.
These can be found in the [icu_provider_adapters] crate.
This crate also contains a concrete provider for testing purposes:
HelloWorldProvider] returns "hello world" strings in several languages.If you need a testing provider that contains the actual resource keys used by ICU4X features,
see the [icu_testdata] crate.
Types compatible with [Yokeable] can be passed through the data provider, so long as they are
associated with a marker type implementing [DataMarker].
Data structs should generally have one lifetime argument: 'data. This lifetime allows data
structs to borrow zero-copy data.
This functionality is enabled with the "datagen" feature
The [datagen] module contains several APIs for data generation. See [icu_datagen] for the reference
data generation implementation.
For more information on development, authorship, contributing etc. please visit ICU4X home page.