[−][src]Type Definition fluent_bundle::FluentBundle
type FluentBundle<R> = FluentBundleBase<R, IntlLangMemoizer>;
A collection of localization messages for a single locale, which are meant to be used together in a single view, widget or any other UI abstraction.
Examples
use fluent_bundle::{FluentBundle, FluentResource, FluentValue, FluentArgs}; use unic_langid::langid; let ftl_string = String::from("intro = Welcome, { $name }."); let resource = FluentResource::try_new(ftl_string) .expect("Could not parse an FTL string."); let langid_en = langid!("en-US"); let mut bundle = FluentBundle::new(&[langid_en]); bundle.add_resource(&resource) .expect("Failed to add FTL resources to the bundle."); let mut args = FluentArgs::new(); args.add("name", FluentValue::from("Rustacean")); let msg = bundle.get_message("intro").expect("Message doesn't exist."); let mut errors = vec![]; let pattern = msg.value.expect("Message has no value."); let value = bundle.format_pattern(&pattern, Some(&args), &mut errors); assert_eq!(&value, "Welcome, \u{2068}Rustacean\u{2069}.");
FluentBundle
Life Cycle
Create a bundle
To create a bundle, call FluentBundle::new
with a locale list that represents the best
possible fallback chain for a given locale. The simplest case is a one-locale list.
Fluent uses LanguageIdentifier
which can be created using langid!
macro.
Add Resources
Next, call add_resource
one or more times, supplying translations in the FTL syntax.
Since FluentBundle
is generic over anything that can borrow a FluentResource
,
one can use FluentBundle
to own its resources, store references to them,
or even Rc<FluentResource>
or Arc<FluentResource>
.
The FluentBundle
instance is now ready to be used for localization.
Format
To format a translation, call get_message
to retrieve a FluentMessage
,
and then call format_pattern
on the message value or attribute in order to
retrieve the translated string.
The result of format_pattern
is an Cow<str>
. It is
recommended to treat the result as opaque from the perspective of the program and use it only
to display localized messages. Do not examine it or alter in any way before displaying. This
is a general good practice as far as all internationalization operations are concerned.
If errors were encountered during formatting, they will be
accumulated in the Vec<FluentError>
passed as the third argument.
While they are not fatal, they usually indicate problems with the translation, and should be logged or reported in a way that allows the developer to notice and fix them.
Locale Fallback Chain
FluentBundle
stores messages in a single locale, but keeps a locale fallback chain for the
purpose of language negotiation with i18n formatters. For instance, if date and time formatting
are not available in the first locale, FluentBundle
will use its locales
fallback chain
to negotiate a sensible fallback for date and time formatting.
Concurrency
As you may have noticed, FluentBundle
is a specialization of [FluentBundleBase
]
which works with an IntlMemoizer
over RefCell
.
In scenarios where the memoizer must work concurrently, there's an implementation of
IntlMemoizer
that uses Mutex
and there's concurrent::FluentBundle
which works with that.