Introduction

leptos-fluent is a framework for internationalizing Leptos applications using Fluent. It has all the batteries included to handle language switching, translations management, multiple strategies for activating translations at initialization, different modes of persistent storage, and more.

Alternatives

The unique alternative to leptos-fluent currently is Leptos i18n, which follows a different approach. The main differences are:

leptos-fluent uses Fluent files and the Fluent syntax for translations, while leptos_i18n uses JSON files and a custom syntax.
leptos-fluent defines all the configuration in a macro and an optional languages file, while leptos_i18n defines the configuration in a [package.metadata.leptos-i18n] section in Cargo.toml.
leptos-fluent allows to instantiate multiple internationalization contexts, while leptos_i18n only allows one.
leptos-fluent has a lot of strategies for activating the initial language of the user at initialization and updating it when the user changes the language, while leptos_i18n only follows the cookie strategy.
leptos-fluent automatically builds language names and directions based on language codes, while leptos_i18n don't.
leptos-fluent has multiple side effects for updating the language in the client, while leptos_i18n only has the <html lang="..."> attribute and is not configurable.

Project goals

The main goals of leptos-fluent are:

To provide a simple and easy-to-use API for internationalizing Leptos applications.
Be the most fully featured internationalization framework in any language.
Be the most performant internationalization framework available.

Defining the internationalization strategy using a macro allows to generate the less code possible for each possible configuration.

Help and support

You can ask for help and support in the #leptos-fluent channel of Leptos Discord server, open a discussion in the GitHub repository or report bugs by opening an issue.

Contributing

See CONTRIBUTING.md file for more information about how to setup the development environment and contribute to the project.

Installation

CSR

For client side rendering apps install leptos-fluent and fluent-templates:

[dependencies]
leptos-fluent = "0.1"
fluent-templates = "0.9"

Minimal

Using default-features = false the json default feature of leptos-fluent will not be enabled, so the languages parameter of leptos_fluent! macro will not be available.

[dependencies]
leptos-fluent = { version = "0.1", default-features = false }
fluent-templates = "0.9"

SSR

For server side rendering apps install leptos-fluent, fluent-templates and activate the hydrate, ssr and actix/axum features in their respective features set.

[dependencies]
leptos-fluent = "0.1"
fluent-templates = "0.9"

[features]
hydrate = [
  "leptos-fluent/hydrate"
]
ssr = [
  "leptos-fluent/ssr",
  "leptos-fluent/actix",  # actix and axum are supported
]

# Using cargo-leptos
[package.metadata.leptos]
watch-additional-files = ["locales"]

Desktop applications

leptos-fluent can be installed on non-wasm targets, like desktop applications. You need to install leptos-fluent, fluent-templates and enable the system feature:

[dependencies]
leptos-fluent = { version = "0.1", features = ["system"] }
fluent-templates = "0.9"

Example

See the GTK example.

Features

Server Side Rendering: ssr
Hydration: hydrate
Actix Web integration: actix
Axum integration: axum
Nightly toolchain: nightly
Desktop applications: system
JSON languages file: json (enabled by default)
YAML languages file: yaml
JSON5 languages file: json5
Tracing support: tracing

Nightly toolchain

leptos-fluent builds nightly functionalities by enabling the nightly feature:

[dependencies]
leptos-fluent = { version = "0.1", features = ["nightly"] }
fluent-templates = "0.9"

Language files

By default, leptos-fluent supports JSON languages files. To use other formats to load custom languages, the json5 or yaml features can be enabled:

[dependencies]
fluent-templates = "0.9"
leptos-fluent = { version = "0.1", features = ["json5"], default-features = false }

Tip

See 4. Languages.

Tracking locales files with `cargo leptos`

Using cargo leptos watch of the locales/ folder for reloads:

# Relative to Cargo.toml file
[package.metadata.leptos]
watch-additional-files = ["locales"]

When inside a workspace, use the full path to the folder from the workspace Cargo.toml file:

 # Relative to workspace Cargo.toml file
[package.metadata.leptos]
watch-additional-files = ["examples/csr/locales"]

Tracing

To enable tracing support, add the tracing feature to leptos-fluent:

[dependencies]
leptos-fluent = { version = "0.1", features = ["tracing"] }
fluent-templates = "0.9"

Example

See the GTK example.

Basic usage

Minimal skeleton

The most basic CSR app is reproduced here:

.
├── 📄 Cargo.toml
├── 📁 locales
│   ├── 📁 en
│   │   └── 📄 main.ftl
│   └── 📁 es
│       └── 📄 main.ftl
└── 📁 src
    ├── 📄 main.rs
    └── 📄 lib.rs

# locales/en/main.ftl
select-a-language = Select a language:
language-selected-is = The selected language is { $lang }.

# locales/es/main.ftl
select-a-language = Selecciona un idioma:
language-selected-is = El idioma seleccionado es { $lang }.

#![allow(unused)]
fn main() {
// src/lib.rs
use fluent_templates::static_loader;
use leptos::*;
use leptos_fluent::{expect_i18n, leptos_fluent, move_tr, Language};

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

#[component]
pub fn App() -> impl IntoView {
    leptos_fluent! {{
        translations: [TRANSLATIONS],
        locales: "./locales",
    }};

    view! { <LanguageSelector/> }
}

#[component]
fn LanguageSelector() -> impl IntoView {
    // Use `expect_i18n()` to get the current i18n context:
    let i18n = expect_i18n();

    view! {
        <p>{move_tr!("select-a-language")}</p>
        <fieldset>
            {move || {
                i18n.languages.iter().map(|lang| render_language(lang)).collect::<Vec<_>>()
            }}
        </fieldset>
        <p>
            {move_tr!(
                 "language-selected-is",
                 { "lang" => i18n.language.get().name }
            )}
        </p>
    }
}

fn render_language(lang: &'static Language) -> impl IntoView {
    // Passed as atrribute, `Language` is converted to their code,
    // so `<input id=lang` becomes `<input id=lang.id.to_string()`
    view! {
        <div>
            <label for=lang>{lang.name}</label>
            <input
                id=lang
                value=lang
                name="language"
                checked=lang.is_active()
                on:click=move |_| lang.activate()
                type="radio"
            />
        </div>
    }
}
}

// src/main.rs
pub fn main() {
    console_error_panic_hook::set_once();
    leptos::mount_to_body(minimal_example::App);
}

# Cargo.toml
[package]
name = "minimal-example"
edition = "2021"
version = "0.1.0"

[lib]
name = "minimal_example"
path = "src/lib.rs"

[dependencies]
leptos = { version = "0.6.12", features = ["csr"] }
leptos-fluent = "0.1"
fluent-templates = "0.9"
console_error_panic_hook = "0.1"

# Using cargo-leptos
[package.metadata.leptos]
watch-additional-files = ["locales"]

Translating messages

Use the move_tr! macro to translate a string. The macro takes the key of the translation and an optional object with the variables to interpolate:

#![allow(unused)]
fn main() {
move_tr!("select-a-language")

move_tr!("language-selected-is", { "lang" => i18n.language.get().name })
}

Additionally, use the tr! macro to translate a string inside a reactive context. Note that if is not inside a reactive context, the translation won't be updated on the fly when the language changes. This can lead to warnings in console output like:

Warning

At `./path/to/file.rs:ln`, you access a signal or memo (defined at
`./path/to/file.rs:ln`) outside of a reactive context. This might mean your
app is not responding to changes in signal values in the way you expect.

Can be fixed by replacing calls to tr! with move_tr! or wrapping the tr! calls in a reactive context.

The previous code could be rewritten as:

#![allow(unused)]
fn main() {
move || tr!("select-a-language")

move || tr!("language-selected-is", { "lang" => i18n.language.get().name })
}

The main difference is that move_tr! encapsulates the movement in a leptos::Signal, strictly would be rewritten as:

#![allow(unused)]
fn main() {
leptos::Signal::derive(move || tr!("select-a-language"))
}

Retrieving the `I18n` context

Use the expect_i18n function to get the current i18n context:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent::expect_i18n();
}

It is exported as i18n too:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent::i18n();
}

The function use_i18n returns an Option with the current i18n context:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent::use_i18n().expect("No `I18n` context found");
}

Using the `I18n` context

The i18n context has the following fields:

language: A read-write signal with a pointer to the static current active language.
languages: A pointer to a static list of pointers of the static available languages.
translations: A signal to the vector of fluent-templates loaders that stores the translations.

Update language

To update the language, use lang.activate or the set method of language:

#![allow(unused)]
fn main() {
lang.activate();

expect_i18n().language.set(lang);
}

Nightly

When nightly feature is enabled, can be updated passing a new language to the context as a function with:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent::i18n();
i18n(lang);
}

Get active language

To get the current active language, use get method of language field:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent::i18n();
let lang = i18n.language.get();
}

Nightly

When nightly enabled, can get the active language with:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent::i18n();
let lang = i18n();
}

Get available languages

To get the available languages, iterate over the languages field:

#![allow(unused)]
fn main() {
i18n.languages.iter()
}

Check if a language is active

To check if a language is the active one, use is_active method of a leptos_fluent::Language struct:

#![allow(unused)]
fn main() {
lang.is_active()
}

Strategies

All the features of the framework are optional, following a declarative "opt-in" configuration method.

Loading the initial language of the user

The initial language of the user can be set in different ways:

Strategy	CSR	SSR	Desktop	`leptos_fluent!`
URL parameter	✅	✅	❌	`initial_language_from_url_param`
Cookie	✅	✅	❌	`initial_language_from_cookie`
Server function	✅	✅	❌	`initial_language_from_server_function`
Browser local storage	✅	❌	❌	`initial_language_from_localstorage`
Browser `navigator.languages`	✅	❌	❌	`initial_language_from_navigator`
`Accept-Language` header	❌	✅	❌	`initial_language_from_accept_language_header`
System language	❌	❌	✅	`initial_language_from_system`
Data file	❌	❌	✅	`initial_language_from_data_file`

All of them can be defined at the same time or just one of them at the same time. The first language source found will be used and nexts discharged. The order of precedence is:

SSR
1. Server function
2. URL parameter
3. Cookie
4. Accept-Language header
CSR
1. Server function
2. URL parameter
3. Cookie
4. Browser local storage
5. Browser navigator.languages
Desktop (system feature)
1. Data file
2. System language

CSR | Updating the language on the client

When the user changes the language and I18n::language.set is called, the framework can perform a side effect to update the language in the client. The following strategies are available:

Strategy	`leptos_fluent!`
URL parameter	`set_language_to_url_param`
Cookie	`set_language_to_cookie`
Browser local storage	`set_language_to_localstorage`
Server function	`set_language_to_server_function`

system | Desktop applications

Strategy	`leptos_fluent!`
Data file	`set_language_to_data_file`

CSR | Updating the language from initialization on the client

When a language is loaded from initialization, the framework can perform a side effect to persistently storage the language in the client. The following strategies are available:

Strategy	`leptos_fluent!`
URL parameter to local storage	`initial_language_from_url_param_to_localstorage`
URL parameter to cookie	`initial_language_from_url_param_to_cookie`
Cookie to local storage	`initial_language_from_cookie_to_localstorage`
Local storage to cookie	`initial_language_from_localstorage_to_cookie`
Local storage to server function	`initial_language_from_localstorage_to_server_function`
`navigator.languages` to local storage	`initial_language_from_navigator_to_localstorage`
`navigator.languages` to cookie	`initial_language_from_navigator_to_cookie`
`navigator.languages` to server function	`initial_language_from_navigator_to_server_function`
Server function to local storage	`initial_language_from_server_function_to_localstorage`

CSR + SSR

Strategy	`leptos_fluent!`
URL parameter to server function	`initial_language_from_url_param_to_server_function`
Cookie to server function	`initial_language_from_cookie_to_server_function`
Server function to cookie	`initial_language_from_server_function_to_cookie`

system | Desktop applications

Strategy	`leptos_fluent!`
System language to data file	`initial_language_from_system_to_data_file`

CSR | Client side effects

When the user updates the language, the framework can perform side effects to update the language in the client. The following side effects are available:

Side effect	`leptos_fluent!`
`<html lang="...">` attribute	`sync_html_tag_lang`
`<html dir="...">` attribute	`sync_html_tag_dir`

CSR + SSR | Names

The names of the settings can be configured using the following parameters:

Strategy	`leptos_fluent!`	Default value
Cookie	`cookie_name`	`"lf-lang"`
Cookie attributes	`cookie_attrs`	`""`
Browser local storage	`localstorage_key`	`"lang"`
URL parameter	`url_param`	`"lang"`

system | Desktop applications

Strategy	`leptos_fluent!`	Default value
Data file	`data_file_key`	`"leptos-fluent"`

Languages

leptos-fluent follows a default strategy to generate the languages of the application. This strategy is based on the locales/ directory.

Giving the next directory structure:

.
└── 📁 locales
    ├── 📁 en
    │   └── 📄 main.ftl
    └── 📁 es-ES
        └── 📄 main.ftl

The framework will generate something like the following languages array at compile time:

#![allow(unused)]
fn main() {
let LANGUAGES = [
  leptos_fluent::Language {
    id: unic_langid::langid!("en"),
    name: "English",
    dir: leptos_fluent::WritingDirection::Ltr,
  },
  leptos_fluent::Language {
    id: unic_langid::langid!("es-ES"),
    name: "Español (España)",
    dir: leptos_fluent::WritingDirection::Ltr,
  },
]
}

en is built with the name "English" because it's defined as an ISO 639-1 code, without a region code.
es-ES is built with the name "Español (España)" because it's defined as an ISO 639-1 code and a region code.

This enforces that an user will always be able to select their language in their own language, and not in the current language of the application.

Order

The order of the languages will be defined based on the alphabetical order of their names, not their codes.

The languages file

The languages array can be fully customized by defining a languages parameter in the leptos_fluent! macro pointing to a languages file. This file must be relative to the Cargo.toml file.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    languages: "./locales/languages.json",
    // ...
}}
}

[
  ["en", "English"],
  ["es-ES", "Spanish (Spain)", "auto"]
]

The languages file must expose an array of arrays with the structure:

[
  // Code, Name,            "ltr"/"rtl"/"auto" (optional)
  ["code", "Language name", "Writing direction"],
]

Order

The order of the languages in leptos_fluent::I18n::languages will be the same as in the file regardless of the alphabetical order of the names.

The first in the languages file will used as the initial of the user when any other initialization value is discovered. Use the same as the one configured as fallback_language in static_loader!.

#![allow(unused)]
fn main() {
static_loader! {
    static TRANSLATIONS = {
        locales: "./locales",
        fallback_language: "en",
    };
}

#[component]
pub fn App() -> impl IntoView {
    leptos_fluent! {{
        translations: [TRANSLATIONS],
        languages: "./locales/languages.json5",
    }};
}
}

// ./locales/languages.json5
[
  ["en", "English"],
  ["es-ES", "Español (España)"],
]

File format

By default, the json feature is enabled, which only allows to set the languages file in JSON format. To use other formats, disable the feature and enable another.

[dependencies]
leptos-fluent = { version = "*", default-features = false, features = ["json5"] }

Available features for languages file formats are:

json: JSON (default)
yaml: YAML
json5: JSON5

Checking translations

To check that the translations of the app are correct at compile time, set the check_translations parameter in the leptos_fluent! macro to a glob pattern that matches the Rust files that you want to check.

The pattern must be relative to the location of the Cargo.toml file.

For single crate projects, it would be something like:

#![allow(unused)]
fn main() {
leptos_fluent! {{
    check_translations: "./src/**/*.rs",
}}
}

For workspace projects, it could be something like:

#![allow(unused)]
fn main() {
leptos_fluent! {{
    check_translations: "../{app,components}/src/**/*.rs",
}}
}

Translations error messages

When the translations stop being synchronized, you will see errors like:

error: Translations check failed:
       - Message "select-a-language" defined at `move_tr!("select-a-language")` macro call in src/lib.rs not found in files for locale "en".
       - Message "select-a-lang" of locale "en" not found in any `tr!` or `move_tr!` macro calls.
  --> examples/csr-complete/src/lib.rs:18:29
   |
18 |         check_translations: "./src/**/*.rs",
   |                             ^^^^^^^^^^^^^^^

If placeable are missing in the translations, you will see errors like:

error: Translations check failed:
       - Variable "dir" defined at `move_tr!("html-tag-dir-is", { ... })` macro call in src/lib.rs not found in message "html-tag-dir-is" of locale "en".
       - Variable "name" defined in message "html-tag-dir-is" of locale "en" not found in arguments of `move_tr!("html-tag-dir-is", { ... })` macro call at file src/lib.rs.
  --> examples/csr-complete/src/lib.rs:18:29
   |
18 |         check_translations: "./src/**/*.rs",
   |                             ^^^^^^^^^^^^^^^

Why glob patterns to Rust files?

leptos-fluent provides a I18n context to Leptos when the macro leptos_fluent! is called. So multiple instances of a context with different localization files and strategies can be initialized in different component trees. This is useful, for example, in a multi page app.

The mechanism of translations checking needs to know where reside the calls to tr! and move_tr! macros to extract the messages that need to be checked. This is performed by parsing the source code looking for these macros invocations.

Why macros

leptos-fluent doesn't provide ways to translate directly using I18n context methods, as it would be impossible to extract the translations at compile time.

The only limitation for checking translations with glob patterns is that the tr! and move_tr! macros that consume each context must be in different file trees, but this enforces anyway a good practice of file-level separation of contexts in the codebase.

FAQs

How to get `LanguageIdentifier` if not installed?

#![allow(unused)]
fn main() {
use fluent_templates::LanguageIdentifier;
}

Tip

fluent-templates also depends externally on fluent-bundle whichs provides utilities for parsing the Fluent syntax.

How to get the i18n context at initialization?

#![allow(unused)]
fn main() {
use leptos_fluent::leptos_fluent;

let i18n = leptos_fluent! {{
    // ...
}};

leptos::logging::log!("i18n context: {i18n:?}");
}

Use an expression to set the cookie attributes and will not be validated.

#![allow(unused)]
fn main() {
let attrs = "SameSite=Strict; MyCustomAttr=MyCustomValue;";
leptos_fluent! {{
    cookie_attrs: attrs,
    // ...
}}
}

How to get the fallback language

From fluent-templates v0.9.5 onwards can be obtained from your translations.

#![allow(unused)]
fn main() {
let fallback_language = expect_i18n().translations.get()[0].fallback();
}

Why examples don't use `<For/>` component?

Bug

There are some cases in which the <For/> component is not reproducible between SSR and hydrate modes leading to different renders, so decided to use a simple vector to not bring confusion to main examples.

In any case, the <For/> component is secure on CSR contexts and leptos_fluent::Languages implement Hash and Eq traits to be able to be passed directly to keys properties trigerring reactivity depending on the current active language.

#![allow(unused)]
fn main() {
use leptos_fluent::{i18n, Language};

leptos::logging::warn!("[WARNING]: Not secure on SSR");
view! {
    <p>{move_tr!("select-a-language")}</p>
    <For
        each=move || i18n().languages
        key=|lang| *lang
        children=move |lang| render_language(lang)
    />
}

fn render_language(lang: &'static Language) -> impl IntoView { ... }
}

How to manage translations on server actions

The translations reside on the client side, so the I18n can not be accessed as context on server actions. Pass the translations as values if the bandwidth is not a problem or use your own statics on server side.

#![allow(unused)]
fn main() {
use leptos::*;
use leptos_fluent::{tr, Language};

/// Server action showing client-side translated message on console
#[server(ShowHelloWorld, "/api")]
pub async fn show_hello_world(
    translated_hello_world: String,
    language: String,
) -> Result<(), ServerFnError> {
    println!("{translated_hello_world} ({language})");
    Ok(())
}

fn render_language(lang: &'static Language) -> impl IntoView {
    // Call on click to server action with a client-side translated
    // "hello-world" message
    let on_click = move |_| {
        lang.activate();
        spawn_local(async {
            _ = show_hello_world(
                tr!("hello-world"),
                lang.name.to_string(),
            ).await;
        });
    };

    view! {
        <div>
            <label for=lang>{lang.name}</label>
            <input
                id=lang
                name="language"
                value=lang
                checked=lang.is_active()
                on:click=on_click
                type="radio"
            />
        </div>
    }
}
}

How to change `<html>` attributes on SSR

Use the component leptos_fluent::SsrHtmlTag:

#![allow(unused)]
fn main() {
use leptos::*;
use leptos_fluent::{leptos_fluent, SsrHtmlTag};

#[component]
pub fn App() -> impl IntoView {
    leptos_fluent! {{
        // ...
    }};

    view! {
        <SsrHtmlTag/>
        <LanguageSelector/>
    }
}

#[component]
fn LanguageSelector() -> impl IntoView { ... }
}

How to get values of `leptos_fluent!` macro at runtime?

Use provide_meta_context at the macro initialization and get them with the method I18n::meta:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent! {{
    // ...
    provide_meta_context: true,
}};

println!("Macro parameters: {:?}", i18n.meta().unwrap());
}

Different configuration conditional checks

leptos_fluent! macro does not allows to set the same macro parameter multiple times with different configuration conditional checks, but the next approach can be used instead:

#![allow(unused)]
fn main() {
#[cfg(feature = "ssr")]
let param = "ssr-lang";
#[cfg(feature = "hydrate")]
let param = "hydrate-lang";
#[cfg(debug_assertions)]
let param = "debug-lang";

leptos_fluent! {{
    // ...
    #[cfg(any(feature = "ssr", feature = "hydrate", debug_assertions))]
    url_param: param,
    #[cfg(debug_assertions)]
    initial_language_from_url_param: true,
}}
}

`leptos_fluent!`

The leptos_fluent! macro is used to load the translations and set the current locale. It is used in the root component of the application.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    translations: [TRANSLATIONS],
}}
}

Common configurations

CSR | Local storage from navigator

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    translations: [TRANSLATIONS],

    set_language_to_localstorage: true,
    initial_language_from_localstorage: true,
    initial_language_from_navigator: true,
    initial_language_from_navigator_to_localstorage: true,
    initial_language_from_url_param: true,
    initial_language_from_url_param_to_localstorage: true,
    localstorage_key: "lang",
}}
}

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    translations: [TRANSLATIONS],

    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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    translations: [TRANSLATIONS],

    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, localstorage_key, navigator...

Sources and targets

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

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

Commented example

Example

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
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],
    // ^^^^^^^^^^^^^^^^^^^^^^^^^
}}
}

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

`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.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    // ^^^^^^^^^^^^^^^^^
    translations: [TRANSLATIONS],
}}
}

`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:

#![allow(unused)]
fn main() {
static_loader! {
    pub static TRANSLATIONS = {
        locales: "./locales",
        core_locales: "./locales/core",
    };
}

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.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    languages: "./locales/languages.json",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    translations: [TRANSLATIONS],
}}
}

Tip

See 4. Languages

The languages file should contain an array of arrays where each inner array contains a language identifier and a language name, respectively, at least.

The language identifier should be a valid language tag, such as en-US, en, es-ES, etc. By default, the languages file should be a JSON with a .json extension because the json feature is enabled. For example:

[
  ["en-US", "English (United States)"],
  ["es-ES", "Español (España)"]
]

Set default-features = false and enable the yaml or the json5 feature to use a YAML or JSON5 files. For example:

# locales/languages.yaml
- - en-US
  - English (United States)
- - es-ES
  - Español (España)

// locales/languages.json5
[
  ["en-US", "English (United States)"],
  ["es-ES", "Español (España)"],
]

Define a third element in the inner array with the direction of the language, to use it in the <html dir="..."> attribute (see sync_html_tag_dir). For example:

[
  ["en-US", "English (United States)", "ltr"],
  ["es-ES", "Español (España)", "auto"],
  ["ar", "العربية", "rtl"],
  ["it", "Italiano"]
]

`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.

For single crate projects:

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    translations: [TRANSLATIONS],
    check_translations: "./src/**/*.rs",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}}
}

For workspace projects:

#![allow(unused)]
fn main() {
leptos_fluent! {{
    locales: "./locales",
    translations: [TRANSLATIONS],
    check_translations: "../{app,components}/src/**/*.rs",
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}}
}

CSR | `sync_html_tag_lang`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    sync_html_tag_lang: true,
}}
}

CSR | `sync_html_tag_dir`

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

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

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    url_param: "lang",
}}
}

CSR + SSR | `initial_language_from_url_param`

Set initial language from URL parameter.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_url_param: true,
}}
}

CSR | `initial_language_from_url_param_to_localstorage`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_url_param_to_localstorage: true,
}}
}

CSR | `initial_language_from_url_param_to_cookie`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_url_param_to_cookie: true,
}}
}

CSR | `set_language_to_url_param`

Synchronize current language with URL parameter.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    set_language_to_url_param: true,
}}
}

CSR | `localstorage_key:` "lang"

Local storage key to manage the current language.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    localstorage_key: "lang",
}}
}

CSR | `initial_language_from_localstorage`

Get initial language from local storage.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_localstorage: true,
}}
}

CSR | `initial_language_from_localstorage_to_cookie`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_localstorage_to_cookie: true,
}}
}

CSR | `set_language_to_localstorage`

Set the current language to local storage.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    set_language_to_localstorage: true,
}}
}

CSR | `initial_language_from_navigator`

Get the initial language from navigator.languages.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_navigator: true,
}}
}

CSR | `initial_language_from_navigator_to_localstorage`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_navigator_to_localstorage: true,
}}
}

CSR | `initial_language_from_navigator_to_cookie`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_navigator_to_cookie: true,
}}
}

SSR | `initial_language_from_accept_language_header`

Get the initial language from the Accept-Language header.

#![allow(unused)]
fn main() {
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".

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    cookie_name: "lang",
}}
}

CSR | `cookie_attrs:` ""

Cookie attributes to set on the language cookie.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    cookie_attrs: "SameSite=Strict; Secure",
}}
}

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

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_cookie: true,
}}
}

CSR | `initial_language_from_cookie_to_localstorage`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_cookie_to_localstorage: true,
}}
}

CSR | `set_language_to_cookie`

Set the current language to the cookie.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    set_language_to_cookie: true,
}}
}

system | `initial_language_from_system`

Get the initial language from the system.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_system: true,
}}
}

system | `initial_language_from_data_file`

Get the initial language from a data file.

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_system_to_data_file: true,
}}
}

system | `set_language_to_data_file`

Set the current language to a data file.

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
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:

#![allow(unused)]
fn main() {
let i18n = leptos_fluent! {{
    // ...
    provide_meta_context: true,
}};

println!("Macro parameters: {:?}", i18n.meta().unwrap());
}

`initial_language_from_server_function`

Get the initial language from a server function.

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
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_localstorage_to_server_function`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_localstorage_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.

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
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_server_function_to_cookie`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_server_function_to_cookie: true,
}}
}

`initial_language_from_server_function_to_localstorage`

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

#![allow(unused)]
fn main() {
leptos_fluent! {{
    // ...
    initial_language_from_server_function_to_localstorage: true,
}}
}

leptos-fluent

Retrieving the I18n context

Using the I18n context

system | Desktop applications

system | Desktop applications

system | Desktop applications

How to get LanguageIdentifier if not installed?

How to get the i18n context at initialization?

Custom cookie attributes are invalid

Why examples don't use <For/> component?

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"

Retrieving the `I18n` context

Using the `I18n` context

How to get `LanguageIdentifier` if not installed?

Why examples don't use `<For/>` component?

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"