init

enriched-qwen3-coder-next/DataPRO/Modules/TestSetups/CachedItemsList/Resources.md

@@ -0,0 +1,55 @@
+---
+source_files:
+  - DataPRO/Modules/TestSetups/CachedItemsList/Resources/TranslateExtension.cs
+  - DataPRO/Modules/TestSetups/CachedItemsList/Resources/StringResources.Designer.cs
+generated_at: "2026-04-16T04:51:53.561882+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "f0403bd28120458d"
+---
+
+# Resources
+
+## Documentation: `TranslateExtension` Markup Extension
+
+### 1. Purpose  
+The `TranslateExtension` class provides a WPF markup extension to enable declarative localization of UI strings in XAML. It allows developers to bind localized text to UI elements by referencing a resource key (e.g., `{local:Translate CacheTime}`), retrieving the corresponding string from the strongly-typed `StringResources` class. This avoids hardcoding English strings in XAML and supports runtime culture switching via `StringResources.Culture`. It exists to centralize and standardize string localization within the `CachedItemsList` module.
+
+### 2. Public Interface  
+
+- **`TranslateExtension(string key)`**  
+  Constructor. Initializes the extension with the resource key (`_key`) to look up.  
+  - *Parameter*: `key` (`string`) – The resource key (e.g., `"CacheTime"`, `"Name"`). Must match a key in the `.resx` file.  
+
+- **`override object ProvideValue(IServiceProvider serviceProvider)`**  
+  WPF markup extension entry point. Performs the resource lookup at runtime.  
+  - *Behavior*:  
+    - If `_key` is `null` or empty → returns `"#stringnotfound#"`.  
+    - Otherwise, calls `StringResources.ResourceManager.GetString(_key)`.  
+      - If a matching string is found → returns the localized string.  
+      - If no match is found → returns `"#stringnotfound# " + _key` (e.g., `"#stringnotfound# UnknownKey"`).  
+
+### 3. Invariants  
+- `_key` is immutable after construction (stored in a `readonly` field).  
+- The returned value is always a `string` (enforced by `[MarkupExtensionReturnType(typeof(string))]`).  
+- Lookup is case-sensitive (relies on `ResourceManager.GetString`, which performs exact key matching).  
+- No fallback logic beyond the `"#stringnotfound#"` prefix; missing keys are *not* silently ignored.  
+- Thread-safety: `StringResources.ResourceManager` is thread-safe (uses double-checked locking internally), but `TranslateExtension` itself does not enforce thread-safety for concurrent `ProvideValue` calls—though WPF typically invokes it on the UI thread.
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `System.Windows.Markup.MarkupExtension` (WPF framework)  
+  - `CachedItemsList.Resources.StringResources` (strongly-typed resource class)  
+  - `System.Resources.ResourceManager` (via `StringResources.ResourceManager`)  
+- **Used by**:  
+  - XAML files in the `CachedItemsList` module (e.g., `*.xaml` pages referencing `{local:Translate ...}`).  
+  - No direct programmatic usage in the provided source; usage is exclusively via XAML markup.  
+
+### 5. Gotchas  
+- **Hardcoded fallback**: The `"#stringnotfound#"` prefix is used verbatim for missing keys—this may cause UI clutter if keys are misspelled.  
+- **No null-safety for `serviceProvider`**: The `ProvideValue` method does not validate `serviceProvider` (though WPF always provides a valid instance during XAML parsing).  
+- **Culture switching requires manual update**: While `StringResources.Culture` can be set to switch languages, `TranslateExtension` does not auto-refresh when `Culture` changes; UI updates require re-evaluation (e.g., via property change notifications or re-rendering).  
+- **Key must match `.resx` keys exactly**: Typos in XAML (e.g., `{local:Translate Cache_Time}` vs. `"CacheTime"`) will trigger the fallback string.  
+- **No compile-time key validation**: XAML keys are strings; invalid keys are only caught at runtime (when `ProvideValue` executes).  
+- **Auto-generated resource class**: `StringResources.Designer.cs` is regenerated on build; manual edits will be lost. Resource keys must be managed in the `.resx` file.  
+- **No support for parameterized strings**: The extension only retrieves static strings; it does not handle `string.Format`-style placeholders (e.g., `"Hello {0}"`).