104 lines
5.4 KiB
Markdown
104 lines
5.4 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/Modules/Channels/ChannelCodes/Resources/TranslateExtension.cs
|
||
- DataPRO/Modules/Channels/ChannelCodes/Resources/StringResources.Designer.cs
|
||
generated_at: "2026-04-16T04:55:56.339798+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "3fc30f8d93dc5d3b"
|
||
---
|
||
|
||
# Resources
|
||
|
||
## Documentation: `TranslateExtension` Markup Extension
|
||
|
||
---
|
||
|
||
### **Purpose**
|
||
|
||
The `TranslateExtension` class provides a XAML markup extension for localized string lookup within the `ChannelCodes` module. It enables declarative binding of UI text to resource keys defined in `StringResources.resx`, supporting internationalization by resolving keys at runtime using the .NET `ResourceManager`. This allows UI elements (e.g., `TextBlock.Text`, `Button.Content`) to display culture-specific strings without hardcoding values or writing code-behind.
|
||
|
||
---
|
||
|
||
### **Public Interface**
|
||
|
||
#### `TranslateExtension(string key)`
|
||
**Constructor**
|
||
- **Parameter**: `key` (`string`) – The resource key to look up (e.g., `"ChannelCode"`, `"DuplicateISOChannelCode"`).
|
||
- **Behavior**: Stores the key for later resolution. No validation is performed at construction time.
|
||
|
||
#### `public override object ProvideValue(IServiceProvider serviceProvider)`
|
||
**Markup Extension Entry Point**
|
||
- **Parameter**: `serviceProvider` (`IServiceProvider`) – Provides services to the markup extension (unused in current implementation).
|
||
- **Returns**:
|
||
- `string`: The localized string corresponding to `_key`, or
|
||
- `NotFound` (`"#stringnotfound#"`): If `_key` is `null` or empty,
|
||
- `NotFound + " " + _key`: If `_key` is non-empty but no matching resource string is found.
|
||
- **Behavior**:
|
||
1. Checks if `_key` is `null` or empty → returns `"#stringnotfound#"`.
|
||
2. Calls `StringResources.ResourceManager.GetString(_key)` to retrieve the localized string.
|
||
3. If `GetString` returns `null`, appends the key to the `NotFound` prefix (e.g., `"#stringnotfound# MissingISOCode"`).
|
||
|
||
> **Note**: The `MarkupExtensionReturnType` attribute indicates this extension always returns a `string`.
|
||
|
||
---
|
||
|
||
### **Invariants**
|
||
|
||
1. **Key Handling**:
|
||
- Empty or `null` keys are treated as invalid and always resolve to `"#stringnotfound#"`.
|
||
- Non-empty keys that lack a corresponding resource entry resolve to `"#stringnotfound# <key>"`.
|
||
2. **Resource Lookup**:
|
||
- Uses `StringResources.ResourceManager.GetString(key)` with the current UI culture (via `CultureInfo`).
|
||
- No fallback logic beyond the `null` check in `ProvideValue`.
|
||
3. **Thread Safety**:
|
||
- `StringResources.ResourceManager` is lazily initialized and cached (per `StringResources` class), but `TranslateExtension` itself is stateful per instance (stores `_key`). Reuse across threads is safe *only if* the same instance is not shared concurrently (standard for markup extensions).
|
||
|
||
---
|
||
|
||
### **Dependencies**
|
||
|
||
#### **Depends On**
|
||
- `System.Windows.Markup.MarkupExtension` (WPF framework)
|
||
- `ChannelCodes.Resources.StringResources` (strongly-typed resource class)
|
||
- Specifically relies on `StringResources.ResourceManager` and its `GetString(string)` method.
|
||
- `System` (for `string.IsNullOrEmpty`, `ResourceManager`, `CultureInfo`)
|
||
|
||
#### **Used By**
|
||
- XAML files in the `ChannelCodes` module (e.g., `*.xaml` pages) where localized text is declared via `{local:Translate KeyName}`.
|
||
- Example usage:
|
||
```xaml
|
||
<TextBlock Text="{local:Translate ChannelCode}" />
|
||
```
|
||
|
||
---
|
||
|
||
### **Gotchas**
|
||
|
||
1. **No Resource Key Validation at Compile Time**:
|
||
- Typos in resource keys (e.g., `"ChannelCodee"` instead of `"ChannelCode"`) will silently resolve to `"#stringnotfound# ChannelCodee"` at runtime.
|
||
- No build-time or design-time warning is generated for missing keys.
|
||
|
||
2. **Hardcoded `NotFound` Prefix**:
|
||
- The `"#stringnotfound#"` prefix is hardcoded and may be visible in the UI if a key is missing. This is likely intentional for debugging but could confuse end users.
|
||
|
||
3. **No Caching of Resolved Strings**:
|
||
- `ProvideValue` calls `ResourceManager.GetString(_key)` on every invocation. While `ResourceManager` caches resources internally, repeated use of the same key in a UI (e.g., in a `DataTemplate`) may incur unnecessary lookups. Consider caching if performance is critical.
|
||
|
||
4. **Culture Handling**:
|
||
- Respects `StringResources.Culture` (settable via `StringResources.Culture = ...`). If `Culture` is `null`, the UI thread’s `CurrentUICulture` is used.
|
||
- No explicit handling for fallback cultures (e.g., `en-US` → `en`).
|
||
|
||
5. **Auto-Generated Resource Class**:
|
||
- `StringResources.Designer.cs` is auto-generated. Manual edits will be overwritten. New strings must be added via `.resx` files and regenerated.
|
||
|
||
6. **No Support for Format Strings**:
|
||
- `TranslateExtension` does not support parameterized resources (e.g., `"Error: {0} is missing"`). While `StringResources` has entries like `DuplicateISOChannelCode` (which uses `{0}`), the extension itself does not accept or apply formatting arguments.
|
||
- To use formatted strings, the caller must manually construct the key (e.g., `"DuplicateISOChannelCode"`), but the resolved string will remain unformatted unless the *caller* applies `string.Format` (not done here).
|
||
|
||
7. **WPF-Specific**:
|
||
- Depends on `System.Windows.Markup`, making it unusable outside WPF (e.g., in MAUI, WinUI, or console apps).
|
||
|
||
---
|
||
|
||
*Documentation generated from source files dated to .NET Framework 4.0 and WPF. No external dependencies beyond standard .NET libraries.* |