feat: compile-time i18n system (v0.3.0)

Zero-ceremony internationalization: string literals in UI components are
automatically localizable keys. Translation files are flat JSON, all
validation happens at compile time, and translations are baked into the
binary as an embedded string table with near-zero runtime lookup cost.

- Embedded 2D string table: translations[locale_idx * key_count + string_idx]
- Native locale detection on all 6 platforms (CFLocaleCopyCurrent, GetUserDefaultLocaleName, Android system properties, LANG/LC_ALL)
- {param} interpolation with runtime substitution
- CLDR plural rules for 30+ locales (.one/.other/.few/.many/.zero/.two)
- Format wrappers: Currency, Percent, ShortDate, LongDate, FormatNumber, FormatTime, Raw
- perry i18n extract CLI for scaffolding locale files
- iOS .lproj + Android values-xx/ platform resource generation
- Compile-time validation: missing translations, param mismatches, plural form errors

Author: proggeramlug

CHANGELOG.md

@@ -2,6 +2,47 @@
 
 Detailed changelog for Perry. See CLAUDE.md for concise summaries.
 
+## v0.3.0 — Compile-Time Internationalization
+
+Major release adding a complete compile-time i18n system to Perry.
+
+### Core Mechanism
+- `[i18n]` section in perry.toml: `locales`, `default_locale`, `dynamic`, `[i18n.currencies]`
+- Embedded 2D string table: `translations[locale_idx * key_count + string_idx]` — all locales baked into binary
+- UI widget string detection: string literals in `Button`, `Text`, `Label`, `TextField`, `TextArea`, `Tab`, `NavigationTitle`, `SectionHeader`, `SecureField`, `Alert` automatically treated as localizable keys
+- `Expr::I18nString` HIR variant with transform pass (`perry-transform/src/i18n.rs`) and Cranelift codegen with locale branching
+- Compile-time validation: warns on missing translations, unused keys, parameter mismatches
+- Key registry: `.perry/i18n-keys.json` updated on every build
+
+### Locale Detection (all 6 platforms)
+- macOS/iOS: `CFLocaleCopyCurrent()` (CoreFoundation) — works for GUI apps launched from Finder/SpringBoard
+- Windows: `GetUserDefaultLocaleName()` (Win32)
+- Android: `__system_property_get("persist.sys.locale")` (bionic libc)
+- Linux: `LANG` / `LC_ALL` / `LC_MESSAGES` env vars
+- Platform-native APIs tried first, env vars as fallback
+- Fuzzy matching: `de_DE.UTF-8` matches `de`, normalizes `_` to `-`
+
+### Interpolation & Plurals
+- Parameterized strings: `Text("Hello, {name}!", { name: user.name })` — runtime `perry_i18n_interpolate()` does `{param}` → value substitution
+- CLDR plural rules for 30+ locales: `.one`/`.other`/`.few`/`.many`/`.zero`/`.two` suffixes, compile-time validation, runtime `perry_i18n_plural_category()` category selection
+- `perry/i18n` native module: `import { t } from "perry/i18n"` for non-UI string localization
+
+### Format Wrappers
+- `Currency(value)`, `Percent(value)`, `ShortDate(timestamp)`, `LongDate(timestamp)`, `FormatNumber(value)`, `FormatTime(timestamp)`, `Raw(value)` — importable from `perry/i18n`
+- Hand-rolled formatting rules for 25+ locales: number grouping, decimal/thousands separators, currency symbol placement, date ordering (MDY/DMY/YMD), 12h vs 24h time, percent spacing
+- `[i18n.currencies]` config: locale → ISO 4217 code mapping
+
+### CLI & Platform Output
+- `perry i18n extract`: scans `.ts`/`.tsx` files, generates/updates `locales/*.json` scaffolds
+- iOS: `{locale}.lproj/Localizable.strings` generated inside `.app` bundle
+- Android: `res/values-{locale}/strings.xml` generated alongside `.so`
+
+### New Files
+- `crates/perry-transform/src/i18n.rs` — HIR transform pass
+- `crates/perry-runtime/src/i18n.rs` — Runtime: locale detection, interpolation, plural rules, formatters
+- `crates/perry/src/commands/i18n.rs` — CLI extract command
+- `docs/src/i18n/` — 4 documentation pages (overview, interpolation, formatting, CLI)
+
 ## v0.2.202
 - Fix `perry setup ios` not saving bundle_id to perry.toml — bundle ID was used for provisioning profile creation but never written to `[ios].bundle_id`; `perry publish` fell back to default `com.perry.<name>`, causing profile/bundle mismatch
 

CLAUDE.md

@@ -8,7 +8,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Perry is a native TypeScript compiler written in Rust that compiles TypeScript source code directly to native executables. It uses SWC for TypeScript parsing and Cranelift for code generation.
 
-**Current Version:** 0.2.202
+**Current Version:** 0.3.0
 
 ## Workflow Requirements
 
@@ -153,6 +153,12 @@ Projects can list npm packages to compile natively instead of routing to V8. Con
 
 ## Recent Changes
 
+### v0.3.0
+- Compile-time i18n system (`perry/i18n` module): zero-ceremony localization for UI strings, `[i18n]` config in perry.toml, embedded 2D string table, native locale detection (all 6 platforms via OS APIs), `{param}` interpolation, CLDR plural rules (30+ locales), format wrappers (`Currency`, `Percent`, `ShortDate`, `LongDate`, `FormatNumber`, `FormatTime`, `Raw`), `perry i18n extract` CLI, iOS `.lproj` + Android `values-xx/` generation, compile-time validation
+
+### v0.2.203
+- `perry setup` summary: show what's stored in global config vs project perry.toml for all platforms
+
 ### v0.2.202
 - Fix `perry setup ios` not saving bundle_id to perry.toml
 

Cargo.lock

@@ -79,7 +79,7 @@ opt-level = "s"       # Optimize for size in stdlib
 opt-level = 3
 
 [workspace.package]
-version = "0.2.202"
+version = "0.3.0"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/PerryTS/perry"

Cargo.toml

@@ -696,6 +696,10 @@ impl JsEmitter {
             Expr::String(s) => {
                 self.output.push_str(&self.quote_string(s));
             }
+            Expr::I18nString { key, .. } => {
+                // JS codegen: emit as regular string (i18n handled by JS runtime)
+                self.output.push_str(&self.quote_string(key));
+            }
 
             // --- Variables ---
             Expr::LocalGet(id) => {

crates/perry-codegen-js/src/emit.rs

@@ -860,7 +860,7 @@ impl crate::codegen::Compiler {
             }
             // Expressions with no inner expressions to traverse
             Expr::Undefined | Expr::Null | Expr::Bool(_) | Expr::Number(_) | Expr::Integer(_) |
-            Expr::BigInt(_) | Expr::String(_) | Expr::LocalGet(_) | Expr::GlobalGet(_) |
+            Expr::BigInt(_) | Expr::String(_) | Expr::I18nString { .. } | Expr::LocalGet(_) | Expr::GlobalGet(_) |
             Expr::Update { .. } | Expr::FuncRef(_) | Expr::ExternFuncRef { .. } |
             Expr::NativeModuleRef(_) | Expr::StaticFieldGet { .. } | Expr::This |
             Expr::EnumMember { .. } | Expr::ClassRef(_) | Expr::EnvGet(_) |