repository·master·Indexed 41 days ago
https://github.com/baptistemontan/leptos_i18nA translations integration helper for the Leptos web framework that provides compile-time loading of locales and validation for translation keys and interpolation. It supports CSR, SSR (with Actix or Axum), and hydration, allowing developers to interpolate variables and components within localized strings and organize translations using namespaces or YAML.
The leptos_i18n crate is designed to simplify internationalization (i18n) within Leptos applications. Its primary advantage is that it loads locales at compile time, which enables compile-time checks for:
This ensures that missing translations or incorrect key usage are caught during the build process rather than at runtime.
Locale inheritance allows you to create specialized locales that build upon more general ones. This reduces duplication by allowing a child locale to override only specific keys while falling back to its parent locale for all other keys.
For example, an en-US locale can inherit from en. You only need to define the keys that differ (e.g., changing "colour" to "color"); all other keys will be automatically pulled from en.
{{ }}) must follow the same naming rules as translation keys.Foreign keys allow you to reference and reuse existing translation keys within your JSON files using the $t() syntax. This helps reduce duplication.
$t(key_name) to replace the placeholder with the value of key_name.$t(key.subkey.subsubkey).$t(namespace:key).{
"hello_world": "Hello World!",
"reuse": "message: $t(hello_world)"
}
// "reuse" becomes "message: Hello World!"Scoping in leptos_i18n is implemented using a typestate pattern.
When you scope an I18nContext<L>, the internal type changes from I18nContext<L> to I18nContext<L, S>, where S is a type representing the path to the keys. This allows the compiler to verify that the keys you are accessing via t! or td! actually exist within that specific scope.
Key takeaways for developers:
i18n module.define_scope! to hide this complexity by creating manageable aliases for these types.The leptos_i18n formatter parser is designed to be resilient and provide comprehensive feedback:
build method will not be called.parse_with_diagnostics function in the Formatter trait treats all problems as errors. You can override this method to implement custom logic for warnings, multiple errors, or specialized error types.The library detects the user's locale using a prioritized list of methods. The resolution order is as follows:
I18nRoute, the locale is extracted from the URL (e.g., /en/about).Accept-Language Header: Used during Server-Side Rendering (SSR) to match the browser's preferred language.navigator.languages API: Used during Client-Side Rendering (CSR) to match the browser's language settings.I18nRoute: The URL pathname locale is only resolved when the I18nRoute component begins rendering. Any logic that relies on the resolved locale before this component renders may use an incorrect or default locale.By default, leptos_i18n bakes translations into the binary at compile time. For projects with many locales or large translation files, this significantly increases binary size.
Enabling the "dynamic_load" feature allows the client to lazy-load translations as "translation units" (either one unit per locale or one unit per locale per namespace) via server functions. This reduces the initial binary size at the cost of some runtime overhead for requesting and parsing translations.
The leptos_i18n code generator expects keys to be consistent across all translation files. Discrepancies are measured against the default locale.
If a key exists in the default locale but is missing in a secondary locale:
To explicitly tell the generator to use the default locale's value without triggering a warning, set the value to null in the secondary locale:
{
"take_value_of_default": null
}If a key exists in a secondary locale but is not present in the default locale:
Locale resolution follows a specific priority:
/en/*), that locale is used immediately./counter), the locale is resolved via cookies, the Accept-Language request header, or the navigator API.Redirection Behavior:
If a locale is resolved (via cookies, etc.) that does not match the default locale, I18nRoute triggers an automatic navigation to the correct prefixed URL. For example, if the default is en but a cookie sets the locale to fr, accessing /counter will redirect the user to /fr/counter.
Navigation & History:
When using <A href=.. /> or leptos_router::use_navigate, you do not need to manually manage locale prefixes. The component handles the redirection, and it uses NavigateOptions.replace = true to ensure that intermediate redirection steps do not clutter the browser history.
By default, custom formatters might require values to implement Display. If you pass a Leptos Signal via a closure (e.g., t!(i18n, my_fmt, var = || signal.get())), the compiler may error because the closure itself does not implement Display.
To support reactivity, you can define a custom trait in your crate that accepts any function returning a Display type, and use that trait in your view_bounds and to_view implementations.
pub trait ToDisplayFn: 'static + Clone + Send + Sync {
type Value: Display;
fn to_value(&self) -> Self::Value;
}
impl<T: Display, F> ToDisplayFn for F
where
F: Fn() -> T + 'static + Clone + Send + Sync,
{
type Value = T;
fn to_value(&self) -> Self::Value {
self()
}
}view_bounds:fn view_bounds(&self) -> TokenStream {
quote!(crate::ToDisplayFn)
}to_view:fn to_view(&self, key: &syn::Ident, locale_field: &syn::Ident) -> TokenStream {
quote! {
move || {
std::format!(#fmt_string, crate::ToDisplayFn::to_value(&#key))
}
}
}The crate automatically establishes inheritance based on the structure of the locale string. It follows a pattern where more specific locales inherit from more general ones.
Matching Pattern: language[-region][-anything-else] inherits from language[-region].
Note: Scripts, variants, and extensions are ignored during automatic matching. For example, en-Latn-US-Valencia-u-ca-buddhist will automatically inherit from en-US because the system only considers the language (en) and region (US) components.