init

enriched-qwen3-coder-next/DataPRO/Modules/Realtime/RealtimeModule/Resources.md

@@ -0,0 +1,80 @@
+---
+source_files:
+  - DataPRO/Modules/Realtime/RealtimeModule/Resources/TranslateExtension.cs
+  - DataPRO/Modules/Realtime/RealtimeModule/Resources/StringResources.Designer.cs
+generated_at: "2026-04-16T04:47:55.535596+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "036a24899acb6b7e"
+---
+
+# Resources
+
+## Documentation: `TranslateExtension` Class
+
+### 1. Purpose  
+The `TranslateExtension` class provides a XAML markup extension for localized string resolution within the RealtimeModule UI layer. It enables declarative binding of localized text in XAML (e.g., `{Translate SomeKey}`) by delegating string lookup to the `StringResources` strongly-typed resource class. This allows UI elements to support multi-language scenarios without hardcoding strings, and centralizes fallback behavior for missing translations.
+
+### 2. Public Interface  
+
+#### `TranslateExtension` class  
+- **Inherits**: `System.Windows.Markup.MarkupExtension`  
+- **Namespace**: `RealtimeModule`  
+- **Attributes**:  
+  - `[MarkupExtensionReturnType(typeof(string))]` — Indicates the extension returns a `string`.
+
+##### Constructor  
+- `TranslateExtension(string key)`  
+  - **Parameters**:  
+    - `key`: The resource key (e.g., `"AvailableChannels"`, `"Search"`) used to look up the localized string.  
+  - **Behavior**: Stores the key in a private readonly field `_key`. No validation is performed on the key itself (e.g., null/empty allowed at construction).
+
+##### Override  
+- `public override object ProvideValue(IServiceProvider serviceProvider)`  
+  - **Parameters**:  
+    - `serviceProvider`: XAML infrastructure service provider (unused in implementation).  
+  - **Returns**:  
+    - `string`: The localized string if found; otherwise, a fallback string.  
+  - **Behavior**:  
+    1. If `_key` is `null` or empty → returns `"#stringnotfound#"`.  
+    2. Otherwise, calls `StringResources.ResourceManager.GetString(_key)`.  
+       - If the result is non-null → returns the localized string.  
+       - If the result is `null` (key not found) → returns `"#stringnotfound# " + _key` (note: space appended after `#stringnotfound#`).  
+
+### 3. Invariants  
+- **Key lookup behavior**:  
+  - The extension *always* returns a `string`.  
+  - A missing key (i.e., `ResourceManager.GetString(key) == null`) results in a deterministic fallback: `"#stringnotfound# " + _key`.  
+- **Null/empty key handling**:  
+  - `_key == null` or `_key == ""` → returns `"#stringnotfound#"` (no key suffix).  
+- **No side effects**:  
+  - `ProvideValue` is pure (no mutation of state, no I/O beyond resource lookup).  
+- **Thread-safety assumption**:  
+  - Relies on `ResourceManager.GetString`, which is documented as thread-safe for read operations in .NET. No additional synchronization is implemented in `TranslateExtension`.
+
+### 4. Dependencies  
+- **Direct dependencies**:  
+  - `System.Windows.Markup` (for `MarkupExtension` and `MarkupExtensionReturnTypeAttribute`).  
+  - `RealtimeModule.Resources.StringResources` (strongly-typed resource class).  
+- **Indirect dependencies**:  
+  - `System.Resources.ResourceManager` (via `StringResources.ResourceManager`).  
+  - `System.Globalization.CultureInfo` (used by `StringResources.Culture` property, though not directly accessed here).  
+- **Consumers**:  
+  - XAML files in the RealtimeModule (e.g., `*.xaml` views) that use `{Translate ...}` syntax.  
+  - *No other C# code depends on this class* — it is exclusively for XAML usage.
+
+### 5. Gotchas  
+- **Fallback format is literal and unlocalized**:  
+  - The fallback string `"#stringnotfound# "` is hardcoded and includes a trailing space. This may cause visual artifacts (e.g., extra whitespace) in UI if keys are missing.  
+- **No validation of key validity**:  
+  - Passing an invalid key (e.g., `"NonExistentKey"`) does not throw; it silently falls back to `"#stringnotfound# NonExistentKey"`. Developers may not immediately notice missing keys in development.  
+- **Case sensitivity**:  
+  - Key lookup is case-sensitive (via `ResourceManager.GetString`). `"AvailableChannels"` works; `"availablechannels"` does not.  
+- **Auto-generated resource class**:  
+  - `StringResources` is auto-generated from `.resx` files. Changes require regenerating the class (via `.resx` edits and rebuild). The extension will return `null`-equivalent fallback if keys are renamed/removed in the `.resx`.  
+- **No culture override support**:  
+  - The extension does not expose or use `StringResources.Culture`. It relies on the current UI thread’s culture (standard WPF behavior).  
+- **No caching of resolved values**:  
+  - Each `ProvideValue` call performs a fresh `ResourceManager.GetString` lookup. While `ResourceManager` caches internally, repeated use in dynamic UI (e.g., data templates) may have minor overhead.  
+
+None identified beyond the above.