Internationalization

Internationalization

Requires the i18n feature flag.

lurq = { version = "0.41.1", features = ["i18n"] }

Setup

Add translation resources to App before mounting the root component. Each resource belongs to a locale and a namespace.

use lurq::app::App;

let app = App::new();
app.i18n().add_resource("en", "translation", "hello", "Hello");
app.i18n().add_resource("en", "translation", "goodbye", "Goodbye");
app.i18n().add_resource("uk", "translation", "hello", "Привіт");
app.i18n().add_resource("uk", "translation", "goodbye", "До побачення");

Use add_resources to register multiple keys at once:

app.i18n().add_resources("en", "translation", [
  ("hello", "Hello"),
  ("goodbye", "Goodbye"),
  ("welcome", "Welcome, {{name}}"),
]);

Translating In Components

Inside a component, call ctx.t(key) to look up a key in the default namespace ("translation").

use lurq::{
  app::{component::Component, ctx::Ctx},
  components::Text,
  node::Element,
};

struct Greeting;

impl Component for Greeting {
  type Props = ();

  fn create(_ctx: &mut Ctx) -> Self { Self }

  fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
    Text::new(&ctx.t("hello"))
  }
}

Translation lookups return Arc<str> rather than String. Resource values are stored as Arc<str>, so a lookup without interpolation hands back a cheap reference-counted clone with no string copy. Only interpolation (t_args / t_ns_args with arguments) allocates a new string.

Translation lookups are reactive — when the locale changes, every component that called ctx.t(...) re-renders automatically.

Interpolation

Use {{variable}} placeholders in translation values. Pass arguments with ctx.t_args:

// resource: "welcome" => "Welcome, {{name}}"
let text = ctx.t_args("welcome", [("name", "Ada")]);
// => "Welcome, Ada"

Namespaces

Organize translations into namespaces for large apps. Use ctx.t_ns or ctx.t_ns_args to look up keys outside the default namespace.

app.i18n().add_resource("en", "errors", "not_found", "Page not found");

// in render:
let msg = ctx.t_ns("errors", "not_found");

Locale Switching

app.i18n().set_locale("uk");

Calling set_locale bumps an internal version signal. All components that read translations re-render on the next frame.

Fallback Locale

If a key is missing for the active locale, the fallback locale is tried. The default fallback is "en".

app.i18n().set_fallback_locale("en");

API Summary

I18n (accessed via app.i18n())

Method	Description
locale()	Current locale string.
set_locale(locale)	Change the active locale.
fallback_locale()	Current fallback locale.
set_fallback_locale(locale)	Change the fallback locale.
add_resource(locale, namespace, key, value)	Register a single translation.
add_resources(locale, namespace, entries)	Register multiple translations.
t(key)	Look up in default namespace. Returns Arc<str>.
t_ns(namespace, key)	Look up in a specific namespace. Returns Arc<str>.
t_args(key, args)	Look up with interpolation. Returns Arc<str>.
t_ns_args(namespace, key, args)	Namespace lookup with interpolation. Returns Arc<str>.

Ctx shortcuts (require i18n feature)

Method	Equivalent to
ctx.t(key)	ctx.i18n().t(key)
ctx.t_ns(ns, key)	ctx.i18n().t_ns(ns, key)
ctx.t_args(key, args)	ctx.i18n().t_args(key, args)
ctx.t_ns_args(ns, key, args)	ctx.i18n().t_ns_args(ns, key, args)
ctx.i18n()	Direct access to the I18n instance.

Missing Keys

When a key is not found in either the active locale or the fallback locale, the key itself is returned as the translation string.