Struct I18n 

pub struct I18n { /* private fields */ }

Available on crate feature i18n only.

The main handle for accessing and managing internationalization state.

I18n holds the selected language, fallback language, locale resources, and the active Fluent bundle used for translating messages. It is Clone + Copy so it can be freely passed around in components.

There are several ways to obtain an I18n instance:

• use_init_i18n to create and provide it to descendant components.
• I18n::create to manually create one from an I18nConfig (useful when you need to handle errors).
• I18n::create_global to create one with global lifetime, suitable for multi-window apps.
• I18n::get or I18n::try_get to retrieve an already-provided instance from the component context.
• use_share_i18n to re-provide an existing instance to a different part of the component tree.

Implementations

impl I18n

pub fn try_get() -> Option<I18n>

Try to retrieve the I18n instance from the component context.

Returns None if no I18n has been provided via use_init_i18n or use_share_i18n in an ancestor component.

pub fn get() -> I18n

Retrieve the I18n instance from the component context.

This is the primary way to access the i18n state from within a component that is a descendant of a component that called use_init_i18n or use_share_i18n.

Panics

Panics if no I18n has been provided in an ancestor component.

#[derive(PartialEq)]
struct MyComponent;

impl Component for MyComponent {
    fn render(&self) -> impl IntoElement {
        let mut i18n = I18n::get();

        let change_to_english = move |_| i18n.set_language(langid!("en-US"));

        rect()
            .child(t!("hello_world"))
            .child(Button::new().on_press(change_to_english).child("English"))
    }
}

pub fn create(_: I18nConfig) -> Result<I18n, Error>

Manually create an I18n instance from an I18nConfig.

Unlike use_init_i18n, this does not automatically provide the instance to descendant components. Use use_share_i18n to share it afterwards, or call this when you need explicit error handling during initialization.

The created state is scoped to the current component. For global state that outlives any single component, see I18n::create_global.

pub fn create_global(_: I18nConfig) -> Result<I18n, Error>

Create an I18n instance with global lifetime.

Unlike I18n::create, the state created here is not scoped to any component and will live for the entire duration of the application. This is useful for multi-window apps where i18n state needs to be created in main and then shared across different windows via use_share_i18n.

This is not a hook, do not use it inside components like you would use_init_i18n. You would usually want to call this in your main function.

struct MyApp {
    i18n: I18n,
}

impl App for MyApp {
    fn render(&self) -> impl IntoElement {
        // Re-provide the global I18n to this window's component tree
        use_share_i18n(move || self.i18n);

        rect().child(t!("hello_world"))
    }
}

fn main() {
    // Create I18n with global lifetime in main, before any window is opened
    let i18n = I18n::create_global(I18nConfig::new(langid!("en-US")).with_locale((
        langid!("en-US"),
        include_str!("../../../examples/i18n/en-US.ftl"),
    )))
    .expect("Failed to create I18n");

    // Pass it to each window's app struct
    launch(LaunchConfig::new().with_window(WindowConfig::new_app(MyApp { i18n })))
}

pub fn try_translate_with_args( &self, msg: &str, args: Option<&FluentArgs<'_>>, ) -> Result<String, Error>

Translate a message by its identifier, optionally with Fluent arguments.

The msg can be a simple message id (e.g. "hello") or a dotted attribute id (e.g. "my_component.placeholder"). See I18n::decompose_identifier for details.

Returns an error if the message id is not found, the pattern is missing, or Fluent reports errors during formatting.

Prefer the t!, te!, or tid! macros for ergonomic translations.

pub fn decompose_identifier(msg: &str) -> Result<(&str, Option<&str>), Error>

Split a message identifier into its message id and optional attribute name.

• "hello" returns ("hello", None)
• "my_component.placeholder" returns ("my_component", Some("placeholder"))

Returns an error if the identifier contains more than one dot.

pub fn translate_with_args( &self, msg: &str, args: Option<&FluentArgs<'_>>, ) -> String

Translate a message by its identifier, optionally with Fluent arguments.

This is the panicking version of I18n::try_translate_with_args.

Panics

Panics if the translation fails for any reason.

pub fn try_translate(&self, msg: &str) -> Result<String, Error>

Translate a message by its identifier, without arguments.

Shorthand for self.try_translate_with_args(msg, None).

pub fn translate(&self, msg: &str) -> String

Translate a message by its identifier, without arguments.

This is the panicking version of I18n::try_translate.

Panics

Panics if the translation fails for any reason.

pub fn language(&self) -> LanguageIdentifier

Get the selected language.

pub fn fallback_language(&self) -> Option<LanguageIdentifier>

Get the fallback language.

pub fn try_set_language(&mut self, id: LanguageIdentifier) -> Result<(), Error>

Update the selected language, rebuilding the active Fluent bundle.

Returns an error if the bundle cannot be rebuilt for the new language.

pub fn set_language(&mut self, id: LanguageIdentifier)

Update the selected language, rebuilding the active Fluent bundle.

This is the panicking version of I18n::try_set_language.

Panics

Panics if the bundle cannot be rebuilt for the new language.

pub fn try_set_fallback_language( &mut self, id: LanguageIdentifier, ) -> Result<(), Error>

Update the fallback language, rebuilding the active Fluent bundle.

The given language must have a corresponding Locale registered in the config. Returns an error if no locale exists for the language or if the bundle cannot be rebuilt.

pub fn set_fallback_language(&mut self, id: LanguageIdentifier)

Update the fallback language, rebuilding the active Fluent bundle.

This is the panicking version of I18n::try_set_fallback_language.

Panics

Panics if no locale exists for the language or if the bundle cannot be rebuilt.

Trait Implementations

impl Clone for I18n

fn clone(&self) -> I18n

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for I18n