84 lines
5.0 KiB
Markdown
84 lines
5.0 KiB
Markdown
|
---
|
|||
|
|
source_files:
|
|||
|
|
- DataPRO/Modules/Groups/GroupList/Resources/TranslateExtension.cs
|
|||
|
|
- DataPRO/Modules/Groups/GroupList/Resources/StringResources.Designer.cs
|
|||
|
|
generated_at: "2026-04-16T04:47:13.405699+00:00"
|
|||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|||
|
|
schema_version: 1
|
|||
|
|
sha256: "30656f2a830a5a31"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Resources
|
|||
|
|
|
|||
|
|
## Documentation: `TranslateExtension` Markup Extension
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 1. **Purpose**
|
|||
|
|
|
|||
|
|
This module provides a WPF `MarkupExtension` (`TranslateExtension`) to enable declarative, data-bound localization of UI strings directly in XAML. It allows developers to reference localized string resources by key (e.g., `{local:Translate Name}`) and automatically retrieve the appropriate localized value at runtime from the `StringResources` resource class. Its role is to bridge XAML markup with the application’s resource management system, supporting multi-language UI without requiring code-behind or manual string lookups.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2. **Public Interface**
|
|||
|
|
|
|||
|
|
#### `TranslateExtension` class
|
|||
|
|
- **Namespace**: `GroupList`
|
|||
|
|
- **Base class**: `System.Windows.Markup.MarkupExtension`
|
|||
|
|
- **Attributes**:
|
|||
|
|
- `[MarkupExtensionReturnType(typeof(string))]` — Indicates the extension returns a `string`.
|
|||
|
|
|
|||
|
|
##### Constructor
|
|||
|
|
- **`TranslateExtension(string key)`**
|
|||
|
|
Initializes a new instance with the specified resource key. The key is stored in the private readonly field `_key`.
|
|||
|
|
- *Parameter*: `key` — The string key used to look up a localized resource (e.g., `"Name"`, `"Description"`).
|
|||
|
|
- *Behavior*: Validates `key` is non-null/non-empty at *runtime* during `ProvideValue` (not in constructor).
|
|||
|
|
|
|||
|
|
##### Overridden Method
|
|||
|
|
- **`public override object ProvideValue(IServiceProvider serviceProvider)`**
|
|||
|
|
Returns the localized string for `_key`, or a fallback value if the key is missing or 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` (e.g., `"#stringnotfound# MissingKey"`).
|
|||
|
|
- *Note*: The `serviceProvider` parameter is unused in the implementation.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3. **Invariants**
|
|||
|
|
|
|||
|
|
- **Resource key must be a valid string resource name** (e.g., `"Name"`, `"Channels"`). Invalid keys (e.g., `"UnknownKey"`) will not throw but will return the fallback string `"#stringnotfound# UnknownKey"`.
|
|||
|
|
- **Case sensitivity**: Resource keys are case-sensitive (e.g., `"name"` ≠ `"Name"`).
|
|||
|
|
- **No runtime exceptions** are thrown for missing keys; the extension gracefully degrades to the `NotFound` prefix.
|
|||
|
|
- **Thread-safety**: Relies on `StringResources.ResourceManager`, which is thread-safe per .NET documentation (uses lazy initialization and locking internally).
|
|||
|
|
- **XAML-only usage**: Intended for use in XAML markup only; not designed for programmatic invocation outside markup extension context.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4. **Dependencies**
|
|||
|
|
|
|||
|
|
#### Dependencies *on* this module:
|
|||
|
|
- **WPF framework**: Requires `System.Windows.Markup` and `System.Windows` (for `MarkupExtension`).
|
|||
|
|
- **`StringResources` class**:
|
|||
|
|
- Defined in `GroupList.Resources` namespace.
|
|||
|
|
- Auto-generated from `.resx` files (not shown here, but implied by `StringResources.Designer.cs`).
|
|||
|
|
- Provides the underlying `ResourceManager` and strongly-typed properties (e.g., `StringResources.Name`).
|
|||
|
|
- **No external third-party dependencies** beyond .NET Framework 4.0+ (per runtime version in `StringResources.Designer.cs`).
|
|||
|
|
|
|||
|
|
#### Dependencies *of* this module:
|
|||
|
|
- None beyond standard WPF/.NET Framework types.
|
|||
|
|
- **Consumers**: Any XAML file in the `GroupList` module (e.g., `GroupList/Resources/TranslateExtension.cs` is likely used in `*.xaml` files in the same module) to localize UI elements.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5. **Gotchas**
|
|||
|
|
|
|||
|
|
- **No compile-time safety for keys**: Using an incorrect key (e.g., `"Nam"` instead of `"Name"`) will not cause a compile error—only a runtime fallback string (`#stringnotfound# Nam`).
|
|||
|
|
- **No culture switching support in extension itself**: While `StringResources.Culture` can be set globally (e.g., via `Thread.CurrentThread.CurrentUICulture`), the extension does not expose or manage culture selection.
|
|||
|
|
- **Hardcoded fallback string**: The `"#stringnotfound#"` prefix is fixed and may be visible to end-users if keys are missing.
|
|||
|
|
- **No validation of key format**: Keys like `""` (empty string) or `" "` (whitespace) are treated as invalid and return `NotFound`, but no explicit error logging occurs.
|
|||
|
|
- **Auto-generated resource class**: `StringResources.Designer.cs` is auto-generated; manual edits will be overwritten. Resource keys must match entries in the corresponding `.resx` file (not visible here).
|
|||
|
|
- **No support for parameterized strings**: The extension only supports simple key-based lookups (e.g., `"{local:Translate Name}"`). It cannot handle format strings like `"{0} is {1}"` (e.g., `String.Format`-style substitution).
|
|||
|
|
|
|||
|
|
None identified beyond the above.
|