docs: update documentations to reflect browser extension i18n features

README.md

@@ -92,9 +92,11 @@ To connect your extension to a self-hosted server, open the popup → **Room** t
 
 ### 🌐 Localization & Translations
 
-The official KoalaSync website features a custom static site compiler to offer seamless localization:
-- **Available Languages**: Manually verified languages (English, German) and auto-generated variants ready for review (French, Spanish, Brazilian Portuguese, and Russian).
-- **Contributing**: We welcome community translations! Please refer directly to the [TRANSLATION.md](website/TRANSLATION.md) file for step-by-step instructions on how to review auto-generated translations or contribute support for new languages.
+Both the official KoalaSync website and the **v2.0 Browser Extension** feature full dynamic localization:
+- **Available Languages**: Support is included for 6 languages: English (`en`), German (`de`), French (`fr`), Spanish (`es`), Portuguese (Brazil) (`pt-BR`), and Russian (`ru`).
+- **Real-Time Extension Localization**: Inside the extension Settings panel, users can swap languages instantly. The entire interface, notifications, Empty States, and onboarding guides re-translate dynamically in real-time.
+- **Contributing**: We welcome community translations for both the website and the extension! Please refer directly to the [TRANSLATION.md](website/TRANSLATION.md) guide for step-by-step instructions on how to audit, refine, or add new languages.
+
 
 ---
 

extension/README.md

@@ -8,11 +8,12 @@ A Manifest V3 Browser Extension (Chrome & Firefox) for synchronized video playba
 - **Smart Peer IDs**: Hexadecimal IDs combined with customizable Usernames for easy identification.
 - **Dual Heartbeat**: Advanced session tracking (Background) and video synchronization (Content) to prevent ghost sessions.
 - **Live Diagnostics**: Built-in "Dev" tab for real-time video state debugging (ReadyState, CurrentTime, etc.).
+- **Dynamic i18n (Multi-Language)**: Fully localized in 6 languages (`en`, `de`, `fr`, `es`, `pt-BR`, `ru`) with auto-detected fallback and dynamic on-the-fly language selectors.
 
 ## Tab Overview
 1. **Room**: Manage connections, view active peers, and share invitation links.
 2. **Sync**: Control video playback (Play/Pause/Force Sync) and view recent activity.
-3. **Settings**: Customize your Username and toggle domain-based Noise Filtering.
+3. **Settings**: Customize your Username, toggle domain-based Noise Filtering, and switch the App Language.
 4. **Dev**: Monitor connection status and view real-time video element metadata for debugging.
 
 ## Privacy & Permissions

website/TRANSLATION.md

@@ -146,3 +146,35 @@ document.addEventListener('DOMContentLoaded', async () => {
 *   **Zero URL Pollution:** Keeps invitation hashes private and avoids messy query parameters (`?lang=de`), protecting user privacy.
 *   **Optimal Performance:** Eliminates duplicate hidden text blocks, cutting page weight in half and ensuring smooth rendering.
 *   **Infinite Scale:** Adding new languages to dynamic pages requires zero edits to HTML markup; the engine simply fetches new JSON dictionaries on-demand.
+
+---
+
+## 🔌 Extension Internationalization (i18n)
+
+In **v2.0**, we extended full internationalization support to the **Browser Extension itself**. The architecture mirrors our web-based dynamic localization model to maintain complete parity.
+
+*   **Locales Directory:** [`extension/locales/`](file:///Users/koala/Documents/KoalaPlay/extension/locales/)
+*   **Active Dictionaries:**
+    *   [`en.json`](file:///Users/koala/Documents/KoalaPlay/extension/locales/en.json) (Baseline English)
+    *   [`de.json`](file:///Users/koala/Documents/KoalaPlay/extension/locales/de.json) (German)
+    *   [`fr.json`](file:///Users/koala/Documents/KoalaPlay/extension/locales/fr.json) (French)
+    *   [`es.json`](file:///Users/koala/Documents/KoalaPlay/extension/locales/es.json) (Spanish)
+    *   [`pt-BR.json`](file:///Users/koala/Documents/KoalaPlay/extension/locales/pt-BR.json) (Portuguese (Brasil))
+    *   [`ru.json`](file:///Users/koala/Documents/KoalaPlay/extension/locales/ru.json) (Russian)
+*   **Translation Engine:** [`extension/i18n.js`](file:///Users/koala/Documents/KoalaPlay/extension/i18n.js)
+*   **Validation Script:** [`scripts/test-locales.js`](file:///Users/koala/Documents/KoalaPlay/scripts/test-locales.js)
+
+### ⚙️ How it Works inside the Extension
+
+1. **System Locale Auto-Detection**: On first run, the extension detects the browser system language using `navigator.language` or `chrome.i18n.getUILanguage()`.
+2. **On-the-Fly Redraws**: When the user selects a different language in the settings tab (`#langSelector`), the selection is stored in `chrome.storage.sync` and the translation engine immediately triggers `translateDOM()`. The interface, empty state cards, tooltips, dynamic onboarding tutorial guides, and status badges re-render instantly without reloading the popup.
+3. **Localized System Notifications**: On play, pause, or seek commands, `background.js` retrieves the user's active locale preference from storage, loads the correct dictionary, and pushes native OS notifications fully translated.
+
+### 🧪 Auditing & Sync Checks
+
+To ensure that no language dictionary falls out of sync (causing missing labels or blank interfaces), developers must run the locale auditor tool before packaging releases:
+```bash
+node scripts/test-locales.js
+```
+This script asserts that all JSON dictionary files under `extension/locales/` share exactly the same set of keys as the English baseline (`en.json`).
+