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

Abierto
#28,384 0 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
55/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
csharp, powershell

Línea de trabajo

Start with GetHelpCommand in src/System.Management.Automation/help/HelpCommands.cs and trace how HelpRequest reaches MUIFileSearcher; the issue names HelpRequest.cs, HelpSystem.cs, providers, and HelpRepository.cs as related paths. Read the existing culture fallback and cache behavior, then run the Get-Help tests in test/powershell/Modules/Microsoft.PowerShell.Utility/Get-Help.Tests.ps1. Done means requested cultures resolve for command and about help, fallback and omitted-parameter behavior remain intact, and mixed-culture calls do not cross-contaminate.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Issue-Enhancement Needs-Triage
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
  • #26724 - user with a Chinese OS wanting English help; no supported switch exists (closed as a support question, but demonstrates the demand).
  • #6217 - help files for cultures other than en-US.
  • #28274 / #21187 - adjacent HelpSystem caching/discovery issues the implementation must respect.

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

Lenguaje dominante
C#
Estrellas
56.1k
Forks
8.5k
Merge medio
12 h 33 min
PR fusionados (30 d)
73

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de PowerShell/PowerShell

Todos los issues de PowerShell/PowerShell

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.