init

enriched-qwen3-coder-next/DataPRO/Modules/Reports/PedestrianAndHeadReports/Resources.md

@@ -0,0 +1,98 @@
+---
+source_files:
+  - DataPRO/Modules/Reports/PedestrianAndHeadReports/Resources/TranslateExtension.cs
+  - DataPRO/Modules/Reports/PedestrianAndHeadReports/Resources/StringResources.Designer.cs
+generated_at: "2026-04-16T04:55:02.133936+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "b181762eeb96b72d"
+---
+
+# Resources
+
+## Documentation: `TranslateExtension` Module
+
+---
+
+### 1. Purpose
+
+This module provides a WPF `MarkupExtension` (`TranslateExtension`) to enable declarative, localized string resolution in XAML. It allows UI elements (e.g., `TextBlock.Text`, `Header`, etc.) to bind to resource keys and automatically retrieve the corresponding localized string at runtime from `StringResources`, falling back to a standardized placeholder if the key is missing or empty. Its role is to centralize and simplify internationalization (i18n) for the *PedestrianAndHeadReports* module, ensuring consistent handling of localized UI text without requiring code-behind or manual resource lookups.
+
+---
+
+### 2. Public Interface
+
+#### `TranslateExtension` class  
+**Namespace:** `PedestrianAndHeadReports.Resources`  
+**Inherits:** `System.Windows.Markup.MarkupExtension`
+
+##### Constructor  
+```csharp
+public TranslateExtension(string key)
+```
+- **Purpose:** Initializes a new instance with the specified resource key.
+- **Parameters:**  
+  - `key`: The string key used to look up a localized value in `StringResources.ResourceManager`.
+
+##### `ProvideValue` method  
+```csharp
+public override object ProvideValue(IServiceProvider serviceProvider)
+```
+- **Purpose:** Returns the localized string corresponding to `_key`, or a fallback value if lookup fails.
+- **Behavior:**  
+  - If `_key` is `null` or empty → returns `"#stringnotfound#"`.  
+  - Otherwise, calls `StringResources.ResourceManager.GetString(_key)`.  
+    - If the result is non-null → returns the localized string.  
+    - If the result is `null` → returns `"#stringnotfound# " + _key` (i.e., the placeholder followed by a space and the original key).  
+- **Return type:** `object` (always a `string` per `[MarkupExtensionReturnType(typeof(string))]`).
+
+---
+
+### 3. Invariants
+
+- **Key must be non-null/non-empty for meaningful lookup:**  
+  Empty or `null` keys are explicitly handled and return `"#stringnotfound#"`—no exception is thrown.
+- **Fallback format is deterministic:**  
+  When a key is missing, the output is always `"#stringnotfound# <key>"`. This makes missing keys visually identifiable in the UI.
+- **Thread-safety of resource access is assumed:**  
+  `StringResources.ResourceManager.GetString(...)` is used directly; while `ResourceManager` is thread-safe for concurrent reads, the extension itself does not enforce synchronization (but WPF’s `MarkupExtension` lifecycle typically avoids concurrent `ProvideValue` calls per instance).
+- **Return type is always a string:**  
+  Guaranteed by `[MarkupExtensionReturnType(typeof(string))]` and implementation.
+
+---
+
+### 4. Dependencies
+
+#### Dependencies *of* this module:
+- **`System.Windows.Markup`** (WPF framework): Required for `MarkupExtension` base class and `MarkupExtensionReturnTypeAttribute`.
+- **`PedestrianAndHeadReports.Resources.StringResources`**:  
+  - Used via `StringResources.ResourceManager.GetString(...)`.  
+  - `StringResources` is auto-generated from `.resx` files and contains strongly-typed properties (e.g., `Acceleration`, `TestDate`) backed by the `ResourceManager`.
+
+#### Dependencies *on* this module:
+- **XAML files in the `PedestrianAndHeadReports` module** (inferred):  
+  - Likely used in XAML as `{local:Translate KeyName}` to localize UI elements.  
+  - Example: `<TextBlock Text="{local:Translate Acceleration}" />` → resolves to localized string for `"Acceleration"` (e.g., `"加速度"` in Japanese).
+
+#### External dependencies:
+- **.NET Framework 4.0+** (inferred from runtime version in `StringResources.Designer.cs` header).
+
+---
+
+### 5. Gotchas
+
+- **No caching of resolved values per instance:**  
+  Each call to `ProvideValue` performs a fresh `ResourceManager.GetString(_key)` lookup. While `ResourceManager` caches internally, repeated use of the same `TranslateExtension` instance in different contexts (e.g., data templates) may re-resolve unnecessarily.
+- **Missing keys produce visible placeholders in UI:**  
+  The `"#stringnotfound# <key>"` fallback is intentional for debugging but may appear in production if resource keys are mistyped or missing in `.resx` files.
+- **Case sensitivity of keys:**  
+  Resource keys (e.g., `"Acceleration"`, `"Acceleration "`) are case-sensitive. A mismatch in casing (e.g., `"acceleration"`) will result in a `null` lookup and fallback.
+- **No support for parameterized strings (e.g., `string.Format`):**  
+  The extension only supports simple key → string lookup. It does not handle placeholders (e.g., `"Hello {0}"`) or arguments.
+- **Auto-generated `StringResources` class:**  
+  Changes to the underlying `.resx` file require regeneration of `StringResources.Designer.cs`. If keys are renamed/removed in `.resx` but referenced in XAML via `TranslateExtension`, they will fall back to `"#stringnotfound#..."`.
+- **No culture override support in `TranslateExtension`:**  
+  While `StringResources.Culture` can be set globally, `TranslateExtension` does not expose or accept a culture parameter—respects only the current UI thread’s `CurrentUICulture`.
+
+> **None identified from source alone.**  
+> *(Note: The above are inferred from standard behavior of `ResourceManager`, WPF `MarkupExtension`, and common localization patterns—not from explicit warnings in the source.)*