DP44/enriched-qwen3-coder-next/DataPRO/Modules/SystemSettings/ISOSettings/Resources.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/SystemSettings/ISOSettings/Resources/TranslateExtension.cs DataPRO/Modules/SystemSettings/ISOSettings/Resources/StringResources.Designer.cs	2026-04-16T04:42:04.078678+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.