FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add a `-UICulture` parameter to Get-Help to view help in a chosen language · Issue #28384 · PowerShell/PowerShell · GitHub

Repository navigation

Add a -UICulture parameter to Get-Help to view help in a chosen language #28384

Open

Description

Summary of the new feature / enhancement

As a user I want to specify the UI culture when running Get-Help, so that I can read help content in the language I choose, independently of my operating system's display language.

PowerShell's updatable help is asymmetric today:

  • Update-Help -UICulture <culture> and Save-Help -UICulture <culture> can install help content for any culture, side by side ($PSHOME\<culture>\, <module>\<culture>\).
  • Get-Help cannot view a specific culture. It always resolves content using the ambient thread UI culture (CultureInfo.CurrentUICulture), with the MUI fallback chain <current> -> parent cultures -> '' -> en-US -> en.

So help content a user installed in a second language is unreachable without changing the machine or session culture. Concrete pain points:

  1. Users on a non-English OS who prefer English help (or vice versa) have no supported switch. The only workaround is manually setting the whole thread culture ([System.Threading.Thread]::CurrentThread.CurrentUICulture = 'en-US'), which mutates the entire runspace, also changes the language of engine error messages, and is per-runspace.
  2. Authors and testers of localized modules or localized about_* topics cannot verify their content without switching their environment's culture.
  3. CI cannot exercise localized help in-process.

Scope note: comment-based help is single-language by design. -UICulture affects file-based help content: MAML XML help shipped by modules or installed via Update-Help, culture-specific about_* topics, and provider help. For a module that only ships comment-based help, the parameter has no visible effect. When the parameter is omitted, behavior is exactly as today.

Proposed technical implementation details (optional)

Example experience

# OS UI culture is de-DE; English help additionally installed with:
Update-Help -UICulture en-US

Get-Help Get-ChildItem                    # de-DE help (default, unchanged)
Get-Help Get-ChildItem -UICulture en-US   # en-US help, without touching the session culture
Get-Help about_Logging -UICulture en-US   # about topics resolve the same way
Get-Help Get-ChildItem -UICulture nl-NL   # nl-NL not installed -> falls back nl -> en-US -> en,
                                          # the same fallback chain used today

How the language is picked today

Get-Help cmdlet            (help/HelpCommands.cs, class GetHelpCommand)
   |
   v
HelpRequest                (help/HelpRequest.cs - carries target, category, filters...
   |                        but NO culture field)
   v
HelpSystem / providers     (help/HelpSystem.cs, *HelpProvider.cs)
   |
   v
MUIFileSearcher            (help/MUIFileSearcher.cs - HERE the culture is chosen:
   |                        reads CultureInfo.CurrentUICulture and searches
   v                        <culture>\, parent cultures, '', en-US\, en\)

The language decision happens implicitly, deep inside the engine. There is no way for the caller to influence it.

The new parameter

Added to GetHelpCommand, valid in all parameter sets:

/// <summary>
/// Gets or sets the UI culture of the help content to return.
/// When not specified, the current UI culture is used (existing behavior).
/// </summary>
[Parameter]
[ValidateNotNull]
[Alias("Language")]
public CultureInfo UICulture { get; set; }
  • Type System.Globalization.CultureInfo, matching the existing -UICulture parameters of Update-Help/Save-Help; 'en-US' strings bind natively.
  • No wildcards (Update-Help processes a set of cultures for bulk downloads; a single help lookup has no meaningful wildcard semantics).
  • Allowed in remote/restricted sessions: it is a pure content lookup, like -Name (unlike -Online/-ShowWindow).
  • -Language works as an alias for discoverability.

What changes, and where (all under src/System.Management.Automation/help/)

  1. HelpCommands.cs - GetHelpCommand gets the -UICulture parameter shown above and copies its value into the HelpRequest it already builds.
  2. HelpRequest.cs - new internal property CultureInfo RequestedUICulture. null means "use the ambient culture", so all existing call sites that build HelpRequest directly (e.g. GetHelpCodeMethods.GetHelpUri) are unaffected.
  3. MUIFileSearcher.cs - the static SearchFiles/LocateFile APIs gain an optional culture argument. The only change to the search itself: the fallback chain is built from the requested culture when one is present, otherwise from CultureInfo.CurrentUICulture as today. Chain order and the en-US/en fallback stay identical.
  4. HelpSystem.cs + providers - pass the request's culture down to the file searchers instead of relying on ambient culture.
  5. HelpRepository.cs - audit that cached help entries are keyed per culture, so a session mixing Get-Help calls in different cultures cannot serve stale or mixed-language content (regression test included).

One rule summarizes the design: if the request carries a culture, it wins for this one lookup; otherwise nothing changes.

Alternatives considered

  • Temporarily switching CultureInfo.CurrentUICulture inside the cmdlet - smallest diff, but mutating ambient thread state from a cmdlet is unsafe with concurrent/nested pipelines.
  • A script-level proxy function - impossible: the culture is read deep inside SMA's help engine, unreachable from script.

Tests

test/powershell/Modules/Microsoft.PowerShell.Utility/Get-Help.Tests.ps1, with a fixture module shipping a second culture's about_* topic (and ideally a small MAML help file):

  • requested culture is honored for command help and about topics;
  • fallback still ends in en-US/en when the requested culture is not installed;
  • omitting the parameter behaves identically to today;
  • mixed-culture calls in one session do not cross-contaminate results.

Related issues

(A search for an existing feature request for this turned up nothing - closest are the issues above.)

Activity

  1. added
    Issue-Enhancementthe issue is more of a feature request than a bug
    Needs-TriageThe issue is new and needs to be triaged by a work group.
    on Nov 10, 2026
  2. changed the title [-]Add a `-UICulture` parameter to Get-Help to view help in a chosen language[/-] [+]Add a -UICulture parameter to Get-Help to view help in a chosen language[/+] on Nov 10, 2026
  3. changed the title [-]Add a -UICulture parameter to Get-Help to view help in a chosen language[/-] [+]Add a `-UICulture` parameter to Get-Help to view help in a chosen language[/+] on Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Issue-Enhancementthe issue is more of a feature request than a bugNeeds-TriageThe issue is new and needs to be triaged by a work group.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions


      Back | FazBrowse Home | New Git URL