init

1 files changed, 133 insertions, 0 deletions

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.