✨ [feat] Add localization-mode selection, on-demand cache validation docs, localized cache-summary rendering, module/help bumps, and tooling updates

- ✨ [feat] Runtime localization mode & env parsing
 - ✨ ColorScripts-Enhanced.psm1: introduce $script:LocalizationMode and parse COLOR_SCRIPTS_ENHANCED_LOCALIZATION_MODE (supports 'auto', 'full', 'embedded'); honor legacy toggles COLOR_SCRIPTS_ENHANCED_FORCE_LOCALIZATION and COLOR_SCRIPTS_ENHANCED_PREFER_EMBEDDED_MESSAGES.
 - ✨ ColorScripts-Enhanced.psm1: pass -UseDefaultCandidates to Initialize-ColorScriptsLocalization to enable the new fallback behavior when importing localization resources.

- ✨ [feat] Embedded-defaults preference & PSD1 probing
 - ✨ Private/Initialize-ColorScriptsLocalization.ps1: add -UseDefaultCandidates switch and $useDefaultCandidatesFlag; compute preferredCulture from CurrentUICulture and implement preferEmbeddedDefaults logic for 'Embedded' and 'Auto'+UseDefaultCandidates flows.
 - ✨ Private/Initialize-ColorScriptsLocalization.ps1: probe candidatePaths for Messages.psd1 (preferred culture chain + fallback en-US/en) and, when no localized resources exist and embedded defaults are preferred, set $script:Messages to the embedded defaults and populate LocalizationDetails.Source = 'EmbeddedDefaults' (with trace output).

- 🛠️ [fix] Localize and ANSI-color cache summaries
 - 🛠️ Public/New-ColorScriptCache.ps1 & Public/Clear-ColorScriptCache.ps1: read format strings from $script:Messages.CacheBuildSummaryFormat and CacheClearSummaryFormat (with sane fallbacks), format summary values, build an ANSI-colored summary segment via New-ColorScriptAnsiText (-Color 'Cyan') and pass that segment to Write-ColorScriptInformation for consistent, localizable output.

- 📝 [docs] Document -ValidateCache and localization modes
 - 📝 README.md, docs/Development.md, docs/MODULE_SUMMARY.md: add usage and guidance for forcing cache validation and for the new localization modes; recommend COLOR_SCRIPTS_ENHANCED_LOCALIZATION_MODE over legacy toggles.
 - 📝 en-US/Show-ColorScript.md & en-US help XML: add -ValidateCache parameter docs and guidance to force metadata validation before rendering; show examples and environment-variable usage (COLOR_SCRIPTS_ENHANCED_VALIDATE_CACHE).

- 🧹 [chore] Add cache-summary message keys to localized resources
 - 🧹 en-US + localized Messages.psd1 (de, es, fr, it, ja, nl, pt, ru, zh-CN): add CacheBuildSummaryFormat and CacheClearSummaryFormat entries so cache summaries can be localized/overridden via PSD1 files.

- 🔧 [build] Bump module manifest and localized help stamps; regenerate release artifacts
 - 🔧 ColorScripts-Enhanced.psd1: bump ModuleVersion => '2025.11.06.0250' and update Generated on stamp.
 - 🔧 localized HelpInfo.xml files (en-US, de, es, fr, it, ja, nl, pt, ru, zh-CN): synchronize UICultureVersion => '2025.11.06.0250'.
 - 🔧 dist/LatestReleaseNotes.md & dist/PowerShellGalleryReleaseNotes.md: regenerate release headers/content to reflect the changes.

- 🔧 [build] Formatting/tooling: add PowerShell Prettier plugin
 - 🔧 .prettierrc: enable "prettier-plugin-powershell" in the plugin list.
 - 🔧 package.json & package-lock.json: bump prettier-plugin-powershell to ^1.0.5 and update lockfile metadata.

- 🧪 [test] Align tests with signature changes
 - 🧪 Tests/ColorScripts-Enhanced.ModuleImportCoverage.Tests.ps1: update Initialize-ColorScriptsLocalization stubs to accept [switch]$UseDefaultCandidates and null-assign it to keep test stubs compatible with the new signature.

- 🧹 [chore] Minor wiring & consistency
 - 🧹 Ensure module import uses the new -UseDefaultCandidates flag so the embedded-defaults preference path is exercised during import initialization.

Signed-off-by: Nick2bad4u <[email protected]>

Author: Nick2bad4u

.prettierrc

@@ -127,6 +127,7 @@
         "prettier-plugin-interpolated-html-tags",
         "prettier-plugin-multiline-arrays",
         "prettier-plugin-jsdoc",
+        "prettier-plugin-powershell",
         "prettier-plugin-merge"
     ],
     "printWidth": 80,

ColorScripts-Enhanced/ColorScripts-Enhanced.psd1

@@ -3,15 +3,15 @@
 #
 # Generated by: Nick2bad4u
 #
-# Generated on: 11/5/2025
+# Generated on: 11/6/2025
 #
 
 @{
     # Script module or binary module file associated with this manifest.
     RootModule = 'ColorScripts-Enhanced.psm1'
 
     # Version number of this module.
-    ModuleVersion = '2025.11.05.2125'
+    ModuleVersion = '2025.11.06.0250'
 
     # Supported PSEditions
     CompatiblePSEditions = @('Desktop', 'Core')
@@ -211,7 +211,7 @@ PERFECT FOR
 
             # ReleaseNotes of this module
             ReleaseNotes = @'
-Version 2025.11.05.2125:
+Version 2025.11.06.0250:
 - Enhanced caching system with OS-wide cache in AppData
 - 6-19x performance improvement
 - Cache stored in centralized location

ColorScripts-Enhanced/ColorScripts-Enhanced.psm1

@@ -213,6 +213,23 @@ $cultureFallback += 'en-US'
 $cultureFallback += 'en'
 $cultureFallback = $cultureFallback | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -Unique
 
+$script:LocalizationMode = 'Auto'
+$localizationModeEnv = $env:COLOR_SCRIPTS_ENHANCED_LOCALIZATION_MODE
+if (-not [string]::IsNullOrWhiteSpace($localizationModeEnv)) {
+    switch -Regex ($localizationModeEnv.Trim()) {
+        '^(?i)(embedded|defaults?)$' { $script:LocalizationMode = 'Embedded'; break }
+        '^(?i)(full|files?|load|disk)$' { $script:LocalizationMode = 'Full'; break }
+        '^(?i)(auto)$' { $script:LocalizationMode = 'Auto'; break }
+        default { $script:LocalizationMode = 'Auto' }
+    }
+}
+elseif ($env:COLOR_SCRIPTS_ENHANCED_FORCE_LOCALIZATION -match '^(?i)(1|true|yes|full)$') {
+    $script:LocalizationMode = 'Full'
+}
+elseif ($env:COLOR_SCRIPTS_ENHANCED_PREFER_EMBEDDED_MESSAGES -match '^(?i)(1|true|yes|embedded)$') {
+    $script:LocalizationMode = 'Embedded'
+}
+
 $script:EmbeddedDefaultMessages = ConvertFrom-StringData @'
 # ColorScripts-Enhanced Localized Messages
 # English (en-US) - Default Language
@@ -267,6 +284,8 @@ StatusSkippedUpToDate = Skipped (up-to-date)
 StatusSkippedByUser = Skipped by user
 StatusFailed = Failed
 StatusUpToDateSkipped = Up-to-date (skipped)
+CacheBuildSummaryFormat = Cache build summary: Processed {0}, Updated {1}, Skipped {2}, Failed {3}
+CacheClearSummaryFormat = Cache clear summary: Removed {0}, Missing {1}, Skipped {2}, DryRun {3}, Errors {4}
 
 # Interactive Messages
 PressSpacebarToContinue = Press [Spacebar] to continue to next, [Q] to quit`n
@@ -307,7 +326,7 @@ else {
     Write-ModuleTrace ("Private script directory '{0}' was not found." -f $privateDirectory)
 }
 
-$localizationResult = Initialize-ColorScriptsLocalization -CandidateRoots ($moduleRootCandidates | Select-Object -Unique) -CultureFallbackOverride $cultureFallback
+$localizationResult = Initialize-ColorScriptsLocalization -CandidateRoots ($moduleRootCandidates | Select-Object -Unique) -CultureFallbackOverride $cultureFallback -UseDefaultCandidates
 if ($localizationResult -and $localizationResult.ModuleRoot) {
     $script:ModuleRoot = $localizationResult.ModuleRoot
 }

ColorScripts-Enhanced/Private/Initialize-ColorScriptsLocalization.ps1

@@ -1,11 +1,13 @@
 function Initialize-ColorScriptsLocalization {
     param(
         [string[]]$CandidateRoots,
-        [string[]]$CultureFallbackOverride
+        [string[]]$CultureFallbackOverride,
+        [switch]$UseDefaultCandidates
     )
 
     $null = $CandidateRoots
     $null = $CultureFallbackOverride
+    $useDefaultCandidatesFlag = $UseDefaultCandidates.IsPresent
 
     return Invoke-ModuleSynchronized $script:LocalizationSyncRoot {
         if ($script:LocalizationInitialized -and $script:Messages -and -not $CandidateRoots -and -not $CultureFallbackOverride) {
@@ -22,6 +24,32 @@ function Initialize-ColorScriptsLocalization {
             return $script:LocalizationDetails
         }
 
+        $localizationMode = if ($script:LocalizationMode) { $script:LocalizationMode } else { 'Auto' }
+        $preferredCulture = $null
+        if ($CultureFallbackOverride -and $CultureFallbackOverride.Count -gt 0) {
+            $preferredCulture = $CultureFallbackOverride[0]
+        }
+        else {
+            try {
+                $preferredCulture = [System.Globalization.CultureInfo]::CurrentUICulture.Name
+            }
+            catch {
+                $preferredCulture = $null
+            }
+        }
+
+        $preferEmbeddedDefaults = $false
+        if ($localizationMode -eq 'Embedded') {
+            $preferEmbeddedDefaults = $true
+        }
+        elseif ($localizationMode -eq 'Auto' -and $useDefaultCandidatesFlag) {
+            if ([string]::IsNullOrWhiteSpace($preferredCulture) -or $preferredCulture.StartsWith('en', [System.StringComparison]::OrdinalIgnoreCase)) {
+                $preferEmbeddedDefaults = $true
+            }
+        }
+
+        $preferredCultureDisplay = if ($preferredCulture) { $preferredCulture } else { 'n/a' }
+
         $uniqueCandidates = New-Object System.Collections.Generic.List[string]
         if ($CandidateRoots) {
             foreach ($candidate in $CandidateRoots) {
@@ -90,6 +118,106 @@ function Initialize-ColorScriptsLocalization {
             throw [System.InvalidOperationException]::new('Unable to resolve a module root for localization resources.')
         }
 
+        if ($preferEmbeddedDefaults) {
+            $cultureSearchOrder = New-Object System.Collections.Generic.List[string]
+            if ($CultureFallbackOverride -and $CultureFallbackOverride.Count -gt 0) {
+                foreach ($cultureName in $CultureFallbackOverride) {
+                    if ([string]::IsNullOrWhiteSpace($cultureName)) { continue }
+                    if (-not $cultureSearchOrder.Contains($cultureName)) {
+                        $null = $cultureSearchOrder.Add($cultureName)
+                    }
+                }
+            }
+            elseif (-not [string]::IsNullOrWhiteSpace($preferredCulture)) {
+                try {
+                    $cultureInfo = [System.Globalization.CultureInfo]::GetCultureInfo($preferredCulture)
+                }
+                catch {
+                    $cultureInfo = $null
+                }
+
+                while ($cultureInfo -and $cultureInfo.Name -and -not [string]::IsNullOrWhiteSpace($cultureInfo.Name)) {
+                    if (-not $cultureSearchOrder.Contains($cultureInfo.Name)) {
+                        $null = $cultureSearchOrder.Add($cultureInfo.Name)
+                    }
+
+                    if (-not $cultureInfo.Parent -or $cultureInfo.Parent.Name -eq $cultureInfo.Name) {
+                        break
+                    }
+
+                    $cultureInfo = $cultureInfo.Parent
+                }
+            }
+
+            foreach ($fallbackCulture in @('en-US', 'en')) {
+                if (-not [string]::IsNullOrWhiteSpace($fallbackCulture) -and -not $cultureSearchOrder.Contains($fallbackCulture)) {
+                    $null = $cultureSearchOrder.Add($fallbackCulture)
+                }
+            }
+
+            $localizedResourceExists = $false
+            foreach ($candidatePath in $candidatePaths) {
+                if ([string]::IsNullOrWhiteSpace($candidatePath)) { continue }
+
+                $probePaths = New-Object System.Collections.Generic.List[string]
+                $null = $probePaths.Add((Join-Path -Path $candidatePath -ChildPath 'Messages.psd1'))
+
+                foreach ($cultureName in $cultureSearchOrder) {
+                    $cultureProbe = Join-Path -Path $candidatePath -ChildPath $cultureName
+                    $null = $probePaths.Add((Join-Path -Path $cultureProbe -ChildPath 'Messages.psd1'))
+                }
+
+                foreach ($probe in ($probePaths | Select-Object -Unique)) {
+                    try {
+                        if (Test-Path -LiteralPath $probe -PathType Leaf) {
+                            $localizedResourceExists = $true
+                            break
+                        }
+                    }
+                    catch {
+                        continue
+                    }
+                }
+
+                if ($localizedResourceExists) { break }
+            }
+
+            if (-not $localizedResourceExists) {
+                $moduleRootCandidate = $null
+                if ($candidatePaths.Count -gt 0) {
+                    $moduleRootCandidate = $candidatePaths[0]
+                }
+
+                if (-not $moduleRootCandidate -and $script:ModuleRoot) {
+                    $moduleRootCandidate = $script:ModuleRoot
+                }
+                elseif (-not $moduleRootCandidate -and $PSScriptRoot) {
+                    try {
+                        $moduleRootCandidate = (Resolve-Path -LiteralPath $PSScriptRoot -ErrorAction Stop).ProviderPath
+                    }
+                    catch {
+                        $moduleRootCandidate = $PSScriptRoot
+                    }
+                }
+
+                $script:ModuleRoot = $moduleRootCandidate
+                $script:Messages = if ($script:EmbeddedDefaultMessages) { $script:EmbeddedDefaultMessages.Clone() } else { @{} }
+                $script:LocalizationInitialized = $true
+                $script:LocalizationDetails = [pscustomobject]@{
+                    LocalizedDataLoaded = $false
+                    ModuleRoot          = $moduleRootCandidate
+                    SearchedPaths       = $candidatePaths.ToArray()
+                    Source              = 'EmbeddedDefaults'
+                    FilePath            = $null
+                }
+
+                Write-ModuleTrace ("Localization using embedded defaults (mode: {0}, culture: {1})" -f $localizationMode, $preferredCultureDisplay)
+                return $script:LocalizationDetails
+            }
+
+            Write-ModuleTrace ("Embedded localization preference skipped; culture resources detected for {0}" -f $preferredCultureDisplay)
+        }
+
         $importSucceeded = $false
         $selectedRoot = $null
         $source = 'Import-LocalizedData'

ColorScripts-Enhanced/Public/Clear-ColorScriptCache.ps1

@@ -448,8 +448,18 @@ function Clear-ColorScriptCache {
         $output = $results.ToArray()
 
         if (-not $PassThru) {
-            $summaryMessage = [string]::Format('Cache clear summary – Removed: {0}, Missing: {1}, Skipped: {2}, DryRun: {3}, Errors: {4}', $summary.Removed, $summary.Missing, $summary.Skipped, $summary.DryRun, $summary.Errors)
-            Write-ColorScriptInformation -Message $summaryMessage -Quiet:$false
+            $formatString = $null
+            if ($script:Messages -and $script:Messages.ContainsKey('CacheClearSummaryFormat')) {
+                $formatString = $script:Messages.CacheClearSummaryFormat
+            }
+
+            if ([string]::IsNullOrWhiteSpace($formatString)) {
+                $formatString = 'Cache clear summary: Removed {0}, Missing {1}, Skipped {2}, DryRun {3}, Errors {4}'
+            }
+
+            $summaryMessage = $formatString -f $summary.Removed, $summary.Missing, $summary.Skipped, $summary.DryRun, $summary.Errors
+            $summarySegment = New-ColorScriptAnsiText -Text $summaryMessage -Color 'Cyan' -NoAnsiOutput:$false
+            Write-ColorScriptInformation -Message $summarySegment -Quiet:$false
         }
 
         return $output

ColorScripts-Enhanced/Public/New-ColorScriptCache.ps1

@@ -335,8 +335,18 @@ function New-ColorScriptCache {
         Write-Progress -Activity $activity -Completed -Status 'Completed'
 
         if (-not $PassThru -and $summary.Processed -gt 0) {
-            $summaryMessage = "Cache build summary: Processed {0}, Updated {1}, Skipped {2}, Failed {3}" -f $summary.Processed, $summary.Updated, $summary.Skipped, $summary.Failed
-            Write-ColorScriptInformation -Message $summaryMessage -Quiet:$false
+            $formatString = $null
+            if ($script:Messages -and $script:Messages.ContainsKey('CacheBuildSummaryFormat')) {
+                $formatString = $script:Messages.CacheBuildSummaryFormat
+            }
+
+            if ([string]::IsNullOrWhiteSpace($formatString)) {
+                $formatString = 'Cache build summary: Processed {0}, Updated {1}, Skipped {2}, Failed {3}'
+            }
+
+            $summaryMessage = $formatString -f $summary.Processed, $summary.Updated, $summary.Skipped, $summary.Failed
+            $summarySegment = New-ColorScriptAnsiText -Text $summaryMessage -Color 'Cyan' -NoAnsiOutput:$false
+            Write-ColorScriptInformation -Message $summarySegment -Quiet:$false
         }
 
         if ($PassThru) {

ColorScripts-Enhanced/README.md

@@ -347,6 +347,29 @@ Clear-ColorScriptCache -Name "aurora-*" -Confirm:$false
 
 > Tip: Set `COLOR_SCRIPTS_ENHANCED_CACHE_PATH` to redirect cache files to a custom directory for CI or ephemeral test runs.
 
+### Validate Cache on Demand
+
+```powershell
+# Rebuild cache metadata before rendering
+Show-ColorScript -Name "bars" -ValidateCache
+
+# Apply validation for the entire session
+$env:COLOR_SCRIPTS_ENHANCED_VALIDATE_CACHE = '1'
+Import-Module ColorScripts-Enhanced -Force
+```
+
+Use the `-ValidateCache` switch (or the `COLOR_SCRIPTS_ENHANCED_VALIDATE_CACHE` environment variable) whenever you suspect stale cache data or when testing new scripts.
+
+### Localization Modes
+
+Auto mode prefers PSD1 resources whenever they exist so you can override English strings without recompiling the module. Fine-tune the behaviour with `COLOR_SCRIPTS_ENHANCED_LOCALIZATION_MODE`:
+
+- `auto` *(default)* – load PSD1 files when present, otherwise fall back to embedded messages.
+- `full` – always load from disk, even if embedded defaults would succeed.
+- `embedded` – skip PSD1 probes and rely on built-in English messages.
+
+Legacy toggles `COLOR_SCRIPTS_ENHANCED_FORCE_LOCALIZATION` and `COLOR_SCRIPTS_ENHANCED_PREFER_EMBEDDED_MESSAGES` are still honoured, but the consolidated mode variable is recommended.
+
 ### Persist Defaults with Configuration
 
 ```powershell

ColorScripts-Enhanced/de/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>de</UICultureName>
-      <UICultureVersion>2025.11.05.2125</UICultureVersion>
+      <UICultureVersion>2025.11.06.0250</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>

ColorScripts-Enhanced/de/Messages.psd1

@@ -56,6 +56,8 @@ StatusSkippedUpToDate = Übersprungen (aktuell)
 StatusSkippedByUser = Vom Benutzer übersprungen
 StatusFailed = Fehlgeschlagen
 StatusUpToDateSkipped = Aktuell (übersprungen)
+CacheBuildSummaryFormat = Cache build summary: Processed {0}, Updated {1}, Skipped {2}, Failed {3}
+CacheClearSummaryFormat = Cache clear summary: Removed {0}, Missing {1}, Skipped {2}, DryRun {3}, Errors {4}
 
 # Interactive Messages
 PressSpacebarToContinue = Drücken Sie [Leertaste] um fortzufahren, [Q] zum Beenden`n

ColorScripts-Enhanced/docs/Development.md

@@ -513,6 +513,12 @@ Expect to see icons, checkmarks, and box-drawing characters. If they appear as s
 - Override cache location for testing/CI with `COLOR_SCRIPTS_ENHANCED_CACHE_PATH`
 - Use `New-ColorScriptCache` to warm caches during development
 - Use `Clear-ColorScriptCache` to troubleshoot stale outputs
+- Force validation when diagnosing cache issues with `Show-ColorScript -ValidateCache` or by setting `COLOR_SCRIPTS_ENHANCED_VALIDATE_CACHE=1`
+
+## Localization Controls
+
+- Auto mode prefers PSD1 resources when available; adjust behavior with `COLOR_SCRIPTS_ENHANCED_LOCALIZATION_MODE` (`auto`, `full`, `embedded`)
+- Legacy toggle `COLOR_SCRIPTS_ENHANCED_PREFER_EMBEDDED_MESSAGES` remains supported for compatibility, but prefer the consolidated mode variable going forward
 
 ## Branch Policy