Skip to main content

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}