Skip to main content

Crate teksilo_i18n_macros

Crate teksilo_i18n_macros 

Source
Expand description

Compile-time-validating proc macros for Teksilo’s i18n runtime.

This crate exports tr! and tr_widget!, the two proc macros that application code and framework code use to produce LocalizedString values. Both macros validate every invocation against a Fluent source .ftl file at compile time: they read the file, parse it via fluent-syntax, and check that the referenced key exists with matching argument names. Missing keys, missing arguments, and unknown arguments are rejected with a compile_error! pointing at the call site.

The runtime side of the i18n stack lives in teksilo-i18n. The macros emit code that calls localized(...) and resolve_message[_widget](...) under one of two crate roots (see SourceKind::i18n_root): external crates route through ::teksilo::i18n, so they only need teksilo in deps (with the i18n feature enabled); internal teksilo-* crates route through ::teksilo_i18n, which they must depend on instead — they cannot depend on teksilo (circular).

§Source file resolution

tr! reads $CARGO_MANIFEST_DIR/locales/en-US/ as a directory of .ftl files when that directory exists, and otherwise the single $CARGO_MANIFEST_DIR/locales/en-US.ftl file. For tests that need a different fixture, set TEKSILO_I18N_SOURCE_DIR (directory) or TEKSILO_I18N_SOURCE_PATH (single file) at compile time to a path relative to CARGO_MANIFEST_DIR (or an absolute path); the directory variable wins over the file one.

tr_widget! reads the same path. It is used inside teksilo-widgets where the crate’s own manifest dir points at the framework’s own .ftl file.

§Cache and rebuild tracking

The parsed key→args map is cached per path for the duration of a single proc-macro process, so a crate with hundreds of tr! calls parses each .ftl file once.

To ensure cargo rebuilds the downstream crate when the .ftl file changes, every expansion also emits an include_bytes!(...) token for the source file. include_bytes! is a compiler builtin that registers the path as a build dependency — the same mechanism cargo uses to track include_str! files.

Macros§

tr
Compile-time-validating translation macro for application strings.
tr_signal
Reactive variant of tr! for the Signal<T>-inside-translated-sentence case. Every named argument expression must evaluate to a Signal<T> where T: Clone + 'static + Into<FluentValue<'static>>. Returns a Signal<String> that re-renders on (any arg change ∪ locale change ∪ .ftl hot reload).
tr_signal_widget
Reactive variant of tr_widget!. Same arg shape as tr_signal!.
tr_widget
Compile-time-validating translation macro for framework-internal strings. Same surface as tr!, but routes to the framework bundle at runtime. Only used inside teksilo-widgets.