77 lines
5.0 KiB
Markdown
77 lines
5.0 KiB
Markdown
|
---
|
||
|
|
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.
|