init

enriched-qwen3-coder-next/DataPRO/Modules/Groups/GroupChannelList/Resources.md

@@ -0,0 +1,77 @@
+---
+source_files:
+  - DataPRO/Modules/Groups/GroupChannelList/Resources/TranslateExtension.cs
+  - DataPRO/Modules/Groups/GroupChannelList/Resources/StringResources.Designer.cs
+generated_at: "2026-04-16T04:46:25.212575+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "5dba578a99876d46"
+---
+
+# Documentation: `TranslateExtension` Markup Extension
+
+## 1. Purpose
+
+This module provides a WPF `MarkupExtension` (`TranslateExtension`) that enables localization of UI strings directly in XAML by resolving resource keys against a strongly-typed resource class (`StringResources`). It serves as a bridge between declarative UI markup and localized string resources, allowing developers to bind text content (e.g., labels, tooltips, headers) to culture-sensitive values without writing code-behind. Its role is critical for internationalization of the `GroupChannelList` module, ensuring that user-facing text adapts to the current UI culture.
+
+## 2. Public Interface
+
+### `TranslateExtension` class
+
+- **Namespace**: `GroupChannelList`  
+- **Base class**: `System.Windows.Markup.MarkupExtension`  
+- **Attribute**: `[MarkupExtensionReturnType(typeof(string))]`
+
+#### Constructor  
+```csharp
+public TranslateExtension(string key)
+```
+- **Parameters**:  
+  - `key` (`string`): The resource key (e.g., `"ChannelName"`) used to look up a localized string in `StringResources`.
+- **Behavior**: Stores the key for later resolution during `ProvideValue`.
+
+#### `ProvideValue` method  
+```csharp
+public override object ProvideValue(IServiceProvider serviceProvider)
+```
+- **Parameters**:  
+  - `serviceProvider` (`IServiceProvider`): WPF service provider (unused in current implementation).
+- **Returns**:  
+  - `string`: The localized string if the key exists and is non-null/non-empty; otherwise, one of two fallback values:
+    - If `_key` is `null` or empty → returns `"#stringnotfound#"`
+    - If `StringResources.ResourceManager.GetString(_key)` returns `null` → returns `"#stringnotfound# " + _key` (e.g., `"#stringnotfound# ChannelName"`)
+- **Behavior**: Performs a culture-aware lookup using `StringResources.ResourceManager.GetString(_key)`.
+
+## 3. Invariants
+
+- **Key must be a valid resource key**: The `_key` passed to the constructor must match a property name in `StringResources` (e.g., `"ChannelName"`, `"AnalogParameters_Range"`). Mismatched keys will result in the fallback `"#stringnotfound# <key>"` string.
+- **Null/empty key handling**: If `_key` is `null` or `string.Empty`, the extension *always* returns `"#stringnotfound#"` (no concatenation with key).
+- **No culture override via extension**: The extension does not expose or support overriding the culture used for lookup; it relies on the current `Thread.CurrentUICulture` via `StringResources.Culture`.
+- **No side effects**: `ProvideValue` is pure—no state mutation or I/O occurs beyond the resource lookup.
+
+## 4. Dependencies
+
+### Dependencies *of* this module:
+- **`System.Windows.Markup`**: Required for `MarkupExtension` base class and `MarkupExtensionReturnTypeAttribute`.
+- **`GroupChannelList.Resources.StringResources`**: Strongly-typed resource class generated from `.resx` files. Relies on:
+  - `System.Resources.ResourceManager`
+  - `System.Globalization.CultureInfo`
+- **WPF runtime**: Required for `IServiceProvider` and XAML markup extension resolution.
+
+### Dependencies *on* this module:
+- **XAML files in `GroupChannelList` module**: Used via XMLNS (e.g., `xmlns:res="clr-namespace:GroupChannelList"`) to localize UI elements:
+  ```xml
+  <TextBlock Text="{res:Translate ChannelName}" />
+  ```
+- **No other modules directly depend on `TranslateExtension`**—it is consumed only via XAML markup.
+
+## 5. Gotchas
+
+- **No runtime validation of key existence**: If a resource key is misspelled (e.g., `"ChannelNme"` instead of `"ChannelName"`), the extension silently returns `"#stringnotfound# ChannelNme"`, which may appear as visible text in the UI.  
+- **No fallback to default language**: If a key exists in the `.resx` but lacks a translation for the current culture, `ResourceManager.GetString` returns `null`, triggering the fallback string. This may cause inconsistent behavior if translations are incomplete.
+- **Hardcoded fallback prefix**: The `"#stringnotfound#"` prefix is hardcoded and not configurable. This could conflict with legitimate strings if used as a key.
+- **No support for parameterized strings**: While `StringResources` includes format strings (e.g., `"Sensor {0} can not be assigned..."`), `TranslateExtension` does not support passing arguments (e.g., `{res:Translate Key, Arg1, Arg2}`). Developers must use `String.Format` manually in code-behind or elsewhere.
+- **Auto-generated resource class**: `StringResources.Designer.cs` is auto-generated; manual edits are overwritten. Adding new keys requires updating the `.resx` file and regenerating the class.
+- **No thread-safety guarantees**: Though `ResourceManager` is thread-safe, the extension itself is stateful (via `_key`), but this is harmless since each usage creates a new instance.
+
+None identified beyond the above.