From c38d117b5803c65ad57a4c4704ee0d897d9fb3cb Mon Sep 17 00:00:00 2001 From: copi143 Date: Sat, 17 Jan 2026 04:02:47 +0800 Subject: init --- derive/README.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 derive/README.md (limited to 'derive/README.md') diff --git a/derive/README.md b/derive/README.md new file mode 100644 index 0000000..dc2709d --- /dev/null +++ b/derive/README.md @@ -0,0 +1,133 @@ +# static-l10n + +Procedural macros for `static-l10n`. + +## Macros + +- `main!()` initializes the language state with the default language. +- `lang!("xx")` switches the current language. +- `l10n!("key")` returns a localized string for `key`. +- `f16n!("fmt: {}", arg)` returns a localized formatted string. +- `l10n_print!("key")` prints a localized string. +- `l10n_println!("key")` prints a localized string with newline. +- `l10n_eprint!("key")` prints a localized string to stderr. +- `l10n_eprintln!("key")` prints a localized string to stderr with newline. +- `l10n_write!(writer, "key")` writes a localized string to a writer. +- `l10n_writeln!(writer, "key")` writes a localized string to a writer with newline. +- `l10n_panic!("key")` panics with a localized string. +- `l10n_args!("key")` returns `std::fmt::Arguments` for formatting APIs. +- `l10n_assert!(cond, "key")` asserts a condition with a localized message. +- `l10n_assert_eq!(left, right, "key")` asserts equality with a localized message. +- `l10n_assert_ne!(left, right, "key")` asserts inequality with a localized message. +- `l10n_debug_assert!(cond, "key")` debug-asserts a condition with a localized message. +- `l10n_debug_assert_eq!(left, right, "key")` debug-asserts equality with a localized message. +- `l10n_debug_assert_ne!(left, right, "key")` debug-asserts inequality with a localized message. +- `f16n_print!("fmt: {}", arg)` prints a localized formatted string. +- `f16n_println!("fmt: {}", arg)` prints a localized formatted string with newline. +- `f16n_eprint!("fmt: {}", arg)` prints a localized formatted string to stderr. +- `f16n_eprintln!("fmt: {}", arg)` prints a localized formatted string to stderr with newline. +- `f16n_write!(writer, "fmt: {}", arg)` writes a localized formatted string to a writer. +- `f16n_writeln!(writer, "fmt: {}", arg)` writes a localized formatted string to a writer with newline. +- `f16n_panic!("fmt: {}", arg)` panics with a localized formatted string. +- `f16n_args!("fmt: {}", arg)` returns `std::fmt::Arguments` for formatting APIs. +- `f16n_assert!(cond, "fmt: {}", arg)` asserts a condition with a localized formatted message. +- `f16n_assert_eq!(left, right, "fmt: {}", arg)` asserts equality with a localized formatted message. +- `f16n_assert_ne!(left, right, "fmt: {}", arg)` asserts inequality with a localized formatted message. +- `f16n_debug_assert!(cond, "fmt: {}", arg)` debug-asserts a condition with a localized formatted message. +- `f16n_debug_assert_eq!(left, right, "fmt: {}", arg)` debug-asserts equality with a localized formatted message. +- `f16n_debug_assert_ne!(left, right, "fmt: {}", arg)` debug-asserts inequality with a localized formatted message. +- `debug_print_metadata!()` prints resolved metadata and loaded translations at compile time. + +## Usage + +Add metadata to your crate `Cargo.toml` (this is read at compile time): + +```toml +[package.metadata.static-l10n] +path = "i18n" +base = "en" +langs = ["en", { name = "zh", fallback = "en" }] +``` + +Create translation files under the `path` directory. Each file is TOML and can contain multiple keys: + +```toml +["Hello, world!"] +en = "Hello, world!" +zh = "你好，世界！" + +["Hello, {}!"] +en = "Hello, {}!" +zh = "你好，{}！" +``` + +You can split keys across multiple files and nested folders under `path`. Duplicate keys for the same language will cause a compile-time panic. + +Then use the macros in your crate: + +```rust +static_l10n::main!(); + +static_l10n::lang!("zh"); +let msg = static_l10n::l10n!("hello"); +let formatted = static_l10n::f16n!("count: {}", 3); +static_l10n::l10n_println!("hello"); +static_l10n::f16n_println!("count: {}", 3); +``` + +## How It Works + +- `main!()` defines a global mutex holding the current language. Call it once at crate root. +- `lang!("xx")` switches the current language for subsequent lookups. +- `l10n!` looks up a string key and returns a `&'static str` literal from the translations table. +- `f16n!` looks up a format string and returns a `String` built with `format!`. +- `*_args!` returns `std::fmt::Arguments` for zero-allocation formatting (use with `write!`, `format!`, etc.). + +## Common Patterns + +Print to stdout or stderr: + +```rust +static_l10n::l10n_print!("Hello, world!"); +static_l10n::l10n_eprintln!("Hello, world!"); +static_l10n::f16n_println!("Hello, {}!", "Rust"); +``` + +Write into a buffer or writer: + +```rust +let mut buf = String::new(); +static_l10n::l10n_write!(&mut buf, "Hello, world!"); +static_l10n::f16n_writeln!(&mut buf, "Hello, {}!", "Rust"); +``` + +Use `*_args!` with formatting APIs: + +```rust +use std::fmt::Write; + +let mut buf = String::new(); +let args = static_l10n::f16n_args!("Hello, {}!", "Rust"); +let _ = write!(&mut buf, "{}", args); +``` + +Localized assertions: + +```rust +static_l10n::l10n_assert!(1 + 1 == 2, "Hello, world!"); +static_l10n::f16n_assert_eq!(2 + 2, 4, "Hello, {}!", "Rust"); +static_l10n::l10n_debug_assert_ne!(3, 4, "Hello, world!"); +``` + +Localized panic: + +```rust +static_l10n::l10n_panic!("Hello, world!"); +static_l10n::f16n_panic!("Hello, {}!", "Rust"); +``` + +## Notes + +- All translations are loaded at compile time from `path`. +- Missing keys per language produce a compile-time error. +- `debug_print_metadata!()` can help inspect loaded metadata and translations during compilation. -- cgit