132 lines
6.9 KiB
Markdown
132 lines
6.9 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/Modules/SystemSettings/ISOSettings/Resources/TranslateExtension.cs
|
||
- DataPRO/Modules/SystemSettings/ISOSettings/Resources/StringResources.Designer.cs
|
||
generated_at: "2026-04-16T04:42:04.078678+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "fa1be3ee1b42a3c2"
|
||
---
|
||
|
||
# Resources
|
||
|
||
## Documentation: `TranslateExtension` and `StringResources`
|
||
|
||
---
|
||
|
||
### 1. **Purpose**
|
||
|
||
This module provides localized string resolution for WPF UI elements within the `ISOSettings` module. It enables declarative binding of localized text in XAML via the `TranslateExtension` markup extension, which retrieves strings from the strongly-typed `StringResources` resource class. The module acts as a bridge between WPF’s XAML rendering pipeline and the application’s embedded resource strings, supporting internationalization (i18n) by allowing UI text to be translated without hardcoding values.
|
||
|
||
---
|
||
|
||
### 2. **Public Interface**
|
||
|
||
#### `TranslateExtension` class
|
||
- **Namespace**: `ISOSettings.Resources`
|
||
- **Inherits**: `MarkupExtension` (from `System.Windows.Markup`)
|
||
- **Purpose**: A WPF markup extension used in XAML to fetch localized strings at runtime.
|
||
|
||
##### Constructor
|
||
- `public TranslateExtension(string key)`
|
||
- Initializes the extension with a resource key (`_key`).
|
||
- Throws no exceptions; invalid keys are handled gracefully at `ProvideValue` time.
|
||
|
||
##### Method
|
||
- `public override object ProvideValue(IServiceProvider serviceProvider)`
|
||
- **Behavior**:
|
||
- Returns `"#stringnotfound#"` if `_key` is `null` or empty.
|
||
- Otherwise, retrieves the localized string via `StringResources.ResourceManager.GetString(_key)`.
|
||
- If the string is not found (`null`), returns `"#stringnotfound# <key>"`.
|
||
- **Parameters**:
|
||
- `serviceProvider`: Used by WPF to resolve services (e.g., `IProvideValueTarget`), but not used in the implementation.
|
||
- **Return type**: `object` (castable to `string`).
|
||
|
||
#### `StringResources` class
|
||
- **Namespace**: `ISOSettings.Resources`
|
||
- **Purpose**: Auto-generated strongly-typed resource class for accessing embedded localized strings.
|
||
- **Note**: This class is **not public** (`internal`), and its members are only used internally by `TranslateExtension`.
|
||
- **Key members**:
|
||
- `internal static ResourceManager ResourceManager { get; }`
|
||
- Lazily initializes and returns a `System.Resources.ResourceManager` for the `"ISOSettings.Resources.StringResources"` base name.
|
||
- `internal static CultureInfo Culture { get; set; }`
|
||
- Allows overriding the UI culture for resource lookups (e.g., for testing or dynamic language switching).
|
||
- **Static properties** (examples):
|
||
- `internal static string AllowNonISO { get; }`
|
||
- `internal static string ChannelNamesOnly { get; }`
|
||
- `internal static string ISOOnly { get; }`
|
||
- `internal static string ISOSupportLevel { get; }`
|
||
- `internal static string NoISO { get; }`
|
||
- `internal static string RequireUniqueISOCodes { get; }`
|
||
- `internal static string ShowChannelCodeLookupHelper { get; }`
|
||
- `internal static string ShowISOCodes { get; }`
|
||
- `internal static string ShowISOStringBuilder { get; }`
|
||
- `internal static string ShowUserCodes { get; }`
|
||
- `internal static string SupportTransitional { get; }`
|
||
- `internal static string Transitory { get; }`
|
||
- `internal static string UseISOCodeFilterMapping { get; }`
|
||
- `internal static string UseUserCodes { get; }`
|
||
- `internal static string ValidateTestObjectAndPositionFields { get; }`
|
||
- Each property calls `ResourceManager.GetString(key, resourceCulture)` for its respective key (e.g., `"AllowNonISO"`).
|
||
|
||
---
|
||
|
||
### 3. **Invariants**
|
||
|
||
- **`_key` immutability**: Once set in the constructor, `_key` is never modified.
|
||
- **Fallback behavior**:
|
||
- Missing keys **always** return `"#stringnotfound#"` (empty key) or `"#stringnotfound# <key>"` (key not found in resources).
|
||
- No exceptions are thrown for missing keys or invalid input.
|
||
- **Thread-safety of `ResourceManager`**:
|
||
- The `ResourceManager` instance is lazily initialized and cached in a static field.
|
||
- `ResourceManager` is thread-safe for concurrent reads (per .NET documentation), but `Culture` setter is not explicitly synchronized.
|
||
- **Resource key consistency**:
|
||
- The keys used in `TranslateExtension` must match the property names in `StringResources` (e.g., `"AllowNonISO"`). Mismatches will trigger the fallback string.
|
||
|
||
---
|
||
|
||
### 4. **Dependencies**
|
||
|
||
#### **Depends on**
|
||
- `System.Windows.Markup.MarkupExtension` (WPF framework)
|
||
- `System.Resources.ResourceManager`
|
||
- `System.Globalization.CultureInfo`
|
||
- `System` (core types)
|
||
- `ISOSettings.Resources.StringResources` (strongly-typed resource class, same assembly)
|
||
|
||
#### **Used by**
|
||
- XAML files in the `ISOSettings` module (e.g., `*.xaml` files using `{local:Translate KeyName}`).
|
||
- Any UI component requiring localized strings (e.g., settings dialogs, labels, tooltips).
|
||
- *Not* used by non-UI or backend logic directly (resource access for non-XAML code should use `StringResources` directly).
|
||
|
||
---
|
||
|
||
### 5. **Gotchas**
|
||
|
||
- **No culture switching support in `TranslateExtension`**:
|
||
- The extension does not respect dynamic changes to `StringResources.Culture`. If the UI culture changes at runtime, the extension will not re-resolve strings unless the UI element is reloaded (e.g., via data binding refresh).
|
||
- *Workaround*: Bind to a property that raises `INotifyPropertyChanged` and re-creates the extension (not ideal).
|
||
|
||
- **Hardcoded fallback string**:
|
||
- `"#stringnotfound#"` is a visible placeholder in the UI if a key is missing. This is intentional for debugging but may confuse end users.
|
||
|
||
- **No validation of resource keys at compile time**:
|
||
- Typos in XAML (e.g., `{local:Translate Key="AllowNonISOo"}`) will silently fall back to `"#stringnotfound# AllowNonISOo"`.
|
||
- *Recommendation*: Use source-generated or compile-time-checked alternatives (e.g., `x:Static`) where possible.
|
||
|
||
- **Auto-generated resource class**:
|
||
- `StringResources.Designer.cs` is regenerated on build. Manual edits will be lost.
|
||
- Resource keys must be added/modified in the `.resx` file (not in the `.Designer.cs` file).
|
||
|
||
- **`IServiceProvider` unused**:
|
||
- The `serviceProvider` parameter in `ProvideValue` is ignored. This is acceptable for simple string resolution but prevents advanced scenarios (e.g., resolving context-aware translations).
|
||
|
||
- **No null-check on `ResourceManager.GetString()` result beyond `null`**:
|
||
- If `GetString()` returns an empty string (`""`), it is treated as valid (not replaced with fallback). This may be intentional or a bug depending on requirements.
|
||
|
||
- **No localization for non-WPF contexts**:
|
||
- This module is WPF-specific. Non-XAML code (e.g., console, tests) must use `StringResources` directly.
|
||
|
||
---
|
||
|
||
*Documentation generated from source files only. No external behavior or assumptions beyond the provided code.* |