| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Adds localization middleware to the Kestrun server. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Enables PowerShell-style localization using string table files (Messages.psd1). |
| | | 6 | | The middleware resolves the culture once per request and exposes localized strings via |
| | | 7 | | Context.LocalizedStrings (alias: Context.Strings) and the Localizer variable in route runspaces. |
| | | 8 | | .PARAMETER Options |
| | | 9 | | A Kestrun.Localization.KestrunLocalizationOptions instance. Overrides individual parameters. |
| | | 10 | | .PARAMETER DefaultCulture |
| | | 11 | | Default culture used when no match is found. Default is 'en-US'. |
| | | 12 | | .PARAMETER ResourcesBasePath |
| | | 13 | | Base path for localization resources. Default is 'i18n'. |
| | | 14 | | .PARAMETER FileName |
| | | 15 | | Localization file name. Default is 'Messages.psd1'. |
| | | 16 | | .PARAMETER QueryKey |
| | | 17 | | Query string key used to request a culture. Default is 'lang'. |
| | | 18 | | .PARAMETER CookieName |
| | | 19 | | Cookie name used to request a culture. Default is 'lang'. |
| | | 20 | | .PARAMETER DisableAcceptLanguage |
| | | 21 | | Disables Accept-Language header resolution when specified. |
| | | 22 | | .PARAMETER EnableQuery |
| | | 23 | | Enables query string resolution when specified. Default is false. |
| | | 24 | | .PARAMETER EnableCookie |
| | | 25 | | Enables cookie resolution when specified. Default is false. |
| | | 26 | | .PARAMETER SetDefaultThreadCulture |
| | | 27 | | When specified, sets the process-wide default thread culture |
| | | 28 | | (CultureInfo.DefaultThreadCurrentCulture and |
| | | 29 | | CultureInfo.DefaultThreadCurrentUICulture) once during application |
| | | 30 | | startup, using the configured DefaultCulture. |
| | | 31 | | This culture is used as a fallback for newly created threads that do |
| | | 32 | | not have an explicit CurrentCulture set. It does not change the culture |
| | | 33 | | of existing threads or runspaces and does not replace per-request |
| | | 34 | | culture handling. |
| | | 35 | | Default is false. |
| | | 36 | | .EXAMPLE |
| | | 37 | | Add-KrLocalizationMiddleware -ResourcesBasePath './Assets/i18n' |
| | | 38 | | .EXAMPLE |
| | | 39 | | $opts = [Kestrun.Localization.KestrunLocalizationOptions]::new() |
| | | 40 | | $opts.DefaultCulture = 'en-US' |
| | | 41 | | $opts.ResourcesBasePath = 'i18n' |
| | | 42 | | Add-KrLocalizationMiddleware -Options $opts -PassThru |
| | | 43 | | #> |
| | | 44 | | function Add-KrLocalizationMiddleware { |
| | | 45 | | [KestrunRuntimeApi('Definition')] |
| | | 46 | | [CmdletBinding(DefaultParameterSetName = 'Items')] |
| | | 47 | | param( |
| | | 48 | | [Parameter(Mandatory = $true, ParameterSetName = 'Options')] |
| | | 49 | | [Kestrun.Localization.KestrunLocalizationOptions]$Options, |
| | | 50 | | |
| | | 51 | | [Parameter(ParameterSetName = 'Items')] |
| | | 52 | | [ValidateScript({ |
| | 0 | 53 | | try { [void][System.Globalization.CultureInfo]::GetCultureInfo($_); $true } |
| | 0 | 54 | | catch { throw "Invalid culture name '$_'. Use a valid BCP 47 / .NET culture (e.g. en-US, zh-Hans, sr-Lat |
| | | 55 | | })] |
| | | 56 | | [string]$DefaultCulture = 'en-US', |
| | | 57 | | |
| | | 58 | | [Parameter(ParameterSetName = 'Items')] |
| | | 59 | | [string]$ResourcesBasePath = 'i18n', |
| | | 60 | | |
| | | 61 | | [Parameter(ParameterSetName = 'Items')] |
| | | 62 | | [string]$FileName = 'Messages.psd1', |
| | | 63 | | |
| | | 64 | | [Parameter(ParameterSetName = 'Items')] |
| | | 65 | | [string]$QueryKey = 'lang', |
| | | 66 | | |
| | | 67 | | [Parameter(ParameterSetName = 'Items')] |
| | | 68 | | [string]$CookieName = 'lang', |
| | | 69 | | |
| | | 70 | | [Parameter(ParameterSetName = 'Items')] |
| | | 71 | | [switch]$DisableAcceptLanguage, |
| | | 72 | | |
| | | 73 | | [Parameter(ParameterSetName = 'Items')] |
| | | 74 | | [switch]$EnableQuery, |
| | | 75 | | |
| | | 76 | | [Parameter(ParameterSetName = 'Items')] |
| | | 77 | | [switch]$EnableCookie, |
| | | 78 | | |
| | | 79 | | [Parameter(ParameterSetName = 'Items')] |
| | | 80 | | [switch]$SetDefaultThreadCulture |
| | | 81 | | ) |
| | | 82 | | # Ensure the server instance is resolved |
| | 0 | 83 | | $Server = Resolve-KestrunServer |
| | | 84 | | |
| | 0 | 85 | | if ($PSCmdlet.ParameterSetName -eq 'Items') { |
| | 0 | 86 | | $Options = [Kestrun.Localization.KestrunLocalizationOptions]::new() |
| | 0 | 87 | | $Options.DefaultCulture = $DefaultCulture |
| | 0 | 88 | | $Options.ResourcesBasePath = (Resolve-KrPath -Path $ResourcesBasePath -KestrunRoot) |
| | 0 | 89 | | $Options.FileName = $FileName |
| | 0 | 90 | | $Options.QueryKey = $QueryKey |
| | 0 | 91 | | $Options.CookieName = $CookieName |
| | | 92 | | |
| | 0 | 93 | | if ($PSBoundParameters.ContainsKey('DisableAcceptLanguage')) { $Options.EnableAcceptLanguage = -not $DisableAcce |
| | 0 | 94 | | if ($PSBoundParameters.ContainsKey('EnableQuery')) { $Options.EnableQuery = $EnableQuery.IsPresent } |
| | 0 | 95 | | if ($PSBoundParameters.ContainsKey('EnableCookie')) { $Options.EnableCookie = $EnableCookie.IsPresent } |
| | 0 | 96 | | if ($PSBoundParameters.ContainsKey('SetDefaultThreadCulture')) { $Options.SetDefaultThreadCulture = $SetDefaultT |
| | | 97 | | } else { |
| | 0 | 98 | | if ($null -eq $Options) { |
| | 0 | 99 | | throw 'Options cannot be null.' |
| | | 100 | | } |
| | | 101 | | try { |
| | 0 | 102 | | [void][System.Globalization.CultureInfo]::GetCultureInfo($Options.DefaultCulture) |
| | | 103 | | } catch { |
| | 0 | 104 | | throw "Invalid culture name '$($Options.DefaultCulture)'. Use a valid BCP 47 / .NET culture (e.g. en-US, zh- |
| | | 105 | | } |
| | | 106 | | } |
| | | 107 | | |
| | 0 | 108 | | $Server.AddLocalization($Options) | Out-Null |
| | | 109 | | } |
| | | 110 | | |