# 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. |