`leptos_fluent!`

Common configurations
Processing steps
Parameters

Common configurations

CSR | Local storage from navigator

leptos_fluent! {
    locales: "./locales",

    set_language_to_local_storage: true,
    initial_language_from_local_storage: true,
    initial_language_from_navigator: true,
    initial_language_from_navigator_to_local_storage: true,
    initial_language_from_url_param: true,
    initial_language_from_url_param_to_local_storage: true,
    local_storage_key: "lang",
}

leptos_fluent! {
    locales: "./locales",

    set_language_to_cookie: true,
    initial_language_from_cookie: true,
    initial_language_from_navigator: true,
    initial_language_from_navigator_to_cookie: true,
    initial_language_from_url_param: true,
    initial_language_from_url_param_to_cookie: true,
    initial_language_from_accept_language_header: true,
    cookie_name: "lf-lang",
}

system | Data files on Desktop applications

leptos_fluent! {
    locales: "./locales",

    initial_language_from_system: true,
    initial_language_from_system_to_data_file: true,
    initial_language_from_data_file: true,
    set_language_to_data_file: true,
    data_file_key: "system-language-example",
}

Processing steps

There is four kind of parameters for all the possible configurations and are executed in the next order:

Order

Get the initial languaje from a source or target: initial_language_from_*
Obtain the initial language and set to a target: initial_language_from_*_to_*
Synchronize the current language with a target: set_language_to_*

The name of a source or a target: cookie_name, local_storage_key, navigator...

Sources and targets

Sources are read-only and targets are read-write.

Sources: navigator, system, accept_language_header
Targets: cookie_name, local_storage_key, url_param, data_file...

Commented example

Example

leptos_fluent! {
    // ..
    // Get the initial language from the source operative system
    initial_language_from_system: true,
    // and set to the target file.
    initial_language_from_system_to_data_file: true,
    // If a target data file exists, get the initial language from it.
    initial_language_from_data_file: true,
    // When the language is updated, set it to the file.
    set_language_to_data_file: true,
    // Unique file name to set the language for this app:
    data_file_key: "system-language-example",
};

Parameters

`translations`

Set the translations to be used in the application. It must be a reference to a static array of fluent_templates::static_loader! instances.

use fluent_templates::static_loader;
use leptos_fluent::leptos_fluent;

static_loader! {
    pub static TRANSLATIONS = {
        locales: "./locales",
        fallback_language: "en",
    };
}

leptos_fluent! {
    locales: "./locales",
    translations: [TRANSLATIONS],
    // ^^^^^^^^^^^^^^^^^^^^^^^^^
    fallback_language: "en",
}

Must be the same identifier used in the fluent_templates::static_loader! macro, which returns an std::sync::LazyLock variable.

This parameter is optional. If not provided, the macro will internally create a static loader.

`locales`

Set the path to the locales directory which contain the Fluent files for the translations. Must be relative to the Cargo.toml file, the same used in the fluent_templates::static_loader! macro.

leptos_fluent! {
    locales: "./locales",
    // ^^^^^^^^^^^^^^^^^
}

`children`

Set the children components of the root component. It is used to pass the children to the I18n component.

use leptos::prelude::*;

#[component]
fn I18n(children: Children) -> impl IntoView {
    leptos_fluent! {
        children: children(),
        locales: "./locales",
        // ...
    }
}

#[component]
fn App() -> impl IntoView {
    I18n! {
        // ... your components
    }
}

`default_language`

Initial language to load when the user does not load any with the provided configuration.

If not defined, the first language in by the alphabetical order of their language codes will be used as fallback.

static_loader! {
    pub static TRANSLATIONS = {
        locales: "./locales",
        fallback_language: "en",
    };
}

leptos_fluent! {
    locales: "./locales",
    translations: [TRANSLATIONS],
    default_language: "en",
    // ^^^^^^^^^^^^^^^^^^^
}

Note that this is not the same as the fallback_language parameter of fluent_templates::static_loader!, which is used to provide a fallback language when a translation is not found in the current language.

`core_locales`

Common locale resources that are shared across all locales. Must be relative to the Cargo.toml file, the same used in the fluent_templates::static_loader! macro:

static_loader! {
    pub static TRANSLATIONS = {
        locales: "./locales",
        core_locales: "./locales/core",
        fallback_language: "en",
    };
}

leptos_fluent! {
    locales: "./locales",
    core_locales: "./locales/core",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    translations: [TRANSLATIONS],
}

`languages`

Path to a file containing the list of languages supported by the application. Must be relative to the Cargo.toml file.

Tip

In order to use this parameter a languages file feature must be enabled. See 4. Languages

leptos_fluent! {
    locales: "./locales",
    languages: "./locales/languages.json",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}

`check_translations`

Check the translations at compile time. It is useful to ensure that all translations are correct and that there are no missing translations.

Must be a glob relative to the Cargo.toml file or a literal boolean.

For single crate projects:

leptos_fluent! {
    locales: "./locales",
    check_translations: "./src/**/*.rs",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}

For workspace projects:

leptos_fluent! {
    locales: "./locales",
    check_translations: "../{app,components}/src/**/*.rs",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}

When the parameter is a literal boolean, the translations will be checked in all the Rust files of the workspace.

leptos_fluent! {
    locales: "./locales",
    check_translations: true,
    // ^^^^^^^^^^^^^^^^^^^^^
}

`fill_translations`

Add new messages found in tr! and move_tr! macros to translations files.

For single crate projects:

leptos_fluent! {
    locales: "./locales",
    fill_translations: "./src/**/*.rs",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}

For workspace projects:

leptos_fluent! {
    locales: "./locales",
    fill_translations: "../{app,components}/src/**/*.rs",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}

CSR | `sync_html_tag_lang`

Synchronize the global <html lang="..."> attribute with current language using Effect::new. Can be a literal boolean or an expression that will be evaluated at runtime.

leptos_fluent! {
    // ...
    sync_html_tag_lang: true,
}

CSR | `sync_html_tag_dir`

Synchronize the global <html dir="..."> attribute with current language using Effect::new.

Can be a literal boolean or an expression that will be evaluated at runtime.

leptos_fluent! {
    // ...
    sync_html_tag_dir: true,
}

For custom languages from a languages file, specify a third element in the inner array with the direction of the language, which can be "auto", "ltr", or "rtl". Discovered languages will be defined depending on the language.

Example

Arabic (ar): "rtl"
English (en): "ltr"
Japanese (ja): "auto"

CSR + SSR | `url_param:` "lang"

Name of URL parameter used to manage the current language.

leptos_fluent! {
    // ...
    url_param: "lang",
}

CSR + SSR | `initial_language_from_url_param`

Set initial language from URL parameter.

leptos_fluent! {
    // ...
    initial_language_from_url_param: true,
}

CSR | `initial_language_from_url_param_to_local_storage`

Get initial language from URL parameter and save it to local storage.

leptos_fluent! {
    // ...
    initial_language_from_url_param_to_local_storage: true,
}

CSR | `initial_language_from_url_param_to_session_storage`

Get initial language from URL parameter and save it to session storage.

leptos_fluent! {
    // ...
    initial_language_from_url_param_to_session_storage: true,
}

CSR | `initial_language_from_url_param_to_cookie`

Get initial language from URL parameter and save it to a cookie.

leptos_fluent! {
    // ...
    initial_language_from_url_param_to_cookie: true,
}

CSR | `set_language_to_url_param`

Synchronize current language with URL parameter.

leptos_fluent! {
    // ...
    set_language_to_url_param: true,
}

CSR + SSR | `url_path`

Language extractor from URL path. It must take the URI path as argument and return the possible language.

/// Get the language from the top directory in the URL path.
fn get_language_from_url_path(path: &str) -> &str {
    if let Some(language) = path.split('/').nth(1) {
        return language;
    }
    ""
}

leptos_fluent! {
    // ...
    url_path: get_language_from_url_path,
    initial_language_from_url_path: true,
}

CSR + SSR | `initial_language_from_url_path`

Set initial language from URL path.

leptos_fluent! {
    // ...
    initial_language_from_url_path: true,
}

CSR | `initial_language_from_url_path_to_cookie`

Set initial language from URL path to a cookie.

leptos_fluent! {
    // ...
    initial_language_from_url_path_to_cookie: true,
}

CSR | `initial_language_from_url_path_to_local_storage`

Set initial language from URL path to local storage.

leptos_fluent! {
    // ...
    initial_language_from_url_path_to_local_storage: true,
}

CSR | `initial_language_from_url_path_to_session_storage`

Set initial language from URL path to session storage.

leptos_fluent! {
    // ...
    initial_language_from_url_path_to_session_storage: true,
}

CSR | `local_storage_key:` "lang"

Local storage key to manage the current language.

leptos_fluent! {
    // ...
    local_storage_key: "lang",
}

CSR | `initial_language_from_local_storage`

Get initial language from local storage.

leptos_fluent! {
    // ...
    initial_language_from_local_storage: true,
}

CSR | `initial_language_from_local_storage_to_cookie`

Get initial language from local storage and save it to a cookie.

leptos_fluent! {
    // ...
    initial_language_from_local_storage_to_cookie: true,
}

CSR | `initial_language_from_local_storage_to_session_storage`

Get initial language from local storage and save it to session storage.

leptos_fluent! {
    // ...
    initial_language_from_local_storage_to_session_storage: true,
}

CSR | `set_language_to_local_storage`

Set the current language to local storage.

leptos_fluent! {
    // ...
    set_language_to_local_storage: true,
}

CSR | `session_storage_key:` "lang"

Session storage key to manage the current language.

leptos_fluent! {
    // ...
    session_storage_key: "lang",
}

CSR | `initial_language_from_session_storage`

Get initial language from session storage.

leptos_fluent! {
    // ...
    initial_language_from_session_storage: true,
}

CSR | `initial_language_from_session_storage_to_cookie`

Get initial language from session storage and save it to a cookie.

leptos_fluent! {
    // ...
    initial_language_from_session_storage_to_cookie: true,
}

CSR | `initial_language_from_session_storage_to_local_storage`

Get initial language from session storage and save it to local storage.

leptos_fluent! {
    // ...
    initial_language_from_session_storage_to_local_storage: true,
}

CSR | `set_language_to_session_storage`

Set the current language to session storage.

leptos_fluent! {
    // ...
    set_language_to_session_storage: true,
}

CSR | `initial_language_from_navigator`

Get the initial language from navigator.languages.

leptos_fluent! {
    // ...
    initial_language_from_navigator: true,
}

CSR | `initial_language_from_navigator_to_local_storage`

Get the initial language from navigator.languages and save it in local storage.

leptos_fluent! {
    // ...
    initial_language_from_navigator_to_local_storage: true,
}

CSR | `initial_language_from_navigator_to_session_storage`

Get the initial language from navigator.languages and save it in session storage.

leptos_fluent! {
    // ...
    initial_language_from_navigator_to_session_storage: true,
}

CSR | `initial_language_from_navigator_to_cookie`

Get the initial language from navigator.languages and save it in a cookie.

leptos_fluent! {
    // ...
    initial_language_from_navigator_to_cookie: true,
}

CSR | `set_language_from_navigator`

When the user changes the language in the browser settings, the language change will be reflected in the client.

leptos_fluent! {
    // ...
    set_language_from_navigator: true,
}

SSR | `initial_language_from_accept_language_header`

Get the initial language from the Accept-Language header.

leptos_fluent! {
    // ...
    initial_language_from_accept_language_header: true,
}

CSR + SSR | `cookie_name:` "lf-lang"

Name of the cookie that will be used to manage the current language. By default it is "lf-lang".

leptos_fluent! {
    // ...
    cookie_name: "lang",
}

CSR | `cookie_attrs:` ""

Cookie attributes to set on the language cookie.

leptos_fluent! {
    // ...
    cookie_attrs: "SameSite=Strict; Secure",
}

If value is an expression the cookie will not be validated at compile time:

let attrs = "SameSite=Strict; Secure; MyCustomCookie=value"
leptos_fluent! {
    // ...
    cookie_attrs: attrs,
}

CSR + SSR | `initial_language_from_cookie`

Get the initial language from the cookie.

leptos_fluent! {
    // ...
    initial_language_from_cookie: true,
}

CSR | `initial_language_from_cookie_to_local_storage`

Get the initial language from the cookie and save it in local storage.

leptos_fluent! {
    // ...
    initial_language_from_cookie_to_local_storage: true,
}

CSR | `initial_language_from_cookie_to_session_storage`

Get the initial language from the cookie and save it in session storage.

leptos_fluent! {
    // ...
    initial_language_from_cookie_to_session_storage: true,
}

CSR | `set_language_to_cookie`

Set the current language to the cookie.

leptos_fluent! {
    // ...
    set_language_to_cookie: true,
}

system | `initial_language_from_system`

Get the initial language from the system.

leptos_fluent! {
    // ...
    initial_language_from_system: true,
}

system | `initial_language_from_data_file`

Get the initial language from a data file.

leptos_fluent! {
    // ...
    initial_language_from_data_file: true,
}

system | `initial_language_from_system_to_data_file`

Get the initial language from the system and save it in a data file.

leptos_fluent! {
    // ...
    initial_language_from_system_to_data_file: true,
}

system | `set_language_to_data_file`

Set the current language to a data file.

leptos_fluent! {
    // ...
    set_language_to_data_file: true,
}

system | `data_file_key:` "leptos-fluent"

Key to manage the current language in the data file. It should be unique per application.

leptos_fluent! {
    // ...
    data_file_key: "my-app",
}

`provide_meta_context`

Provide the macro meta information at runtime as a context. Get it using I18n::meta:

use leptos::prelude::*;
use leptos_fluent::{I18n, leptos_fluent};

leptos_fluent! {
    // ...
    provide_meta_context: true,
}

let i18n = leptos::prelude::expect_context::<I18n>();
println!("Macro parameters: {:?}", i18n.meta().unwrap());

`initial_language_from_server_function`

Get the initial language from a server function.

leptos_fluent! {
    // ...
    initial_language_from_server_function: initial_language_server_function,
}

/// Server function to set the initial language
#[server(InitialLanguage, "/api")]
pub async fn initial_language_server_function(
) -> Result<Option<String>, ServerFnError> {
    // .. replace with your own logic
    Ok(Some("es".to_string()))
}

This parameter type is not like the initial_language_from_* parameters, it takes an identifier to the server function that will be called to get the initial language.

The function must return a Result<Option<String>, ServerFnError>.

`set_language_to_server_function`

Set the current language to a server function.

leptos_fluent! {
    // ...
    set_language_to_server_function: set_language_server_function,
}

/// Server function to update the current language
#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

This parameter type is not like the set_language_to_* parameters, it takes an identifier to the server function that will be called to update the current language.

The function must return a Result<(), ServerFnError>.

`initial_language_from_local_storage_to_server_function`

Get the initial language from local storage and set it to a server function.

leptos_fluent! {
    // ...
    initial_language_from_local_storage_to_server_function: set_language_server_function,
}

#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

`initial_language_from_session_storage_to_server_function`

Get the initial language from session storage and set it to a server function.

leptos_fluent! {
    // ...
    initial_language_from_session_storage_to_server_function: set_language_server_function,
}

#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

`initial_language_from_cookie_to_server_function`

Get the initial language from a cookie and set it to a server function.

leptos_fluent! {
    // ...
    initial_language_from_cookie_to_server_function: set_language_server_function,
}

#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

`initial_language_from_navigator_to_server_function`

Get the initial language from navigator.languages and set it to a server function.

leptos_fluent! {
    // ...
    initial_language_from_navigator_to_server_function: set_language_server_function,
}

#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

`initial_language_from_url_param_to_server_function`

Get the initial language from a URL parameter and set it to a server function.

leptos_fluent! {
    // ...
    initial_language_from_url_param_to_server_function: set_language_server_function,
}

#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

`initial_language_from_url_path_to_server_function`

Get the initial language from a URL path and set it to a server function.

leptos_fluent! {
    // ...
    initial_language_from_url_path_to_server_function: set_language_server_function,
}

#[server(SetLanguage, "/api")]
pub async fn set_language_server_function(
    language: String,
) -> Result<(), ServerFnError> {
    // .. replace with your own logic
    Ok(())
}

`initial_language_from_server_function_to_cookie`

Get the initial language from a server function and set it to a cookie.

leptos_fluent! {
    // ...
    initial_language_from_server_function_to_cookie: true,
}

`initial_language_from_server_function_to_local_storage`

Get the initial language from a server function and set it to local storage.

leptos_fluent! {
    // ...
    initial_language_from_server_function_to_local_storage: true,
}

Keyboard shortcuts

leptos-fluent

system | Data files on Desktop applications

system | initial_language_from_system

system | initial_language_from_data_file

system | initial_language_from_system_to_data_file

system | set_language_to_data_file

system | data_file_key: "leptos-fluent"

system | `initial_language_from_system`

system | `initial_language_from_data_file`

system | `initial_language_from_system_to_data_file`

system | `set_language_to_data_file`

system | `data_file_key:` "leptos-fluent"