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 theSignal<T>-inside-translated-sentence case. Every named argument expression must evaluate to aSignal<T>whereT: Clone + 'static + Into<FluentValue<'static>>. Returns aSignal<String>that re-renders on (any arg change ∪ locale change ∪.ftlhot reload). - tr_
signal_ widget - Reactive variant of
tr_widget!. Same arg shape astr_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 insideteksilo-widgets.