init
This commit is contained in:
@@ -0,0 +1,100 @@
|
||||
---
|
||||
source_files:
|
||||
- DataPRO/Modules/SystemSettings/RealtimeSettings/Resources/TranslateExtension.cs
|
||||
- DataPRO/Modules/SystemSettings/RealtimeSettings/Resources/StringResources.Designer.cs
|
||||
generated_at: "2026-04-16T04:42:50.978478+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "2a6f478ba4a248f4"
|
||||
---
|
||||
|
||||
# Resources
|
||||
|
||||
## Documentation: `TranslateExtension` and `StringResources`
|
||||
|
||||
---
|
||||
|
||||
### 1. **Purpose**
|
||||
|
||||
This module provides localized string support for the `RealtimeSettings` UI layer in a WPF application. It consists of two tightly coupled components:
|
||||
- `TranslateExtension`, a XAML markup extension enabling declarative localization in XAML (e.g., `{local:Translate KeyName}`), and
|
||||
- `StringResources`, a strongly-typed, auto-generated resource class that wraps access to embedded string resources (`.resx`-backed).
|
||||
Together, they allow UI elements to display culture-sensitive text without hardcoding strings, supporting runtime language switching via `StringResources.Culture`.
|
||||
|
||||
---
|
||||
|
||||
### 2. **Public Interface**
|
||||
|
||||
#### `TranslateExtension` class
|
||||
- **Namespace**: `RealtimeSettings.Resources`
|
||||
- **Base class**: `System.Windows.Markup.MarkupExtension`
|
||||
- **Attributes**: `[MarkupExtensionReturnType(typeof(string))]`
|
||||
|
||||
| Member | Signature | Behavior |
|
||||
|--------|-----------|----------|
|
||||
| **Constructor** | `public TranslateExtension(string key)` | Stores the resource key (`_key`) for later lookup. Does not validate key format or existence. |
|
||||
| **ProvideValue** | `public override object ProvideValue(IServiceProvider serviceProvider)` | Returns the localized string for `_key` using `StringResources.ResourceManager.GetString(_key)`. If `_key` is `null`/empty or lookup fails, returns a fallback string (see *Invariants*). |
|
||||
|
||||
#### `StringResources` class
|
||||
- **Namespace**: `RealtimeSettings.Resources`
|
||||
- **Attributes**: `[GeneratedCode]`, `[DebuggerNonUserCode]`, `[CompilerGenerated]`
|
||||
- **Visibility**: `internal` (not public)
|
||||
|
||||
| Member | Signature | Behavior |
|
||||
|--------|-----------|----------|
|
||||
| **ResourceManager** | `internal static ResourceManager ResourceManager { get; }` | Lazily initializes and returns a `ResourceManager` for the `RealtimeSettings.Resources.StringResources` resource file (embedded in the assembly). |
|
||||
| **Culture** | `internal static CultureInfo Culture { get; set; }` | Gets/sets the UI culture used for resource lookups. Affects all subsequent `GetString` calls. |
|
||||
| **Static properties** | e.g., `internal static string DelayBetweenPolls { get; }` | Each property performs a `ResourceManager.GetString("KeyName")` call. Property names match resource keys (e.g., `"DelayBetweenPolls"`). |
|
||||
|
||||
**Notable string keys defined in `StringResources`**:
|
||||
- `DelayBetweenPolls`, `DelayBetweenPollsHelp`
|
||||
- `HighDelay`, `HighDelayHelp`
|
||||
- `LowDelay`, `LowDelayHelp`
|
||||
- `RealtimeSampleRate`, `RealtimeSampleRates`, `RealtimeSampleRateSliceIP`, `RealtimeSampleRateSliceUSB`, `RealtimeSampleRateTDASG5`
|
||||
- `SampleRate`, `SampleRateHelp`
|
||||
- `UseMeterModeHelp`, `UseMeterModeTableStyle`
|
||||
|
||||
---
|
||||
|
||||
### 3. **Invariants**
|
||||
|
||||
- **Key validation**:
|
||||
- If `_key` passed to `TranslateExtension` is `null` or empty (`""`), `ProvideValue` returns `"#stringnotfound#"`.
|
||||
- If `StringResources.ResourceManager.GetString(_key)` returns `null` (key not found), `ProvideValue` returns `"#stringnotfound# " + _key` (e.g., `"#stringnotfound# MissingKey"`).
|
||||
- **Resource key consistency**:
|
||||
- `StringResources` properties are generated from keys in the `.resx` file. The key used in `TranslateExtension(key)` must exactly match the resource name (e.g., `"DelayBetweenPolls"`), including case.
|
||||
- **Thread-safety**:
|
||||
- `StringResources.ResourceManager` is thread-safe (uses `Lazy<T>`-like pattern via `ReferenceEquals` check).
|
||||
- `StringResources.Culture` is *not* thread-safe; concurrent writes may cause race conditions.
|
||||
- **Fallback behavior**:
|
||||
- No exception is thrown for missing keys—only fallback strings. This avoids runtime crashes but may result in visible placeholder text.
|
||||
|
||||
---
|
||||
|
||||
### 4. **Dependencies**
|
||||
|
||||
#### **Depends on**
|
||||
- `System.Windows.Markup` (for `MarkupExtension` base class)
|
||||
- `System.Resources` (via `ResourceManager`)
|
||||
- `System.Globalization` (for `CultureInfo`)
|
||||
- `System.CodeDom.Compiler`, `System.Diagnostics`, `System.Runtime.CompilerServices` (auto-generated attributes)
|
||||
- **Embedded resource**: `RealtimeSettings.Resources.StringResources.resources` (compiled from `StringResources.resx`)
|
||||
|
||||
#### **Depended on by**
|
||||
- **WPF XAML files** in the `RealtimeSettings` module (e.g., `*.xaml` pages) using `{local:Translate KeyName}` syntax.
|
||||
- **UI code-behind** may directly access `StringResources` properties (e.g., `StringResources.DelayBetweenPolls`) for non-XAML localization.
|
||||
- **No other modules** appear to depend on this (based on namespace isolation: `RealtimeSettings.Resources`).
|
||||
|
||||
---
|
||||
|
||||
### 5. **Gotchas**
|
||||
|
||||
- **Hardcoded fallback prefix**: The `"#stringnotfound#"` prefix is hardcoded in `TranslateExtension`—not configurable or localized itself.
|
||||
- **No null-safety for `serviceProvider`**: `ProvideValue` does not validate `serviceProvider` (though WPF always provides one during XAML parsing).
|
||||
- **Case sensitivity**: Resource keys are case-sensitive. A typo like `"delaybetweenpolls"` (lowercase) will fail lookup.
|
||||
- **Designer file warnings**: `StringResources.Designer.cs` explicitly warns that manual changes are lost on regeneration. Modifying `.resx` requires rebuilding to sync `StringResources`.
|
||||
- **Culture persistence**: `StringResources.Culture` only affects *new* lookups; existing `TranslateExtension` instances retain the culture at instantiation time (since `ProvideValue` is called at XAML parse time).
|
||||
- **No support for pluralization/formatting**: `TranslateExtension` only returns raw strings. Placeholders (e.g., `{0}`) are possible in `.resx` but must be manually handled in XAML (e.g., `String.Format` in code-behind).
|
||||
- **No localization for non-string resources**: Only strings are supported; no support for images, icons, etc.
|
||||
|
||||
None identified beyond these.
|
||||
Reference in New Issue
Block a user