Crate fluent

Fluent is a modern localization system designed to improve how software is translated.

The Rust implementation provides the low level components for syntax operations, like parser and AST, and the core localization struct - FluentBundle.

FluentBundle is the low level container for storing and formatting localization messages in a single locale.

This crate provides also a number of structures needed for a localization API such as FluentResource, FluentMessage, FluentArgs, and FluentValue.

Together, they allow implementations to build higher-level APIs that use FluentBundle and add user friendly helpers, framework bindings, error fallbacking, language negotiation between user requested languages and available resources, and I/O for loading selected resources.

Example

use fluent::{FluentBundle, FluentValue, FluentResource, FluentArgs};

// Used to provide a locale for the bundle.
use unic_langid::LanguageIdentifier;

let ftl_string = String::from("
hello-world = Hello, world!
intro = Welcome, { $name }.
");
let res = FluentResource::try_new(ftl_string)
    .expect("Failed to parse an FTL string.");

let langid_en: LanguageIdentifier = "en-US".parse().expect("Parsing failed");
let mut bundle = FluentBundle::new(vec![langid_en]);

bundle
    .add_resource(res)
    .expect("Failed to add FTL resources to the bundle.");

let msg = bundle.get_message("hello-world")
    .expect("Message doesn't exist.");
let mut errors = vec![];
let pattern = msg.value()
    .expect("Message has no value.");
let value = bundle.format_pattern(&pattern, None, &mut errors);

assert_eq!(&value, "Hello, world!");

let mut args = FluentArgs::new();
args.set("name", FluentValue::from("John"));

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);

// The FSI/PDI isolation marks ensure that the direction of
// the text from the variable is not affected by the translation.
assert_eq!(value, "Welcome, \u{2068}John\u{2069}.");

Ergonomics & Higher Level APIs

Reading the example, you may notice how verbose it feels. Many core methods are fallible, others accumulate errors, and there are intermediate structures used in operations.

This is intentional as it serves as building blocks for variety of different scenarios allowing implementations to handle errors, cache and optimize results.

At the moment it is expected that users will use the fluent-bundle crate directly, while the ecosystem matures and higher level APIs are being developed.

Modules

builtins

bundle

FluentBundle is a collection of localization messages in Fluent.

concurrent

types

types module contains types necessary for Fluent runtime value handling. The core struct is FluentValue which is a type that can be passed to the FluentBundle::format_pattern as an argument, it can be passed to any Fluent Function, and any function may return it.

Macros

fluent_args

A helper macro to simplify creation of FluentArgs.

Structs

FluentArgs

Fluent messages can use arguments in order to programmatically add values to a translated string. For instance, in a localized application you may wish to display a user’s email count. This could be done with the following message.

FluentAttribute

FluentAttribute is a component of a compound FluentMessage.

FluentMessage

FluentMessage is a basic translation unit of the Fluent system.

FluentResource

A resource containing a list of localization messages.

Enums

FluentError

Core error type for Fluent runtime system.

FluentValue

The FluentValue enum represents values which can be formatted to a String.

Type Aliases

FluentBundle

Specialized FluentBundle over non-concurrent IntlLangMemoizer.