Crate fluent_zero 

fluent-zero

A zero-allocation, high-performance Fluent localization loader designed for GUIs and games.

This crate works in tandem with the fluent-zero-build crate. The build script generates static Perfect Hash Maps (PHF) that allow O(1) lookups for localized strings. When a string is static (contains no variables), it returns a &'static str reference to the binary’s read-only data, avoiding all heap allocations.

The public API is t!, t_in!, set_lang, get_lang, LocaleState, Catalog, CacheEntry, DEFAULT_FALLBACK, join_charsets, the runtime diagnostics (set_error_handler, clear_error_handler, LookupError, FormatErrors, ErrorHandler) and the re-exported LanguageIdentifier and FluentArgs. Everything under __private exists only for the code fluent-zero-build generates and the macros; it is not covered by semver and may change in any release.

Example

// Brings the generated `CATALOG`, `keys` and key list into scope.
// (Replaced by hand-written stand-ins in this example.)
include!(concat!(env!("OUT_DIR"), "/static_cache.rs"));

use fluent_zero::{set_lang, t};

fn main() {
    // Static message: a borrowed `&'static str`, no allocation.
    assert_eq!(t!("app-title"), "My App");

    // Dynamic message: formatted by the Fluent bundle.
    let welcome = t!("welcome-user", { "name" => "Alice", "unread_count" => 5 });
    assert_eq!(welcome, "Welcome, Alice! (5 unread)");

    // Switching language is global and takes effect immediately.
    set_lang("fr-FR".parse().unwrap());
    assert_eq!(t!("app-title"), "Mon appli");
    assert_eq!(fluent_zero::get_lang().key(), "fr-FR");

    // Messages missing from fr-FR fall back to en-US.
    let welcome = t!("welcome-user", { "name" => "Bob", "unread_count" => 0 });
    assert_eq!(welcome, "Welcome, Bob! (0 unread)");
}

Macros

t

The primary accessor macro for localized strings.

t_in

Like t!, but for an explicit LocaleState instead of the global language.

Structs

Catalog

A crate’s generated lookup tables, as used by t! and t_in!.

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.

FormatErrors

The errors fluent-bundle reported while formatting one message, as carried by LookupError::Format.

LanguageIdentifier

LanguageIdentifier is a core struct representing a Unicode Language Identifier.

LocaleState

A language and the locale keys a lookup tries for it.

Enums

CacheEntry

Represents the result of a cache lookup from the generated PHF map.

LookupError

A localization problem observed at runtime.

Constants

DEFAULT_FALLBACK

The fallback locale of catalogs that do not configure one.

Functions

clear_error_handler

Removes the handler installed with set_error_handler.

get_lang

Retrieves the current language state.

join_charsets

Merges multiple charset strings into a single, deduplicated, and sorted string.

set_error_handler

Installs a process-wide handler that is called for every LookupError.

set_lang

Updates the runtime language for the application.

Type Aliases

ErrorHandler

Signature of a handler installed with set_error_handler.