80 lines
4.7 KiB
Markdown
80 lines
4.7 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/Modules/Realtime/RealtimeModule/Resources/TranslateExtension.cs
|
||
- DataPRO/Modules/Realtime/RealtimeModule/Resources/StringResources.Designer.cs
|
||
generated_at: "2026-04-16T04:47:55.535596+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "036a24899acb6b7e"
|
||
---
|
||
|
||
# Resources
|
||
|
||
## Documentation: `TranslateExtension` Class
|
||
|
||
### 1. Purpose
|
||
The `TranslateExtension` class provides a XAML markup extension for localized string resolution within the RealtimeModule UI layer. It enables declarative binding of localized text in XAML (e.g., `{Translate SomeKey}`) by delegating string lookup to the `StringResources` strongly-typed resource class. This allows UI elements to support multi-language scenarios without hardcoding strings, and centralizes fallback behavior for missing translations.
|
||
|
||
### 2. Public Interface
|
||
|
||
#### `TranslateExtension` class
|
||
- **Inherits**: `System.Windows.Markup.MarkupExtension`
|
||
- **Namespace**: `RealtimeModule`
|
||
- **Attributes**:
|
||
- `[MarkupExtensionReturnType(typeof(string))]` — Indicates the extension returns a `string`.
|
||
|
||
##### Constructor
|
||
- `TranslateExtension(string key)`
|
||
- **Parameters**:
|
||
- `key`: The resource key (e.g., `"AvailableChannels"`, `"Search"`) used to look up the localized string.
|
||
- **Behavior**: Stores the key in a private readonly field `_key`. No validation is performed on the key itself (e.g., null/empty allowed at construction).
|
||
|
||
##### Override
|
||
- `public override object ProvideValue(IServiceProvider serviceProvider)`
|
||
- **Parameters**:
|
||
- `serviceProvider`: XAML infrastructure service provider (unused in implementation).
|
||
- **Returns**:
|
||
- `string`: The localized string if found; otherwise, a fallback string.
|
||
- **Behavior**:
|
||
1. If `_key` is `null` or empty → returns `"#stringnotfound#"`.
|
||
2. Otherwise, calls `StringResources.ResourceManager.GetString(_key)`.
|
||
- If the result is non-null → returns the localized string.
|
||
- If the result is `null` (key not found) → returns `"#stringnotfound# " + _key` (note: space appended after `#stringnotfound#`).
|
||
|
||
### 3. Invariants
|
||
- **Key lookup behavior**:
|
||
- The extension *always* returns a `string`.
|
||
- A missing key (i.e., `ResourceManager.GetString(key) == null`) results in a deterministic fallback: `"#stringnotfound# " + _key`.
|
||
- **Null/empty key handling**:
|
||
- `_key == null` or `_key == ""` → returns `"#stringnotfound#"` (no key suffix).
|
||
- **No side effects**:
|
||
- `ProvideValue` is pure (no mutation of state, no I/O beyond resource lookup).
|
||
- **Thread-safety assumption**:
|
||
- Relies on `ResourceManager.GetString`, which is documented as thread-safe for read operations in .NET. No additional synchronization is implemented in `TranslateExtension`.
|
||
|
||
### 4. Dependencies
|
||
- **Direct dependencies**:
|
||
- `System.Windows.Markup` (for `MarkupExtension` and `MarkupExtensionReturnTypeAttribute`).
|
||
- `RealtimeModule.Resources.StringResources` (strongly-typed resource class).
|
||
- **Indirect dependencies**:
|
||
- `System.Resources.ResourceManager` (via `StringResources.ResourceManager`).
|
||
- `System.Globalization.CultureInfo` (used by `StringResources.Culture` property, though not directly accessed here).
|
||
- **Consumers**:
|
||
- XAML files in the RealtimeModule (e.g., `*.xaml` views) that use `{Translate ...}` syntax.
|
||
- *No other C# code depends on this class* — it is exclusively for XAML usage.
|
||
|
||
### 5. Gotchas
|
||
- **Fallback format is literal and unlocalized**:
|
||
- The fallback string `"#stringnotfound# "` is hardcoded and includes a trailing space. This may cause visual artifacts (e.g., extra whitespace) in UI if keys are missing.
|
||
- **No validation of key validity**:
|
||
- Passing an invalid key (e.g., `"NonExistentKey"`) does not throw; it silently falls back to `"#stringnotfound# NonExistentKey"`. Developers may not immediately notice missing keys in development.
|
||
- **Case sensitivity**:
|
||
- Key lookup is case-sensitive (via `ResourceManager.GetString`). `"AvailableChannels"` works; `"availablechannels"` does not.
|
||
- **Auto-generated resource class**:
|
||
- `StringResources` is auto-generated from `.resx` files. Changes require regenerating the class (via `.resx` edits and rebuild). The extension will return `null`-equivalent fallback if keys are renamed/removed in the `.resx`.
|
||
- **No culture override support**:
|
||
- The extension does not expose or use `StringResources.Culture`. It relies on the current UI thread’s culture (standard WPF behavior).
|
||
- **No caching of resolved values**:
|
||
- Each `ProvideValue` call performs a fresh `ResourceManager.GetString` lookup. While `ResourceManager` caches internally, repeated use in dynamic UI (e.g., data templates) may have minor overhead.
|
||
|
||
None identified beyond the above. |