73 lines
4.7 KiB
Markdown
73 lines
4.7 KiB
Markdown
|
---
|
||
|
|
source_files:
|
||
|
|
- DTS Viewer/DTS.Viewer.Modules/DTS.Viewer.ViewerSettings/Resources/TranslateExtension.cs
|
||
|
|
- DTS Viewer/DTS.Viewer.Modules/DTS.Viewer.ViewerSettings/Resources/StringResources.Designer.cs
|
||
|
|
generated_at: "2026-04-16T13:50:32.426485+00:00"
|
||
|
|
model: "zai-org/GLM-5-FP8"
|
||
|
|
schema_version: 1
|
||
|
|
sha256: "b58f3ee343f377b9"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Documentation: DTS.Viewer.ViewerSettings.Resources
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
This module provides localization infrastructure for the `DTS.Viewer.ViewerSettings` namespace. It consists of a strongly-typed resource accessor class (`StringResources`) generated from a `.resx` file, and a XAML markup extension (`TranslateExtension`) that allows UI elements to bind directly to localized strings using the resource keys. This separates user-facing text from code logic and supports multi-language deployments.
|
||
|
|
|
||
|
|
## 2. Public Interface
|
||
|
|
|
||
|
|
### `TranslateExtension`
|
||
|
|
**Location:** `DTS.Viewer.ViewerSettings`
|
||
|
|
**Inheritance:** `System.Windows.Markup.MarkupExtension`
|
||
|
|
|
||
|
|
A XAML markup extension used to resolve localized strings in the UI layer.
|
||
|
|
|
||
|
|
* **`TranslateExtension(string key)`**
|
||
|
|
* Constructor that accepts the resource key to be translated.
|
||
|
|
* **`object ProvideValue(IServiceProvider serviceProvider)`**
|
||
|
|
* Returns the localized string corresponding to the `_key`.
|
||
|
|
* Returns `#stringnotfound#` if the key is null or empty.
|
||
|
|
* Returns `#stringnotfound# {key}` if the lookup fails for a specific key.
|
||
|
|
|
||
|
|
### `StringResources`
|
||
|
|
**Location:** `DTS.Viewer.ViewerSettings.Resources`
|
||
|
|
**Attributes:** `internal`, Auto-generated
|
||
|
|
|
||
|
|
A strongly-typed resource class providing access to localized strings.
|
||
|
|
|
||
|
|
* **`static global::System.Resources.ResourceManager ResourceManager`**
|
||
|
|
* Returns the cached `ResourceManager` instance for this assembly.
|
||
|
|
* **`static global::System.Globalization.CultureInfo Culture`**
|
||
|
|
* Gets or sets the `CultureInfo` used for resource lookups. Overrides the current thread's `CurrentUICulture`.
|
||
|
|
* **`static string CalibrationBehavior_LinearIfAvailable`**
|
||
|
|
* Resource string: "Use the linear sensitivity, if available."
|
||
|
|
* **`static string CalibrationBehavior_NonLinearIfAvailable`**
|
||
|
|
* Resource string: "Use the non-linear sensitivity, if available."
|
||
|
|
* **`static string CalibrationBehavior_UseBothIfAvailable`**
|
||
|
|
* Resource string: "Use both sensitivities, if available, as separate channels."
|
||
|
|
* **`static string CalibrationBehaviorText`**
|
||
|
|
* Resource string: "Calibration Behavior".
|
||
|
|
|
||
|
|
## 3. Invariants
|
||
|
|
|
||
|
|
* **Non-Null Return:** `TranslateExtension.ProvideValue` always returns a string; it never returns null. It guarantees a fallback string if the resource is missing.
|
||
|
|
* **Fallback Format:** If a resource key is valid but not found, the return value follows the format `#stringnotfound# {key}`.
|
||
|
|
* **Empty Key Handling:** If the key passed to `TranslateExtension` is null or empty, the return value is exactly `#stringnotfound#` (without a trailing space or key name).
|
||
|
|
* **Visibility:** `StringResources` is marked `internal`, restricting access to within the assembly.
|
||
|
|
* **Code Generation:** `StringResources` is auto-generated; manual edits to the file will be overwritten by the tooling (ResGen/Visual Studio).
|
||
|
|
|
||
|
|
## 4. Dependencies
|
||
|
|
|
||
|
|
* **Internal Dependencies:**
|
||
|
|
* `TranslateExtension` depends on `StringResources` to perform the actual resource lookup via `StringResources.ResourceManager`.
|
||
|
|
* **External Framework Dependencies:**
|
||
|
|
* `System.Windows.Markup`: Required for `MarkupExtension` and `IServiceProvider` (WPF specific).
|
||
|
|
* `System.Resources`: Required for `ResourceManager`.
|
||
|
|
* `System.Globalization`: Required for `CultureInfo`.
|
||
|
|
* **File Dependencies:**
|
||
|
|
* `StringResources.Designer.cs` depends on an underlying `.resx` file (likely `StringResources.resx`) which contains the actual key-value pairs for the localized strings.
|
||
|
|
|
||
|
|
## 5. Gotchas
|
||
|
|
|
||
|
|
* **Culture Inconsistency:** `TranslateExtension` calls `StringResources.ResourceManager.GetString(_key)` without passing a culture argument. This relies on `Thread.CurrentUICulture`. However, `StringResources` exposes a static `Culture` property. If a developer sets `StringResources.Culture` explicitly, the strongly-typed properties (e.g., `CalibrationBehaviorText`) will respect it, but `TranslateExtension` will **ignore** it and continue using the thread's current UI culture.
|
||
|
|
* **Silent Failures:** The `TranslateExtension` does not throw exceptions for missing keys. Instead, it returns the error string `#stringnotfound#`. This is designed for debugging visibility but requires visual inspection of the UI to detect missing translations.
|
||
|
|
* **Designer File Edits:** Because `StringResources.Designer.cs` is auto-generated, developers must not add custom logic or properties directly to this class. Changes must be made in the corresponding `.resx` file.
|