mirror of
https://github.com/Start9Labs/start-os.git
synced 2026-03-26 10:21:52 +00:00
f2142f0bb3
* add documentation for ai agents * docs: consolidate CLAUDE.md and CONTRIBUTING.md, add style guidelines - Refactor CLAUDE.md to reference CONTRIBUTING.md for build/test/format info - Expand CONTRIBUTING.md with comprehensive build targets, env vars, and testing - Add code style guidelines section with conventional commits - Standardize SDK prettier config to use single quotes (matching web) - Add project-level Claude Code settings to disable co-author attribution * style(sdk): apply prettier with single quotes Run prettier across sdk/base and sdk/package to apply the standardized quote style (single quotes matching web). * docs: add USER.md for per-developer TODO filtering - Add agents/USER.md to .gitignore (contains user identifier) - Document session startup flow in CLAUDE.md: - Create USER.md if missing, prompting for identifier - Filter TODOs by @username tags - Offer relevant TODOs on session start * docs: add i18n documentation task to agent TODOs * docs: document i18n ID patterns in core/ Add agents/i18n-patterns.md covering rust-i18n setup, translation file format, t!() macro usage, key naming conventions, and locale selection. Remove completed TODO item and add reference in CLAUDE.md. * chore: clarify that all builds work on any OS with Docker
101 lines
3.1 KiB
Markdown
101 lines
3.1 KiB
Markdown
# i18n Patterns in `core/`
|
|
|
|
## Library & Setup
|
|
|
|
**Crate:** [`rust-i18n`](https://crates.io/crates/rust-i18n) v3.1.5 (`core/Cargo.toml`)
|
|
|
|
**Initialization** (`core/src/lib.rs:3`):
|
|
```rust
|
|
rust_i18n::i18n!("locales", fallback = ["en_US"]);
|
|
```
|
|
This macro scans `core/locales/` at compile time and embeds all translations as constants.
|
|
|
|
**Prelude re-export** (`core/src/prelude.rs:4`):
|
|
```rust
|
|
pub use rust_i18n::t;
|
|
```
|
|
Most modules import `t!` via the prelude.
|
|
|
|
## Translation File
|
|
|
|
**Location:** `core/locales/i18n.yaml`
|
|
**Format:** YAML v2 (~755 keys)
|
|
|
|
**Supported languages:** `en_US`, `de_DE`, `es_ES`, `fr_FR`, `pl_PL`
|
|
|
|
**Entry structure:**
|
|
```yaml
|
|
namespace.sub.key-name:
|
|
en_US: "English text with %{param}"
|
|
de_DE: "German text with %{param}"
|
|
# ...
|
|
```
|
|
|
|
## Using `t!()`
|
|
|
|
```rust
|
|
// Simple key
|
|
t!("error.unknown")
|
|
|
|
// With parameter interpolation (%{name} in YAML)
|
|
t!("bins.deprecated.renamed", old = old_name, new = new_name)
|
|
```
|
|
|
|
## Key Naming Conventions
|
|
|
|
Keys use **dot-separated hierarchical namespaces** with **kebab-case** for multi-word segments:
|
|
|
|
```
|
|
<module>.<submodule>.<descriptive-name>
|
|
```
|
|
|
|
Examples:
|
|
- `error.incorrect-password` — error kind label
|
|
- `bins.start-init.updating-firmware` — startup phase message
|
|
- `backup.bulk.complete-title` — backup notification title
|
|
- `help.arg.acme-contact` — CLI help text for an argument
|
|
- `context.diagnostic.starting-diagnostic-ui` — diagnostic context status
|
|
|
|
### Top-Level Namespaces
|
|
|
|
| Namespace | Purpose |
|
|
|-----------|---------|
|
|
| `error.*` | `ErrorKind` display strings (see `src/error.rs`) |
|
|
| `bins.*` | CLI binary messages (deprecated, start-init, startd, etc.) |
|
|
| `init.*` | Initialization phase labels |
|
|
| `setup.*` | First-run setup messages |
|
|
| `context.*` | Context startup messages (diagnostic, setup, CLI) |
|
|
| `service.*` | Service lifecycle messages |
|
|
| `backup.*` | Backup/restore operation messages |
|
|
| `registry.*` | Package registry messages |
|
|
| `net.*` | Network-related messages |
|
|
| `middleware.*` | Request middleware messages (auth, etc.) |
|
|
| `disk.*` | Disk operation messages |
|
|
| `lxc.*` | Container management messages |
|
|
| `system.*` | System monitoring/metrics messages |
|
|
| `notifications.*` | User-facing notification messages |
|
|
| `update.*` | OS update messages |
|
|
| `util.*` | Utility messages (TUI, RPC) |
|
|
| `ssh.*` | SSH operation messages |
|
|
| `shutdown.*` | Shutdown-related messages |
|
|
| `logs.*` | Log-related messages |
|
|
| `auth.*` | Authentication messages |
|
|
| `help.*` | CLI help text (`help.arg.<arg-name>`) |
|
|
| `about.*` | CLI command descriptions |
|
|
|
|
## Locale Selection
|
|
|
|
`core/src/bins/mod.rs:15-36` — `set_locale_from_env()`:
|
|
|
|
1. Reads `LANG` environment variable
|
|
2. Strips `.UTF-8` suffix
|
|
3. Exact-matches against available locales, falls back to language-prefix match (e.g. `en_GB` matches `en_US`)
|
|
|
|
## Adding New Keys
|
|
|
|
1. Add the key to `core/locales/i18n.yaml` with all 5 language translations
|
|
2. Use the `t!("your.key.name")` macro in Rust code
|
|
3. Follow existing namespace conventions — match the module path where the key is used
|
|
4. Use kebab-case for multi-word segments
|
|
5. Translations are validated at compile time
|