Add LocaleFallbackProvider to tutorial examples (#3334)

docs/tutorials/data_management.md

@@ -46,6 +46,10 @@ You should generate it automatically at build time if:
 
 If you check in the generated data, it is recommended that you configure a job in continuous integration that verifies that the data in your repository reflects the latest CLDR/Unicode releases; otherwise, your app may drift out of date.
 
+## Locale Fallbacking
+
+Data generated with `--format blob` or `--format fs` supports only exact matches for locales, not locales requiring _fallback_. For example, if `en-US` is requested but only `en` data is available, then the data request will fail. Because of this, it is often desirable to configure a `LocaleFallbackProvider`, as illustrated in the remainder of the examples on this page.
+
 # 3. Using the generated data
 
 Once we have generated some data, it needs to be loaded as a data provider. The blob format we chose can be loaded by `BlobDataProvider` from the `icu_provider_blob` crate.
@@ -65,6 +69,7 @@ We can then use the provider in our code:
 use icu::locid::{locale, Locale};
 use icu::calendar::DateTime;
 use icu::datetime::{DateTimeFormatter, options::length};
+use icu_provider_adapters::fallback::LocaleFallbackProvider;
 use icu_provider_blob::BlobDataProvider;
 
 const LOCALE: Locale = locale!("ja");
@@ -75,6 +80,11 @@ fn main() {
         BlobDataProvider::try_new_from_blob(blob.into_boxed_slice())
             .expect("Failed to initialize Data Provider.");
 
+    // Wrapping the raw BlobDataProvider in a LocaleFallbackProvider enables
+    // locales to fall back to other locales, like "en-US" to "en".
+    let buffer_provider = LocaleFallbackProvider::try_new_with_buffer_provider(buffer_provider)
+        .expect("Provider should contain fallback rules");
+
     let options = length::Bag::from_date_time_style(length::Date::Long, length::Time::Medium);
 
     let dtf = DateTimeFormatter::try_new_with_buffer_provider(&buffer_provider, &LOCALE.into(), options.into())
@@ -109,6 +119,7 @@ We can instead use `TypedDateTimeFormatter<Gregorian>`, which only supports form
 use icu::locid::{locale, Locale};
 use icu::calendar::{DateTime, Gregorian};
 use icu::datetime::{TypedDateTimeFormatter, options::length};
+use icu_provider_adapters::fallback::LocaleFallbackProvider;
 use icu_provider_blob::BlobDataProvider;
 
 const LOCALE: Locale = locale!("ja");
@@ -119,6 +130,11 @@ fn main() {
         BlobDataProvider::try_new_from_blob(blob.into_boxed_slice())
             .expect("Failed to initialize Data Provider.");
 
+    // Wrapping the raw BlobDataProvider in a LocaleFallbackProvider enables
+    // locales to fall back to other locales, like "en-US" to "en".
+    let buffer_provider = LocaleFallbackProvider::try_new_with_buffer_provider(buffer_provider)
+        .expect("Provider should contain fallback rules");
+
     let options = length::Bag::from_date_time_style(length::Date::Long, length::Time::Medium);
 
     let dtf = TypedDateTimeFormatter::<Gregorian>::try_new_with_buffer_provider(&buffer_provider, &LOCALE.into(), options.into())
@@ -168,6 +184,7 @@ extern crate alloc; // required as my-data-mod is written for #[no_std]
 use icu::locid::{locale, Locale};
 use icu::calendar::DateTime;
 use icu::datetime::{TypedDateTimeFormatter, options::length};
+use icu_provider_adapters::fallback::LocaleFallbackProvider;
 
 const LOCALE: Locale = locale!("ja");
 
@@ -178,6 +195,11 @@ impl_data_provider!(UnstableProvider);
 fn main() {
     let unstable_provider = UnstableProvider;
 
+    // Wrapping the raw UnstableProvider in a LocaleFallbackProvider enables
+    // locales to fall back to other locales, like "en-US" to "en".
+    let unstable_provider = LocaleFallbackProvider::try_new_unstable(unstable_provider)
+        .expect("Provider should contain fallback rules");
+
     let options = length::Bag::from_date_time_style(length::Date::Long, length::Time::Medium);
 
     let dtf = TypedDateTimeFormatter::try_new_unstable(&unstable_provider, &LOCALE.into(), options.into())
@@ -224,6 +246,7 @@ $ cargo add icu_provider_fs
 use icu::locid::{locale, Locale};
 use icu::calendar::DateTime;
 use icu::datetime::{TypedDateTimeFormatter, options::length};
+use icu_provider_adapters::fallback::LocaleFallbackProvider;
 use icu_provider_fs::FsDataProvider;
 
 const LOCALE: Locale = locale!("ja");
@@ -232,6 +255,11 @@ fn main() {
     let buffer_provider = FsDataProvider::try_new("my-data-dir")
            .expect("Failed to initialize Data Provider");
 
+    // Wrapping the raw BlobDataProvider in a LocaleFallbackProvider enables
+    // locales to fall back to other locales, like "en-US" to "en".
+    let buffer_provider = LocaleFallbackProvider::try_new_with_buffer_provider(buffer_provider)
+        .expect("Provider should contain fallback rules");
+
     let options = length::Bag::from_date_time_style(length::Date::Long, length::Time::Medium);
 
     let dtf = TypedDateTimeFormatter::try_new_with_buffer_provider(&buffer_provider, &LOCALE.into(), options.into())

docs/tutorials/testing/Cargo.toml

@@ -14,7 +14,7 @@ displaydoc = "0.2.3"
 icu = "1.2"
 icu_datagen = { version = "1.2", default-features = false}
 icu_provider = { version = "1.2", features = ["deserialize_json"] }
-icu_provider_adapters = "1.2"
+icu_provider_adapters = { version = "1.2", features = ["serde"] }
 icu_provider_blob = "1.2"
 icu_provider_fs = "1.2"
 icu_testdata = "1.2"