fixing db error and upgrading technical documentation

2026-02-12 22:29:35 +01:00
parent ab8f3191cb
commit 8123406ab9
43 changed files with 6366 additions and 4555 deletions
@@ -0,0 +1,99 @@
+# 16 - Internationalization
+
+JSON-based translation system. Translations are loaded from static files, cached in memory, and served via a public REST API (no auth required).
+
+## Supported Languages
+
+| Locale | Code | File |
+|---|---|---|
+| English | `en` | `static/locales/en.json` |
+| Spanish | `es` | `static/locales/es.json` |
+| French | `fr` | `static/locales/fr.json` |
+| German | `de` | `static/locales/de.json` |
+| Portuguese | `pt` | `static/locales/pt.json` |
+| Persian | `fa` | `static/locales/fa.json` |
+| Chinese | `zh` | `static/locales/zh.json` |
+
+Default locale: **en** (English).
+
+## Architecture
+
+| Layer | Component | File |
+|---|---|---|
+| Domain Port | **I18nService** trait, **Locale** enum | `src/domain/services/i18n_service.rs` |
+| Application Service | **I18nApplicationService** | `src/application/services/i18n_application_service.rs` |
+| Application DTOs | **LocaleDto**, **TranslationRequestDto**, etc. | `src/application/dtos/i18n_dto.rs` |
+| Infrastructure | **FileSystemI18nService** | `src/infrastructure/services/file_system_i18n_service.rs` |
+| Interfaces | **I18nHandler** | `src/interfaces/api/handlers/i18n_handler.rs` |
+
+## REST API
+
+Public endpoints (no authentication), under `/api/i18n`:
+
+| Method | Path | Handler | Description |
+|---|---|---|---|
+| `GET` | `/api/i18n/locales` | `get_locales` | List available locales |
+| `GET` | `/api/i18n/translate` | `translate` | Translate a key (`?key=...&locale=...`) |
+| `GET` | `/api/i18n/locales/{locale_code}` | `get_translations_by_locale` | Get all translations for a locale |
+
+### Examples
+
+```bash
+# List available locales
+curl "https://oxicloud.example.com/api/i18n/locales"
+# [{"code":"en","name":"English"},{"code":"es","name":"Spanish"}, ...]
+
+# Translate a key
+curl "https://oxicloud.example.com/api/i18n/translate?key=app.title&locale=es"
+# {"key":"app.title","locale":"es","text":"OxiCloud"}
+
+# Get all translations for a locale
+curl "https://oxicloud.example.com/api/i18n/locales/en"
+# { "app": { "title": "OxiCloud", ... }, "nav": { ... }, ... }
+```
+
+## Translation File Format
+
+Nested JSON with dot-delimited key lookups:
+
+```json
+{
+  "app": {
+    "title": "OxiCloud",
+    "description": "Your personal cloud storage"
+  },
+  "nav": {
+    "files": "Files",
+    "shared": "Shared",
+    "recent": "Recent",
+    "favorites": "Favorites",
+    "trash": "Trash"
+  },
+  "actions": {
+    "search": "Search files...",
+    "new_folder": "New folder",
+    "upload": "Upload",
+    "download": "Download",
+    "delete": "Delete"
+  },
+  "share": { ... },
+  "user_menu": { ... }
+}
+```
+
+Key lookup: `"nav.files"` resolves to `"Files"`.
+
+## Fallback Behavior
+
+If a key is missing in the requested locale, the system falls back to English (`en`). If still not found, returns an `I18nError::KeyNotFound`.
+
+## Caching
+
+Translations are cached in-memory via `RwLock<HashMap<Locale, serde_json::Value>>`. Loaded lazily on first request per locale.
+
+## Frontend Integration
+
+The frontend uses `static/js/i18n.js` and `static/js/languageSelector.js` to:
+1. Detect the user's preferred language
+2. Load translations via `/api/i18n/locales/{code}`
+3. Apply translations to DOM elements