teksilo_i18n_macros/lib.rs
1// SPDX-License-Identifier: MPL-2.0
2// SPDX-FileCopyrightText: 2026 FernTech
3
4//! Compile-time-validating proc macros for Teksilo's i18n runtime.
5//!
6//! This crate exports `tr!` and `tr_widget!`, the two proc macros that
7//! application code and framework code use to produce `LocalizedString`
8//! values. Both macros validate every invocation against a Fluent source
9//! `.ftl` file at compile time: they read the file, parse it via
10//! `fluent-syntax`, and check that the referenced key exists with
11//! matching argument names. Missing keys, missing arguments, and unknown
12//! arguments are rejected with a `compile_error!` pointing at the call
13//! site.
14//!
15//! The runtime side of the i18n stack lives in `teksilo-i18n`. The macros
16//! emit code that calls `localized(...)` and
17//! `resolve_message[_widget](...)` under one of two crate roots (see
18//! `SourceKind::i18n_root`): external crates route through
19//! `::teksilo::i18n`, so they only need `teksilo` in deps (with the
20//! `i18n` feature enabled); internal `teksilo-*` crates route through
21//! `::teksilo_i18n`, which they must depend on instead — they cannot
22//! depend on `teksilo` (circular).
23//!
24//! # Source file resolution
25//!
26//! `tr!` reads `$CARGO_MANIFEST_DIR/locales/en-US/` as a directory of
27//! `.ftl` files when that directory exists, and otherwise the single
28//! `$CARGO_MANIFEST_DIR/locales/en-US.ftl` file. For tests that need a
29//! different fixture, set `TEKSILO_I18N_SOURCE_DIR` (directory) or
30//! `TEKSILO_I18N_SOURCE_PATH` (single file) at compile time to a path
31//! relative to `CARGO_MANIFEST_DIR` (or an absolute path); the directory
32//! variable wins over the file one.
33//!
34//! `tr_widget!` reads the same path. It is used inside teksilo-widgets
35//! where the crate's own manifest dir points at the framework's own
36//! `.ftl` file.
37//!
38//! # Cache and rebuild tracking
39//!
40//! The parsed key→args map is cached per path for the duration of a
41//! single proc-macro process, so a crate with hundreds of `tr!` calls
42//! parses each `.ftl` file once.
43//!
44//! To ensure cargo rebuilds the downstream crate when the `.ftl` file
45//! changes, every expansion also emits an `include_bytes!(...)` token
46//! for the source file. `include_bytes!` is a compiler builtin that
47//! registers the path as a build dependency — the same mechanism cargo
48//! uses to track `include_str!` files.
49
50use std::collections::HashMap;
51use std::path::PathBuf;
52use std::sync::{Mutex, OnceLock};
53
54use fluent_syntax::ast;
55use fluent_syntax::parser::parse;
56use proc_macro::TokenStream;
57use proc_macro2::TokenStream as TokenStream2;
58use quote::{quote, quote_spanned};
59use syn::parse::{Parse, ParseStream};
60use syn::punctuated::Punctuated;
61use syn::{Expr, Ident, Result, Token, parse_macro_input, spanned::Spanned};
62
63/// Compile-time-validating translation macro for application strings.
64///
65/// Usage: `tr!(key_name())` or `tr!(key_name(arg = expr, ...))`.
66///
67/// Expands to a `LocalizedString` that, at runtime, resolves the message
68/// through the active `I18nManager`'s application bundle.
69#[proc_macro]
70pub fn tr(input: TokenStream) -> TokenStream {
71 tr_impl(input, SourceKind::App, /* signal */ false)
72}
73
74/// Compile-time-validating translation macro for framework-internal
75/// strings. Same surface as `tr!`, but routes to the framework bundle at
76/// runtime. Only used inside `teksilo-widgets`.
77#[proc_macro]
78pub fn tr_widget(input: TokenStream) -> TokenStream {
79 tr_impl(input, SourceKind::Widget, /* signal */ false)
80}
81
82/// Reactive variant of `tr!` for the `Signal<T>`-inside-translated-sentence
83/// case. Every named argument expression must evaluate to a `Signal<T>`
84/// where `T: Clone + 'static + Into<FluentValue<'static>>`. Returns a
85/// `Signal<String>` that re-renders on (any arg change ∪ locale change ∪
86/// `.ftl` hot reload).
87///
88/// Use `tr!` for fully-static-arg call sites; this macro is for the
89/// reactive case.
90#[proc_macro]
91pub fn tr_signal(input: TokenStream) -> TokenStream {
92 tr_impl(input, SourceKind::App, /* signal */ true)
93}
94
95/// Reactive variant of `tr_widget!`. Same arg shape as `tr_signal!`.
96#[proc_macro]
97pub fn tr_signal_widget(input: TokenStream) -> TokenStream {
98 tr_impl(input, SourceKind::Widget, /* signal */ true)
99}
100
101#[derive(Clone, Copy)]
102enum SourceKind {
103 App,
104 Widget,
105}
106
107impl SourceKind {
108 /// The i18n crate root path.
109 ///
110 /// External apps route through `::teksilo::i18n` so they only
111 /// need `teksilo` in deps (the serde pattern). Internal teksilo
112 /// crates (`teksilo-widgets`, `teksilo-i18n` tests) route through
113 /// `::teksilo_i18n` because they can't depend on `teksilo` (circular).
114 fn i18n_root(self) -> TokenStream2 {
115 match self {
116 SourceKind::Widget => quote!(::teksilo_i18n),
117 SourceKind::App => {
118 // Internal workspace crates can't depend on `teksilo` (cycle),
119 // so they route through `::teksilo_i18n`; external apps route
120 // through `::teksilo::i18n` (the serde pattern — they only need
121 // `teksilo` in deps). A proc-macro can only see the *compiled*
122 // crate's name, and every internal crate starts with
123 // `teksilo-`, so that prefix is the default signal.
124 //
125 // Escape hatch for the one collision — a downstream crate
126 // legitimately named `teksilo-*` that depends on `teksilo`, not
127 // `teksilo-i18n`: set `TEKSILO_I18N_ROUTE=external` (or
128 // `=internal` to force the other way). Honoured first.
129 match std::env::var("TEKSILO_I18N_ROUTE").as_deref() {
130 Ok("external") => return quote!(::teksilo::i18n),
131 Ok("internal") => return quote!(::teksilo_i18n),
132 _ => {}
133 }
134 let pkg = std::env::var("CARGO_PKG_NAME").unwrap_or_default();
135 if pkg.starts_with("teksilo-") {
136 quote!(::teksilo_i18n)
137 } else {
138 quote!(::teksilo::i18n)
139 }
140 }
141 }
142 }
143
144 fn resolver_path(self) -> TokenStream2 {
145 let root = self.i18n_root();
146 match self {
147 SourceKind::App => quote!(#root::resolve_message),
148 SourceKind::Widget => quote!(#root::resolve_message_widget),
149 }
150 }
151}
152
153// ---------------------------------------------------------------------------
154// Parsed macro input
155// ---------------------------------------------------------------------------
156
157struct TrCall {
158 /// The path segments of the key, e.g. `auth::login_title` parses
159 /// as `[auth, login_title]`. A single-segment path remains the
160 /// common case; multi-segment paths organize related keys
161 /// hierarchically.
162 key_path: Vec<Ident>,
163 args: Vec<TrArg>,
164}
165
166impl TrCall {
167 /// The span of the entire key path — used for "missing key" and
168 /// "wrong argument" error reporting.
169 fn path_span(&self) -> proc_macro2::Span {
170 self.key_path
171 .first()
172 .map(|i| i.span())
173 .unwrap_or_else(proc_macro2::Span::call_site)
174 }
175}
176
177struct TrArg {
178 name: Ident,
179 value: Expr,
180}
181
182impl Parse for TrCall {
183 fn parse(input: ParseStream) -> Result<Self> {
184 // Parse `ident (:: ident)*` as the key path.
185 let mut key_path = vec![input.parse::<Ident>()?];
186 while input.peek(Token![::]) {
187 let _colons: Token![::] = input.parse()?;
188 key_path.push(input.parse::<Ident>()?);
189 }
190
191 let content;
192 syn::parenthesized!(content in input);
193
194 let args_punct: Punctuated<TrArg, Token![,]> = Punctuated::parse_terminated(&content)?;
195
196 Ok(TrCall {
197 key_path,
198 args: args_punct.into_iter().collect(),
199 })
200 }
201}
202
203impl Parse for TrArg {
204 fn parse(input: ParseStream) -> Result<Self> {
205 let name: Ident = input.parse()?;
206 let _eq: Token![=] = input.parse()?;
207 let value: Expr = input.parse()?;
208 Ok(TrArg { name, value })
209 }
210}
211
212// ---------------------------------------------------------------------------
213// Source-file location and parse cache
214// ---------------------------------------------------------------------------
215
216/// Where the macro reads its source-language messages from at expansion
217/// time. The two variants correspond to two supported layouts:
218/// a single flat `locales/en-US.ftl` file, or a `locales/en-US/`
219/// directory containing one or more `.ftl` files organized by feature.
220///
221/// Directory mode is enabled automatically if the default path
222/// `locales/en-US/` exists as a directory, or explicitly via the
223/// `TEKSILO_I18N_SOURCE_DIR` environment variable. Applications that
224/// already use the flat file layout are unaffected.
225#[derive(Clone, Debug)]
226enum SourceInfo {
227 File(PathBuf),
228 Dir(PathBuf),
229}
230
231impl SourceInfo {
232 fn display(&self) -> std::path::Display<'_> {
233 match self {
234 Self::File(p) | Self::Dir(p) => p.display(),
235 }
236 }
237}
238
239/// Resolve the `.ftl` source location for the crate currently being
240/// compiled. Precedence (highest first): `TEKSILO_I18N_SOURCE_DIR`,
241/// `TEKSILO_I18N_SOURCE_PATH`, auto-detect `locales/en-US/` directory,
242/// then fallback to the single `locales/en-US.ftl` file. The env vars
243/// let tests point the macro at a fixture without touching the
244/// consuming crate's layout (used by `tests/trybuild.rs`).
245fn resolve_source() -> std::result::Result<SourceInfo, String> {
246 let manifest = std::env::var("CARGO_MANIFEST_DIR")
247 .map_err(|_| "CARGO_MANIFEST_DIR is not set".to_string())?;
248 let manifest_path = PathBuf::from(&manifest);
249
250 if let Ok(dir_override) = std::env::var("TEKSILO_I18N_SOURCE_DIR") {
251 let p = PathBuf::from(&dir_override);
252 let resolved = if p.is_absolute() {
253 p
254 } else {
255 manifest_path.join(dir_override)
256 };
257 return Ok(SourceInfo::Dir(resolved));
258 }
259
260 if let Ok(file_override) = std::env::var("TEKSILO_I18N_SOURCE_PATH") {
261 let p = PathBuf::from(&file_override);
262 let resolved = if p.is_absolute() {
263 p
264 } else {
265 manifest_path.join(file_override)
266 };
267 return Ok(SourceInfo::File(resolved));
268 }
269
270 let dir_default = manifest_path.join("locales/en-US");
271 if dir_default.is_dir() {
272 return Ok(SourceInfo::Dir(dir_default));
273 }
274
275 Ok(SourceInfo::File(manifest_path.join("locales/en-US.ftl")))
276}
277
278/// Metadata about a single Fluent message.
279#[derive(Clone, Debug)]
280struct MessageInfo {
281 /// Variable names referenced by the message's pattern.
282 vars: Vec<String>,
283 /// Reconstructable source-language template for the macro's
284 /// compile-time fallback path — used when no `I18nManager` is
285 /// installed at runtime. `Some(parts)` for patterns composed
286 /// entirely of literal text and simple `{ $var }` substitutions;
287 /// `None` for patterns that use selectors, plural rules, function
288 /// calls, or message references (those need the real Fluent
289 /// formatter to produce meaningful output, so the macro formats
290 /// `source` with one at runtime instead).
291 fallback: Option<Vec<FallbackPart>>,
292 /// The message as Fluent source, alone, and the entries its value
293 /// refers to. A message with no `fallback` above is formatted from this
294 /// at runtime instead, in the source language, when no bundle answers.
295 source: EntrySource,
296}
297
298/// One entry of the source `.ftl`, re-serialized on its own, and the
299/// entries it refers to.
300#[derive(Clone, Debug)]
301struct EntrySource {
302 /// The entry as Fluent source, without its comment.
303 text: String,
304 /// The messages and terms its patterns refer to.
305 refs: Vec<EntryRef>,
306}
307
308/// A reference from one Fluent entry to another.
309#[derive(Clone, Debug, PartialEq, Eq, Hash)]
310enum EntryRef {
311 Message(String),
312 Term(String),
313}
314
315/// One piece of a reconstructable source-language fallback template.
316#[derive(Clone, Debug)]
317enum FallbackPart {
318 /// Verbatim literal text from a `TextElement` in the pattern.
319 Text(String),
320 /// A `{ $var }` substitution. The variable name matches one of
321 /// the arg names declared in `vars`, so the macro expansion
322 /// converts it to the captured Rust binding via `ToString`.
323 Var(String),
324}
325
326/// Parsed key map for one source (file or directory). Carries both the
327/// key → `MessageInfo` map and the list of files that contributed to
328/// it — the expansion emits one `include_bytes!` per file so cargo
329/// rebuilds the consuming crate when any of them change.
330#[derive(Clone, Debug)]
331struct KeyMap {
332 messages: HashMap<String, MessageInfo>,
333 /// Every term (`-brand = …`), for a message that refers to one.
334 terms: HashMap<String, EntrySource>,
335 /// Absolute paths of every `.ftl` file that contributed messages.
336 /// For file mode, a single entry. For directory mode, one entry
337 /// per file discovered during the walk.
338 watched_files: Vec<PathBuf>,
339}
340
341fn cache() -> &'static Mutex<HashMap<PathBuf, KeyMap>> {
342 static CACHE: OnceLock<Mutex<HashMap<PathBuf, KeyMap>>> = OnceLock::new();
343 CACHE.get_or_init(|| Mutex::new(HashMap::new()))
344}
345
346/// Dispatch loader used by the macro entry point.
347fn load_key_map_for_source(info: &SourceInfo) -> std::result::Result<KeyMap, String> {
348 match info {
349 SourceInfo::File(p) => load_key_map(p),
350 SourceInfo::Dir(p) => load_key_map_from_dir(p),
351 }
352}
353
354/// Parse one `.ftl` file's entries into `messages` and `watched_files`
355/// buffers. Shared by the single-file and directory-walk loaders.
356fn parse_ftl_file(
357 path: &std::path::Path,
358 messages: &mut HashMap<String, MessageInfo>,
359 terms: &mut HashMap<String, EntrySource>,
360 watched_files: &mut Vec<PathBuf>,
361) -> std::result::Result<(), String> {
362 let contents = std::fs::read_to_string(path)
363 .map_err(|e| format!("cannot read `{}`: {e}", path.display()))?;
364
365 let resource = parse(contents.as_str())
366 .map_err(|(_, errs)| format!("Fluent parse errors in `{}`: {:?}", path.display(), errs))?;
367
368 for entry in &resource.body {
369 if let ast::Entry::Term(term) = entry {
370 let id = term.id.name.to_string();
371 let mut refs = Vec::new();
372 collect_refs_pattern(&term.value, &mut refs);
373 for attribute in &term.attributes {
374 collect_refs_pattern(&attribute.value, &mut refs);
375 }
376 let mut alone = term.clone();
377 alone.comment = None;
378 terms.entry(id).or_insert(EntrySource {
379 text: serialize_entry(ast::Entry::Term(alone)),
380 refs,
381 });
382 }
383 if let ast::Entry::Message(msg) = entry {
384 let id = msg.id.name.to_string();
385 // Single walk of the pattern: `build_fallback` already
386 // descends every element and branch, so we piggy-back a
387 // var-collection side effect onto it rather than running
388 // a second full walk via `collect_variables`. For
389 // patterns that bail out of fallback (selectors, plural
390 // rules, term/message refs) we do still need to enumerate
391 // `$var`s, so the walker continues through those paths
392 // and only reports `fallback = None` at the end.
393 let mut vars_buf: Vec<String> = Vec::new();
394 let fallback = if let Some(pattern) = &msg.value {
395 build_fallback_and_collect_vars(pattern, &mut vars_buf)
396 } else {
397 None
398 };
399 // Dedupe while preserving first-seen order.
400 let mut seen = std::collections::HashSet::new();
401 vars_buf.retain(|v| seen.insert(v.clone()));
402 if messages.contains_key(&id) {
403 return Err(format!(
404 "duplicate message key `{id}` (second definition in `{}`)",
405 path.display()
406 ));
407 }
408 let mut refs = Vec::new();
409 if let Some(pattern) = &msg.value {
410 collect_refs_pattern(pattern, &mut refs);
411 }
412 for attribute in &msg.attributes {
413 collect_refs_pattern(&attribute.value, &mut refs);
414 }
415 let mut alone = msg.clone();
416 alone.comment = None;
417 messages.insert(
418 id,
419 MessageInfo {
420 vars: vars_buf,
421 fallback,
422 source: EntrySource {
423 text: serialize_entry(ast::Entry::Message(alone)),
424 refs,
425 },
426 },
427 );
428 }
429 }
430
431 watched_files.push(path.to_path_buf());
432 Ok(())
433}
434
435/// Load-and-parse a single `.ftl` file into a `KeyMap`, or read the
436/// cached copy.
437fn load_key_map(path: &std::path::Path) -> std::result::Result<KeyMap, String> {
438 if let Ok(guard) = cache().lock()
439 && let Some(existing) = guard.get(path)
440 {
441 return Ok(existing.clone());
442 }
443
444 let mut messages: HashMap<String, MessageInfo> = HashMap::new();
445 let mut terms: HashMap<String, EntrySource> = HashMap::new();
446 let mut watched_files: Vec<PathBuf> = Vec::new();
447 parse_ftl_file(path, &mut messages, &mut terms, &mut watched_files)?;
448
449 let map = KeyMap {
450 messages,
451 terms,
452 watched_files,
453 };
454 if let Ok(mut guard) = cache().lock() {
455 guard.insert(path.to_path_buf(), map.clone());
456 }
457 Ok(map)
458}
459
460/// Walk a `locales/en-US/` directory recursively, parse every `.ftl`
461/// file, and merge their messages into a single flat `KeyMap`. The
462/// order of files is deterministic (sorted by relative path) so that
463/// the error reported on duplicate keys is stable. Architecture
464/// The directory layout is an organizational convention;
465/// every key across every file is visible through a single flat
466/// lookup. Applications prevent collisions by prefixing keys (e.g.,
467/// `auth-login-title = Log in` in `auth.ftl`), and the macro's
468/// `tr!(auth::login_title())` syntax targets the same flat key via
469/// `path_to_fluent_key`.
470fn load_key_map_from_dir(root: &std::path::Path) -> std::result::Result<KeyMap, String> {
471 if let Ok(guard) = cache().lock()
472 && let Some(existing) = guard.get(root)
473 {
474 return Ok(existing.clone());
475 }
476
477 if !root.is_dir() {
478 return Err(format!(
479 "`{}` is not a directory (directory mode was requested)",
480 root.display()
481 ));
482 }
483
484 let mut ftl_files: Vec<PathBuf> = Vec::new();
485 collect_ftl_files(root, &mut ftl_files)
486 .map_err(|e| format!("failed to walk `{}`: {e}", root.display()))?;
487 ftl_files.sort();
488
489 if ftl_files.is_empty() {
490 return Err(format!("no `.ftl` files found under `{}`", root.display()));
491 }
492
493 let mut messages: HashMap<String, MessageInfo> = HashMap::new();
494 let mut terms: HashMap<String, EntrySource> = HashMap::new();
495 let mut watched_files: Vec<PathBuf> = Vec::new();
496 for file in &ftl_files {
497 parse_ftl_file(file, &mut messages, &mut terms, &mut watched_files)?;
498 }
499
500 let map = KeyMap {
501 messages,
502 terms,
503 watched_files,
504 };
505 if let Ok(mut guard) = cache().lock() {
506 guard.insert(root.to_path_buf(), map.clone());
507 }
508 Ok(map)
509}
510
511/// Recursively collect every `.ftl` file under `dir`.
512fn collect_ftl_files(dir: &std::path::Path, out: &mut Vec<PathBuf>) -> std::io::Result<()> {
513 for entry in std::fs::read_dir(dir)? {
514 let entry = entry?;
515 let path = entry.path();
516 let file_type = entry.file_type()?;
517 if file_type.is_dir() {
518 collect_ftl_files(&path, out)?;
519 } else if file_type.is_file() && path.extension().and_then(|e| e.to_str()) == Some("ftl") {
520 out.push(path);
521 }
522 }
523 Ok(())
524}
525
526/// Walk a Fluent pattern once, building the fallback template and
527/// collecting every `$var` reference in a single pass. Returns
528/// `Some(parts)` iff the pattern is composed entirely of literal text
529/// and simple `{ $var }` references (safe to reassemble without a
530/// Fluent formatter); otherwise returns `None` to disable the
531/// fallback, but still pushes any discovered variable references to
532/// `vars_out` so that argument validation has complete information.
533///
534/// Patterns that disable fallback include: selectors, plural rules,
535/// function calls, message/term references, and nested placeables.
536/// Argument-validation only cares about the set of `$var`s, which
537/// this walker collects from every branch of every select.
538fn build_fallback_and_collect_vars(
539 pattern: &ast::Pattern<&str>,
540 vars_out: &mut Vec<String>,
541) -> Option<Vec<FallbackPart>> {
542 let mut parts: Vec<FallbackPart> = Vec::new();
543 let mut fallback_ok = true;
544 for element in &pattern.elements {
545 match element {
546 ast::PatternElement::TextElement { value } => {
547 if fallback_ok {
548 parts.push(FallbackPart::Text((*value).to_string()));
549 }
550 }
551 ast::PatternElement::Placeable { expression } => {
552 let simple_var = match expression {
553 ast::Expression::Inline(ast::InlineExpression::VariableReference { id }) => {
554 Some(id.name.to_string())
555 }
556 _ => None,
557 };
558 if let Some(var) = simple_var {
559 vars_out.push(var.clone());
560 if fallback_ok {
561 parts.push(FallbackPart::Var(var));
562 }
563 } else {
564 // Non-trivial placeable: disable fallback, but
565 // continue walking to collect any `$var`s inside
566 // selectors/function calls/etc. so the arg
567 // validator has the full set.
568 fallback_ok = false;
569 walk_expr_for_vars(expression, vars_out);
570 }
571 }
572 }
573 }
574 if fallback_ok { Some(parts) } else { None }
575}
576
577fn walk_expr_for_vars(expr: &ast::Expression<&str>, out: &mut Vec<String>) {
578 match expr {
579 ast::Expression::Inline(inline) => walk_inline_for_vars(inline, out),
580 ast::Expression::Select { selector, variants } => {
581 walk_inline_for_vars(selector, out);
582 for variant in variants {
583 // Recurse into each variant's pattern; we discard the
584 // returned `Option<Vec<FallbackPart>>` because the
585 // outer walk has already marked fallback disabled.
586 let _ = build_fallback_and_collect_vars(&variant.value, out);
587 }
588 }
589 }
590}
591
592fn walk_inline_for_vars(inline: &ast::InlineExpression<&str>, out: &mut Vec<String>) {
593 match inline {
594 ast::InlineExpression::VariableReference { id } => {
595 out.push(id.name.to_string());
596 }
597 ast::InlineExpression::Placeable { expression } => {
598 walk_expr_for_vars(expression, out);
599 }
600 ast::InlineExpression::FunctionReference { arguments, .. } => {
601 for positional in &arguments.positional {
602 walk_inline_for_vars(positional, out);
603 }
604 for named in &arguments.named {
605 walk_inline_for_vars(&named.value, out);
606 }
607 }
608 ast::InlineExpression::MessageReference { .. }
609 | ast::InlineExpression::TermReference { .. }
610 | ast::InlineExpression::StringLiteral { .. }
611 | ast::InlineExpression::NumberLiteral { .. } => {}
612 }
613}
614
615/// One entry as a Fluent resource of its own.
616fn serialize_entry(entry: ast::Entry<&str>) -> String {
617 fluent_syntax::serializer::serialize(&ast::Resource { body: vec![entry] })
618}
619
620/// Every message and term `pattern` refers to, in every branch of every
621/// select.
622fn collect_refs_pattern(pattern: &ast::Pattern<&str>, out: &mut Vec<EntryRef>) {
623 for element in &pattern.elements {
624 if let ast::PatternElement::Placeable { expression } = element {
625 collect_refs_expr(expression, out);
626 }
627 }
628}
629
630fn collect_refs_expr(expr: &ast::Expression<&str>, out: &mut Vec<EntryRef>) {
631 match expr {
632 ast::Expression::Inline(inline) => collect_refs_inline(inline, out),
633 ast::Expression::Select { selector, variants } => {
634 collect_refs_inline(selector, out);
635 for variant in variants {
636 collect_refs_pattern(&variant.value, out);
637 }
638 }
639 }
640}
641
642fn collect_refs_inline(inline: &ast::InlineExpression<&str>, out: &mut Vec<EntryRef>) {
643 let arguments = match inline {
644 ast::InlineExpression::MessageReference { id, .. } => {
645 out.push(EntryRef::Message(id.name.to_string()));
646 None
647 }
648 ast::InlineExpression::TermReference { id, arguments, .. } => {
649 out.push(EntryRef::Term(id.name.to_string()));
650 arguments.as_ref()
651 }
652 ast::InlineExpression::FunctionReference { arguments, .. } => Some(arguments),
653 ast::InlineExpression::Placeable { expression } => {
654 collect_refs_expr(expression, out);
655 None
656 }
657 ast::InlineExpression::VariableReference { .. }
658 | ast::InlineExpression::StringLiteral { .. }
659 | ast::InlineExpression::NumberLiteral { .. } => None,
660 };
661 if let Some(arguments) = arguments {
662 for positional in &arguments.positional {
663 collect_refs_inline(positional, out);
664 }
665 for named in &arguments.named {
666 collect_refs_inline(&named.value, out);
667 }
668 }
669}
670
671/// The Fluent source a bundle needs to format `key` on its own: the message,
672/// then every message and term it reaches through references, once each.
673fn standalone_source(key_map: &KeyMap, key: &str) -> String {
674 let mut text = String::new();
675 let mut seen: std::collections::HashSet<EntryRef> = std::collections::HashSet::new();
676 let mut pending = vec![EntryRef::Message(key.to_string())];
677 while let Some(entry) = pending.pop() {
678 if !seen.insert(entry.clone()) {
679 continue;
680 }
681 let source = match &entry {
682 EntryRef::Message(id) => key_map.messages.get(id).map(|info| &info.source),
683 EntryRef::Term(id) => key_map.terms.get(id),
684 };
685 // A reference to an entry the source does not define is left for
686 // the bundle to report, as it would be with the whole file loaded.
687 if let Some(source) = source {
688 text.push_str(&source.text);
689 pending.extend(source.refs.iter().rev().cloned());
690 }
691 }
692 text
693}
694
695/// The language the source messages are written in, read from the source's
696/// own name (`locales/en-US.ftl`, `locales/en-US/`). The runtime falls back to
697/// `en-US` for a name that is not a language tag.
698fn source_language(info: &SourceInfo) -> String {
699 let path = match info {
700 SourceInfo::File(p) => p.file_stem(),
701 SourceInfo::Dir(p) => p.file_name(),
702 };
703 path.and_then(|name| name.to_str())
704 .unwrap_or("en-US")
705 .to_string()
706}
707
708// ---------------------------------------------------------------------------
709// Name conversion + suggestion helpers
710// ---------------------------------------------------------------------------
711
712/// Convert a Rust path like `auth::login_title` into the Fluent key
713/// `auth__login-title`.
714///
715/// Two separators at play:
716/// - `_` (single underscore) **inside** a segment is converted to
717/// `-` — matching the long-standing flat-mode rule
718/// (`foo_bar` → `foo-bar`).
719/// - `__` (double underscore) is reserved as the **nested module**
720/// separator, emitted at every `::` boundary between segments.
721///
722/// Because `_` → `-` and `__` never occurs inside a normalized
723/// segment, the mapping is injective: distinct Rust paths always
724/// produce distinct Fluent keys. Callers that *write* `__` directly
725/// inside a segment (e.g., `tr!(foo__bar())`) get a compile-time
726/// error pointing at the offending segment — the rule is
727/// "single underscores inside, `::` between."
728///
729/// Examples:
730/// | Rust path | Fluent key |
731/// |----------------------------------------|----------------------------------------|
732/// | `greeting` | `greeting` |
733/// | `foo_bar` | `foo-bar` |
734/// | `auth::login` | `auth__login` |
735/// | `auth::login_title` | `auth__login-title` |
736/// | `auth_login::title` | `auth-login__title` |
737/// | `auth::login::title` | `auth__login__title` |
738/// | `settings::display::resolution_label` | `settings__display__resolution-label` |
739fn path_to_fluent_key(segments: &[Ident]) -> std::result::Result<String, syn::Error> {
740 let mut normalized: Vec<String> = Vec::with_capacity(segments.len());
741 for seg in segments {
742 let s = seg.to_string();
743 if s.contains("__") {
744 return Err(syn::Error::new(
745 seg.span(),
746 format!(
747 "teksilo-i18n: path segment `{s}` contains `__`, \
748 which is reserved as the nested-module separator. \
749 Use `::` for nesting, or single `_` within a segment."
750 ),
751 ));
752 }
753 // Fluent message-id grammar is `[a-zA-Z][a-zA-Z0-9_-]*`. Rust
754 // allows Unicode identifiers (e.g., `tr!(héllo())`), which
755 // would silently produce a non-Fluent-id string that would
756 // fail lookup with a confusing "key not found" error instead
757 // of pointing at the real cause. Reject non-ASCII segments
758 // upfront with a clearer message.
759 let mut chars = s.chars();
760 let first = chars.next().expect("syn::Ident is non-empty");
761 let first_ok = first.is_ascii_alphabetic();
762 let rest_ok = chars.all(|c| c.is_ascii_alphanumeric() || c == '_');
763 if !first_ok || !rest_ok {
764 return Err(syn::Error::new(
765 seg.span(),
766 format!(
767 "teksilo-i18n: path segment `{s}` is not a valid Fluent \
768 message id — must match `[a-zA-Z][a-zA-Z0-9_]*` (ASCII \
769 letters, digits, and underscores only)."
770 ),
771 ));
772 }
773 normalized.push(s.replace('_', "-"));
774 }
775 Ok(normalized.join("__"))
776}
777
778/// Find the closest matching key in `candidates` for a user-supplied
779/// query, using a cheap Levenshtein-style score. Returns `None` if no
780/// candidate is within a small edit budget.
781fn suggest_key<'a>(query: &str, candidates: impl Iterator<Item = &'a String>) -> Option<String> {
782 let mut best: Option<(usize, &String)> = None;
783 for cand in candidates {
784 let d = levenshtein(query, cand);
785 if d < best.map(|(bd, _)| bd).unwrap_or(usize::MAX) {
786 best = Some((d, cand));
787 }
788 }
789 best.and_then(|(d, s)| if d <= 3 { Some(s.clone()) } else { None })
790}
791
792fn levenshtein(a: &str, b: &str) -> usize {
793 let a: Vec<char> = a.chars().collect();
794 let b: Vec<char> = b.chars().collect();
795 let (m, n) = (a.len(), b.len());
796 if m == 0 {
797 return n;
798 }
799 if n == 0 {
800 return m;
801 }
802 let mut prev: Vec<usize> = (0..=n).collect();
803 let mut curr = vec![0usize; n + 1];
804 for i in 1..=m {
805 curr[0] = i;
806 for j in 1..=n {
807 let cost = if a[i - 1] == b[j - 1] { 0 } else { 1 };
808 curr[j] = (curr[j - 1] + 1).min(prev[j] + 1).min(prev[j - 1] + cost);
809 }
810 std::mem::swap(&mut prev, &mut curr);
811 }
812 prev[n]
813}
814
815// ---------------------------------------------------------------------------
816// Core expansion
817// ---------------------------------------------------------------------------
818
819fn tr_impl(input: TokenStream, kind: SourceKind, signal: bool) -> TokenStream {
820 let call = parse_macro_input!(input as TrCall);
821
822 let source_info = match resolve_source() {
823 Ok(info) => info,
824 Err(msg) => {
825 return syn::Error::new(call.path_span(), msg)
826 .to_compile_error()
827 .into();
828 }
829 };
830
831 let key_map = match load_key_map_for_source(&source_info) {
832 Ok(m) => m,
833 Err(msg) => {
834 return syn::Error::new(
835 call.path_span(),
836 format!(
837 "teksilo-i18n: failed to load source `{}`: {msg}",
838 source_info.display()
839 ),
840 )
841 .to_compile_error()
842 .into();
843 }
844 };
845
846 let fluent_key = match path_to_fluent_key(&call.key_path) {
847 Ok(k) => k,
848 Err(e) => return e.to_compile_error().into(),
849 };
850
851 // 1. Validate key existence.
852 let (expected_args, fallback_parts): (Vec<String>, Option<Vec<FallbackPart>>) =
853 match key_map.messages.get(&fluent_key) {
854 Some(info) => (info.vars.clone(), info.fallback.clone()),
855 None => {
856 let mut msg = format!(
857 "teksilo-i18n: translation key `{}` not found in `{}`",
858 fluent_key,
859 source_info.display()
860 );
861 if let Some(suggestion) = suggest_key(&fluent_key, key_map.messages.keys()) {
862 msg.push_str(&format!(" (did you mean `{suggestion}`?)"));
863 }
864 return syn::Error::new(call.path_span(), msg)
865 .to_compile_error()
866 .into();
867 }
868 };
869
870 // 2. Validate argument names.
871 let provided_names: Vec<String> = call.args.iter().map(|a| a.name.to_string()).collect();
872
873 for expected in &expected_args {
874 if !provided_names.iter().any(|p| p == expected) {
875 return syn::Error::new(
876 call.path_span(),
877 format!("teksilo-i18n: missing argument `{expected}` for key `{fluent_key}`"),
878 )
879 .to_compile_error()
880 .into();
881 }
882 }
883 for arg in &call.args {
884 let name = arg.name.to_string();
885 if !expected_args.iter().any(|e| e == &name) {
886 return syn::Error::new(
887 arg.name.span(),
888 format!(
889 "teksilo-i18n: unknown argument `{name}` for key `{fluent_key}` (expected: {})",
890 if expected_args.is_empty() {
891 "no arguments".to_string()
892 } else {
893 expected_args.join(", ")
894 }
895 ),
896 )
897 .to_compile_error()
898 .into();
899 }
900 }
901
902 // 3. Emit the expansion.
903 let i18n_root = kind.i18n_root();
904 let resolver = kind.resolver_path();
905 let key_lit = proc_macro2::Literal::string(&fluent_key);
906 // One tracked `include_bytes!` per `.ftl` file that contributed to
907 // the key map. In file mode there's a single entry; in directory
908 // mode the list covers every file walked. `const _: &[u8] = ...`
909 // with anonymous names means multiple tracking consts coexist in
910 // the same expansion block without name conflicts.
911 let watch_stmts: Vec<TokenStream2> = key_map
912 .watched_files
913 .iter()
914 .map(|p| {
915 let lit = proc_macro2::Literal::string(&p.to_string_lossy());
916 quote! {
917 const _: &[u8] = ::core::include_bytes!(#lit);
918 }
919 })
920 .collect();
921
922 // Per-arg let bindings. In `tr!` mode the let stores the expression
923 // by-value (consistent with the historical behaviour). In
924 // `tr_signal!` mode we wrap with `.clone()` so the caller's `Signal`
925 // handle survives — `(expr).clone()` is method-call syntax that
926 // auto-refs, so a bare ident remains borrowed instead of moved.
927 let mut arg_let_bindings: Vec<TokenStream2> = Vec::new();
928 let mut arg_slice_entries_static: Vec<TokenStream2> = Vec::new();
929 let mut arg_slice_entries_signal: Vec<TokenStream2> = Vec::new();
930 let mut arg_idents: Vec<Ident> = Vec::new();
931 for arg in &call.args {
932 let binding_ident = &arg.name;
933 let value_expr = &arg.value;
934 let name_lit = proc_macro2::Literal::string(&arg.name.to_string());
935 let binding = if signal {
936 quote_spanned! { value_expr.span() =>
937 let #binding_ident = (#value_expr).clone();
938 }
939 } else {
940 quote_spanned! { value_expr.span() =>
941 let #binding_ident = { #value_expr };
942 }
943 };
944 arg_let_bindings.push(binding);
945 arg_slice_entries_static.push(quote! {
946 (#name_lit, #i18n_root::FluentValue::from(#binding_ident.clone()))
947 });
948 arg_slice_entries_signal.push(quote! {
949 (#name_lit, #i18n_root::FluentValue::from(#binding_ident.get()))
950 });
951 arg_idents.push(binding_ident.clone());
952 }
953
954 // Fallback handling: when the macro expansion runs without an
955 // installed i18n manager (or the active locale's bundle lacks the
956 // key), the runtime resolver returns the literal key as a
957 // placeholder. For simple patterns — literal text with optional
958 // `{ $var }` substitutions — the macro reconstructs the source
959 // language text from the pre-parsed `FallbackPart` list, pulling
960 // each variable's value from the closure's captured bindings via
961 // `ToString`. In `tr_signal!` mode the captured bindings are
962 // `Signal<T>` so we read `.get()` first; in `tr!` mode we use the
963 // value directly. Patterns that use selectors, plural rules,
964 // function calls, or message references bail out at parse time
965 // and are formatted from their own source instead (see the `None`
966 // arm below).
967 let arg_slice_entries: &[TokenStream2] = if signal {
968 &arg_slice_entries_signal
969 } else {
970 &arg_slice_entries_static
971 };
972
973 let fallback_body = match fallback_parts {
974 Some(parts) => {
975 let mut fallback_stmts: Vec<TokenStream2> = Vec::new();
976 for part in parts {
977 match part {
978 FallbackPart::Text(text) => {
979 let lit = proc_macro2::Literal::string(&text);
980 fallback_stmts.push(quote! {
981 __teksilo_fallback.push_str(#lit);
982 });
983 }
984 FallbackPart::Var(var_name) => {
985 let ident =
986 proc_macro2::Ident::new(&var_name, proc_macro2::Span::call_site());
987 let value_expr = if signal {
988 quote! { &#ident.get() }
989 } else {
990 quote! { &#ident }
991 };
992 fallback_stmts.push(quote! {
993 __teksilo_fallback.push_str(
994 &::std::string::ToString::to_string(#value_expr),
995 );
996 });
997 }
998 }
999 }
1000 quote! {
1001 let __teksilo_result =
1002 #resolver(#key_lit, &[#(#arg_slice_entries),*]);
1003 if __teksilo_result == #key_lit {
1004 let mut __teksilo_fallback = ::std::string::String::new();
1005 #(#fallback_stmts)*
1006 __teksilo_fallback
1007 } else {
1008 __teksilo_result
1009 }
1010 }
1011 }
1012 // A selector, a plural, a function call or a reference cannot be put
1013 // back together here, so the message's own source goes into the
1014 // expansion instead, with the entries it refers to, and a bundle in
1015 // the source language formats it at runtime. Returning the key, as
1016 // this used to, gave a screen reader "grid-view-selection-count" to
1017 // say in place of "1 item selected".
1018 None => {
1019 let source_lit =
1020 proc_macro2::Literal::string(&standalone_source(&key_map, &fluent_key));
1021 let language_lit = proc_macro2::Literal::string(&source_language(&source_info));
1022 quote! {
1023 let __teksilo_result =
1024 #resolver(#key_lit, &[#(#arg_slice_entries),*]);
1025 if __teksilo_result == #key_lit {
1026 #i18n_root::format_source_fallback(
1027 #language_lit,
1028 #source_lit,
1029 #key_lit,
1030 &[#(#arg_slice_entries),*],
1031 )
1032 } else {
1033 __teksilo_result
1034 }
1035 }
1036 }
1037 };
1038
1039 let expanded = if signal {
1040 // Reactive lowering: `Signal<String>` subscribed to every arg
1041 // signal plus the version signal. Re-runs the resolver via a
1042 // shared `Rc<dyn Fn>` whenever any dependency fires.
1043 let arg_subscribes: Vec<TokenStream2> = arg_idents
1044 .iter()
1045 .map(|ident| {
1046 quote! {
1047 {
1048 let __teksilo_resolver_arg = ::std::rc::Rc::clone(&__teksilo_resolver);
1049 let __teksilo_weak_arg = __teksilo_weak.clone();
1050 let __teksilo_h = #ident.observe(move |_| {
1051 if let Some(__t) = __teksilo_weak_arg.upgrade() {
1052 __t.set((__teksilo_resolver_arg)());
1053 }
1054 });
1055 __teksilo_out.attach_keepalive(__teksilo_h);
1056 }
1057 }
1058 })
1059 .collect();
1060
1061 // Each arg signal is captured by clone into the resolver
1062 // closure so the closure can be cloned into N+1 observers.
1063 let arg_clones_for_resolver: Vec<TokenStream2> = arg_idents
1064 .iter()
1065 .map(|ident| quote! { let #ident = #ident.clone(); })
1066 .collect();
1067
1068 quote! {
1069 {
1070 #(#watch_stmts)*
1071
1072 // `observe`, `attach_keepalive` and `downgrade` are
1073 // inherent methods on `Signal`, so the expansion needs
1074 // no `use` import for them.
1075 #(#arg_let_bindings)*
1076
1077 let __teksilo_resolver: ::std::rc::Rc<dyn ::std::ops::Fn() -> ::std::string::String> = {
1078 #(#arg_clones_for_resolver)*
1079 ::std::rc::Rc::new(move || {
1080 #fallback_body
1081 })
1082 };
1083
1084 let __teksilo_out = #i18n_root::Signal::new((__teksilo_resolver)());
1085 let __teksilo_weak = __teksilo_out
1086 .downgrade()
1087 .expect("Signal::new returns mutable; downgrade cannot fail");
1088
1089 if let Some(__teksilo_ver) = #i18n_root::current_version_signal() {
1090 let __teksilo_resolver_ver = ::std::rc::Rc::clone(&__teksilo_resolver);
1091 let __teksilo_weak_ver = __teksilo_weak.clone();
1092 let __teksilo_handle_ver = __teksilo_ver.observe(move |_| {
1093 if let Some(__t) = __teksilo_weak_ver.upgrade() {
1094 __t.set((__teksilo_resolver_ver)());
1095 }
1096 });
1097 __teksilo_out.attach_keepalive(__teksilo_handle_ver);
1098 }
1099
1100 #(#arg_subscribes)*
1101
1102 __teksilo_out
1103 }
1104 }
1105 } else {
1106 quote! {
1107 {
1108 // Force cargo to track every source `.ftl` file that
1109 // contributed to the key map. `include_bytes!` is a
1110 // compiler builtin that registers the path as a build
1111 // dependency — when any file changes, cargo rebuilds the
1112 // containing crate. The constants are discarded.
1113 #(#watch_stmts)*
1114
1115 #i18n_root::localized({
1116 #(#arg_let_bindings)*
1117 move || {
1118 #fallback_body
1119 }
1120 })
1121 }
1122 }
1123 };
1124
1125 expanded.into()
1126}