43 lines
3.6 KiB
Markdown
43 lines
3.6 KiB
Markdown
|
---
|
|||
|
|
source_files:
|
|||
|
|
- Common/DTS.Common/Strings/TranslateExtension.cs
|
|||
|
|
generated_at: "2026-04-16T02:52:05.025997+00:00"
|
|||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|||
|
|
schema_version: 1
|
|||
|
|
sha256: "73358136e74291bd"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Strings
|
|||
|
|
|
|||
|
|
## 1. Purpose
|
|||
|
|
`TranslateExtension` is a WPF `MarkupExtension` that enables declarative string localization in XAML by resolving resource keys to localized strings at runtime. It acts as a bridge between XAML markup and the application’s resource management system (`Strings.ResourceManager`), allowing UI elements to bind to localized text without requiring code-behind or view model properties. Its role is to simplify internationalization by enabling direct use of translation keys in XAML attributes (e.g., `Text="{local:Translate MyButtonLabel}"`).
|
|||
|
|
|
|||
|
|
## 2. Public Interface
|
|||
|
|
- **`TranslateExtension(string key)`**
|
|||
|
|
Constructor. Stores the resource key to be resolved. Throws no exceptions for `null`/empty keys—these are handled at runtime.
|
|||
|
|
- **`ProvideValue(IServiceProvider serviceProvider)`** *(overrides `MarkupExtension.ProvideValue`)*
|
|||
|
|
Resolves the stored `_key` to a localized string using `Strings.ResourceManager.GetString(_key)`. Returns the localized string if found; otherwise, returns `"#stringnotfound#"` (if `_key` is null/empty) or `"#stringnotfound# " + _key` (if `_key` is non-empty but not found).
|
|||
|
|
|
|||
|
|
## 3. Invariants
|
|||
|
|
- `_key` is immutable after construction (stored in a `readonly` field).
|
|||
|
|
- The extension *always* returns a `string` (per `[MarkupExtensionReturnType(typeof(string))]`).
|
|||
|
|
- If `_key` is `null` or empty, the return value is exactly `"#stringnotfound#"`.
|
|||
|
|
- If `_key` is non-empty but `Strings.ResourceManager.GetString(_key)` returns `null`, the return value is `"#stringnotfound# " + _key` (note the trailing space).
|
|||
|
|
- No validation is performed on `_key` beyond null/empty checks—invalid keys (e.g., containing spaces, special characters) are passed directly to `ResourceManager.GetString`.
|
|||
|
|
|
|||
|
|
## 4. Dependencies
|
|||
|
|
- **Depends on**:
|
|||
|
|
- `System.Windows.Markup.MarkupExtension` (base class)
|
|||
|
|
- `System` (for `string.IsNullOrEmpty`)
|
|||
|
|
- `DTS.Common.Strings.Strings.ResourceManager` (assumed to be a static `ResourceManager` instance; *not imported in this file but referenced in source*).
|
|||
|
|
- **Used by**:
|
|||
|
|
- XAML parsers (e.g., `XamlReader`, design-time/runtime XAML compilation) when encountering `{local:Translate ...}` markup extensions.
|
|||
|
|
- UI components that consume localized strings via XAML (e.g., `TextBlock.Text`, `Button.Content`).
|
|||
|
|
|
|||
|
|
## 5. Gotchas
|
|||
|
|
- **No fallback for missing keys**: The extension does *not* throw, log, or alert on missing keys—only returns a placeholder string. This may silently break UI text if keys are misspelled or resources are missing.
|
|||
|
|
- **Trailing space in error message**: The placeholder for missing keys includes a trailing space (`" #key"`), which may cause unintended whitespace in UI if not handled.
|
|||
|
|
- **No culture support exposed**: Uses `ResourceManager.GetString(string)` without specifying a `CultureInfo`, relying on the default behavior (typically the current UI culture). No mechanism to override culture per extension call.
|
|||
|
|
- **No caching**: Each `ProvideValue` call re-invokes `ResourceManager.GetString`, which *may* be inefficient if the same key is resolved frequently (though `ResourceManager` itself caches internally).
|
|||
|
|
- **No null-safety for `Strings.ResourceManager`**: If `Strings.ResourceManager` is `null` at runtime (e.g., due to initialization order), a `NullReferenceException` will occur.
|
|||
|
|
- **None identified from source alone** for additional edge cases beyond the above.
|