107 lines
6.0 KiB
Markdown
107 lines
6.0 KiB
Markdown
---
|
|
source_files:
|
|
- DTS Viewer/DTS.Viewer/Resources/TranslateExtension.cs
|
|
- DTS Viewer/DTS.Viewer/Resources/StringResources.Designer.cs
|
|
generated_at: "2026-04-16T11:23:12.329617+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "dbbc3094853fd65f"
|
|
---
|
|
|
|
# Documentation: DTS.Viewer.Resources Localization Module
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides localization/internationalization support for the DTS Viewer WPF application. It enables XAML-based string lookup through a markup extension pattern, allowing UI elements to bind to localized resources declaratively. The `TranslateExtension` class serves as a bridge between XAML markup and the underlying `StringResources` resource manager, while `StringResources` provides strongly-typed, auto-generated access to localized strings stored in compiled resource files (.resx).
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### `TranslateExtension` (Class)
|
|
**Namespace:** `DTS.Viewer`
|
|
**Attributes:** `[MarkupExtensionReturnType(typeof(string))]`
|
|
|
|
A WPF markup extension that resolves localization keys to their corresponding string values at runtime.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| Constructor | `TranslateExtension(string key)` | Initializes the extension with the resource key to look up. Stores the key in a readonly field `_key`. |
|
|
| `ProvideValue` | `public override object ProvideValue(IServiceProvider serviceProvider)` | Returns the localized string for the provided key. Returns `NotFound` constant if key is null/empty, or `NotFound + " " + _key` if the key is not found in resources. |
|
|
| `NotFound` | `private const string NotFound = "#stringnotfound#"` | Fallback string returned when a key is invalid or missing. |
|
|
|
|
---
|
|
|
|
### `StringResources` (Class)
|
|
**Namespace:** `DTS.Viewer.Resources`
|
|
**Accessibility:** `internal`
|
|
**Attributes:** `[GeneratedCode]`, `[DebuggerNonUserCode]`, `[CompilerGenerated]`
|
|
|
|
An auto-generated strongly-typed resource class providing access to localized strings.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `ResourceManager` | `internal static global::System.Resources.ResourceManager ResourceManager { get; }` | Lazily-initialized, cached `ResourceManager` instance for the `DTS.Viewer.Resources.StringResources` resource bundle. |
|
|
| `Culture` | `internal static global::System.Globalization.CultureInfo Culture { get; set; }` | Gets or sets the current UI culture for resource lookups. Overrides `Thread.CurrentUICulture` for this resource class. |
|
|
|
|
**Localized String Properties (all `internal static string`):**
|
|
|
|
| Property | Default Value (from comments) |
|
|
|----------|-------------------------------|
|
|
| `ChartOptionsHeader` | "Chart Options" |
|
|
| `GraphsDefaultTitle` | "Graphs " |
|
|
| `ModificationsHeader` | "Modify" |
|
|
| `SavePDFError` | "Error occurred saving chart to PDF" |
|
|
| `SavePDFSuccess` | "Chart saved succesfully as {0}{1} and {2}{3}" |
|
|
| `SettingsTitle` | "Settings" |
|
|
| `TestIDsDefaultTitle` | "Test IDs" |
|
|
| `TestsDefaultTitle` | "Tests " |
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
1. **Key immutability:** The `_key` field in `TranslateExtension` is `readonly` and set only at construction time.
|
|
|
|
2. **Null safety:** `ProvideValue` will never return null. It returns either the localized string, `NotFound` (for null/empty keys), or `NotFound + " " + _key` (for missing keys).
|
|
|
|
3. **ResourceManager singleton:** The `ResourceManager` property uses a check-then-create pattern with a temporary variable to ensure thread-safe lazy initialization.
|
|
|
|
4. **Resource name mapping:** The `ResourceManager` is initialized with the base name `"DTS.Viewer.Resources.StringResources"`, which must match the embedded resource path.
|
|
|
|
5. **Culture fallback:** If `Culture` property is not explicitly set (`resourceCulture` is null), `ResourceManager.GetString` uses the current thread's `CurrentUICulture`.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### This module depends on:
|
|
- `System` (core .NET types)
|
|
- `System.Windows.Markup` - for `MarkupExtension` base class and `MarkupExtensionReturnTypeAttribute`
|
|
- `System.Resources` - for `ResourceManager` class
|
|
- `System.Globalization` - for `CultureInfo` class
|
|
- `System.CodeDom.Compiler`, `System.Diagnostics`, `System.Runtime.CompilerServices` - for auto-generated attributes
|
|
- **Resource files (.resx)** - The actual localized string data backing `StringResources` (not included in source, but implied by the designer file)
|
|
|
|
### What depends on this module:
|
|
- **XAML files in DTS.Viewer** - Use `{x:Static res:StringResources.PropertyName}` or `{local:Translate KeyName}` syntax for localized strings
|
|
- **PDF export functionality** - Uses `SavePDFSuccess` and `SavePDFError` strings
|
|
- **Chart/Graph UI components** - Use `ChartOptionsHeader`, `GraphsDefaultTitle`, `ModificationsHeader`
|
|
- **Settings UI** - Uses `SettingsTitle`
|
|
- **Test-related UI** - Uses `TestIDsDefaultTitle`, `TestsDefaultTitle`
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **`StringResources` is `internal`:** The class cannot be accessed from outside the `DTS.Viewer` assembly. External libraries cannot directly use these resources.
|
|
|
|
2. **Missing key behavior:** Missing localization keys do not throw exceptions. Instead, they return `"#stringnotfound# {key}"`, which may appear in production UI if resources are misconfigured. This is intentional fallback behavior but could mask configuration errors.
|
|
|
|
3. **Typo in resource string:** The `SavePDFSuccess` resource contains "succesfully" (missing one 'l') per the source comments. This typo originates from the .resx file, not the generated code.
|
|
|
|
4. **Trailing spaces:** `GraphsDefaultTitle` and `TestsDefaultTitle` have trailing spaces in their default values ("Graphs " and "Tests "). This may be intentional for UI layout but could cause issues if trimmed unexpectedly.
|
|
|
|
5. **Format string dependency:** `SavePDFSuccess` expects 4 format arguments (`{0}{1} and {2}{3}`). Callers must provide exactly 4 arguments or a `FormatException` will occur at runtime.
|
|
|
|
6. **Auto-generated file warning:** `StringResources.Designer.cs` is regenerated by tooling. Manual edits will be lost. The underlying `.resx` file is the source of truth. |