EdisonJwa
f1bc9a6c85
Imports the v0.9.2 documentation baseline and the bootstrap files required by docs/governance/repository-bootstrap-plan.md v0.1.0 §3, minus the justfile (added in the next commit). This commit establishes the git history for the project. All previous work lived only as filesystem state with no version control.
88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
|
|
# Chanora Internationalization and Localization Architecture
|
|
|
|
**Version:** 0.9.2
|
|
**Status:** Baseline Candidate
|
|
**Language:** English
|
|
|
|
**Repo path:** `docs/i18n/localization-architecture.md` ---
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines Chanora's i18n architecture. Chanora is expected to operate in multilingual environments where product UI language, server-provided names, user nicknames, channel names, chat messages, and diagnostics may contain different languages.
|
|
|
|
## 2. i18n Principles
|
|
|
|
| Principle | Rule |
|
|
|---|---|
|
|
| Product strings are localizable | UI copy, labels, settings, errors, and accessibility labels use localization resources. |
|
|
| Server content is not translated | Server names, channel names, client nicknames, and chat messages are displayed as content. |
|
|
| UTF-8 internal text | Cross-layer DTOs and storage use UTF-8-compatible strings. |
|
|
| Boundary conversion only | Non-UTF-8 conversion occurs only at explicit protocol or platform boundaries. |
|
|
| Diagnostics are stable | Machine-readable diagnostic keys remain language-neutral. |
|
|
| User-facing diagnostics may be localized | Diagnostic descriptions can be localized independently. |
|
|
| Fallback is deterministic | Missing translations fall back to English or configured baseline locale. |
|
|
|
|
## 3. Text Categories
|
|
|
|
| Category | Example | Handling |
|
|
|---|---|---|
|
|
| Product UI string | "Connect", "Settings" | Localized |
|
|
| Accessibility string | "Mute microphone" | Localized |
|
|
| Protocol/server content | Server name, channel name | Preserve and display |
|
|
| User content | Chat message, nickname | Preserve and display |
|
|
| Machine diagnostic key | `audio.device.route_changed` | Stable, not localized |
|
|
| Diagnostic description | "Audio route changed" | Localizable |
|
|
|
|
## 4. Encoding Architecture
|
|
|
|
```text
|
|
External server text
|
|
-> Protocol Adapter boundary conversion if required
|
|
-> UTF-8-compatible Rust DTO
|
|
-> Bridge DTO
|
|
-> Flutter ViewModel
|
|
-> Flutter Text rendering
|
|
|
|
Product string key
|
|
-> Localization Service
|
|
-> Locale resource lookup
|
|
-> Fallback if missing
|
|
-> Flutter rendering
|
|
```
|
|
|
|
## 5. Bidi and Mixed-Language Handling
|
|
|
|
The UI shall not assume that all text is left-to-right. Product strings and content strings should be rendered using platform text widgets capable of bidirectional text rendering where supported.
|
|
|
|
## 6. Testing
|
|
|
|
| Test | Purpose |
|
|
|---|---|
|
|
| Missing-key fallback | Ensure fallback locale works |
|
|
| Unicode server name | Ensure names survive protocol -> UI |
|
|
| Mixed-language chat | Ensure multilingual content displays |
|
|
| RTL smoke test | Ensure basic RTL strings render |
|
|
| Diagnostics Unicode export | Ensure multilingual diagnostics survive redaction |
|
|
| Machine-key stability | Ensure diagnostic keys are language-neutral |
|
|
|
|
## 7. Change History
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.1.0 | 2026-05-14 | Initial i18n and localization architecture baseline. |
|
|
|
|
|
|
## Baseline Candidate 0.9.1 Update
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.9.1 | 2026-05-14 | Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set. |
|
|
|
|
|
|
## Baseline Candidate 0.9.2 Update
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
|