about_Script_Internationalization

项目
10/06/2023

简短说明

介绍使脚本可以轻松地以其用户界面 (UI) 语言向用户显示消息和说明的脚本国际化功能。

长说明

PowerShell 脚本国际化功能可通过以用户的语言显示帮助和用户消息，更好地为世界各地的用户提供服务。

脚本国际化功能在执行过程中查询操作系统的 UI 区域性，导入相应的翻译文本字符串，并将其显示给用户。 Data 部分可以存储独立于代码的文本字符串，以便轻松识别和提取它们。新的 cmdlet ConvertFrom-StringData 将文本字符串转换为类似于字典的哈希表，以简化翻译。

为了支持国际帮助文本，PowerShell 包含以下功能：

Data 部分，用于分隔文本字符串与代码说明。有关 Data 部分的详细信息，请参阅 about_Data_Sections。
新的自动变量 $PSCulture 和 $PSUICulture。 $PSCulture 存储系统上用于日期、时间和货币等元素的 UI 语言的名称。 $PSUICulture 变量存储系统上用于用户界面元素（如菜单和文本字符串）的 UI 语言的名称。
cmdlet ConvertFrom-StringData，用于将文本字符串转换为类似于字典的哈希表，以简化翻译。有关详细信息，请参阅 ConvertFrom-StringData。
新文件类型 .psd1，用于存储已翻译的文本字符串。 .psd1 文件存储在脚本目录的语言特定子目录中。
cmdlet Import-LocalizedData，用于在运行时将指定语言的翻译文本字符串导入脚本。此 cmdlet 识别并导入任何 Windows 支持的语言中的字符串。有关详细信息，请参阅 Import-LocalizedData。

Data 部分：存储默认字符串

使用脚本中的 Data 部分以默认语言存储文本字符串。在 here-string 中排列键/值对中的字符串。每个键/值对必须位于单独的行上。如果包含注释，注释必须位于单独的行上。

ConvertFrom-StringData cmdlet 将 here-string 中的键/值对转换为存储在 Data 部分变量值中的类似字典的哈希表。

在以下示例中，World.ps1 脚本的 Data 部分包括脚本的英语-美国 (en-US) 提示消息集。 ConvertFrom-StringData cmdlet 将字符串转换为哈希表，并将其存储在 $msgtable 变量中。

$msgTable = Data {
    #culture="en-US"
    ConvertFrom-StringData @'
    helloWorld = Hello, World.
    errorMsg1 = You cannot leave the user name field blank.
    promptMsg = Please enter your user name.
'@
}

有关 here-string 的详细信息，请参阅 about_Quoting_Rules。

PSD1 文件：存储翻译后的字符串

将每个 UI 语言的脚本消息保存在与脚本及 .psd1 文件扩展名相同的单独文本文件中。将文件存储在脚本目录的子目录中，其区域性名称采用以下格式：

<language>-<region>

示例：de-DE、ar-SA 和 zh-Hans

例如，如果 World.ps1 脚本存储在 C:\Scripts 目录中，则会创建如下所示的文件目录结构：

C:\Scripts
C:\Scripts\World.ps1
C:\Scripts\de-DE\World.psd1
C:\Scripts\ar-SA\World.psd1
C:\Scripts\zh-CN\World.psd1
...

脚本目录 de-DE 子目录中的 World.psd1 文件可能包括以下语句：

ConvertFrom-StringData -StringData @'
helloWorld = Hallo, Welt.
errorMsg1 = Das Feld Benutzername darf nicht leer sein.
promptMsg = Geben Sie Ihren Benutzernamen ein.
'@

同样，脚本目录 ar-SA 子目录中的 World.psd1 文件可能包括以下语句：

ConvertFrom-StringData -StringData @'
helloWorld = مرحبًا أيها العالَم
errorMsg1 = لا يمكنك ترك حقل اسم المستخدم فارغًا
promptMsg = يرجى إدخال اسم المستخدم الخاص بك
'@

Import-LocalizedData：动态检索已翻译字符串

若要检索当前用户的 UI 语言中的字符串，请使用 Import-LocalizedData cmdlet。

Import-LocalizedData 查找 $PSUICulture 自动变量的值，并导入与 $PSUICulture 值匹配的子目录中 <script-name>.psd1 文件的内容。然后，它将导入的内容保存在由 BindingVariable 参数的值指定的变量中。

Import-LocalizedData -BindingVariable msgTable

例如，如果 Import-LocalizedData 命令出现在 C:\Scripts\World.ps1 脚本中，并且 $PSUICulture 的值为“ar-SA”，Import-LocalizedData 会找到以下文件：

C:\Scripts\ar-SA\World.psd1

然后，它将文件中的阿拉伯语文本字符串导入 $msgTable 变量，替换 World.ps1 脚本 Data 部分中可能定义的任何默认字符串。

因此，当脚本使用 $msgTable 变量显示用户消息时，这些消息会以阿拉伯语显示。

例如，以下脚本以阿拉伯语显示“请输入用户名”消息：

if (!($username)) { $msgTable.promptMsg }

如果 Import-LocalizedData 找不到与 $PSUIculture 值匹配的 .psd1 文件，则不会替换 $msgTable 的值，并且对 $msgTable.promptMsg 的调用将显示英语-美国字符串的回退。

示例

此示例演示如何在脚本中使用脚本国际化功能，以计算机上设置的语言向用户显示一周中的一天。

下面是 Sample1.ps1 脚本文件的完整列表。

该脚本以名为 Day ($Day) 的 Data 部分开头，其中包含 ConvertFrom-StringData 命令。提交到 ConvertFrom-StringData 的表达式是一个 here-string，其中包含键/值对中以默认 UI 区域 en-US 显示的日期名称。 ConvertFrom-StringData cmdlet 将 here-string 中的键/值对转换为哈希表，然后将其保存在 $Day 变量的值中。

Import-LocalizedData 命令将导入目录的 .psd1 文件中与 $PSUICulture 自动变量值匹配的内容，然后将其保存在 $Day 变量中，替换 Data 部分中定义的 $Day 值。

其余命令将字符串加载到数组中并显示它们。

$Day = Data {
#culture="en-US"
ConvertFrom-StringData -StringData @'
    messageDate = Today is
    d0 = Sunday
    d1 = Monday
    d2 = Tuesday
    d3 = Wednesday
    d4 = Thursday
    d5 = Friday
    d6 = Saturday
'@
}

Import-LocalizedData -BindingVariable Day

#Build an array of weekdays.
$a = $Day.d0, $Day.d1, $Day.d2, $Day.d3, $Day.d4, $Day.d5, $Day.d6

# Get the day of the week as a number (Monday = 1).
# Index into $a to get the name of the day.
# Use string formatting to build a sentence.

"{0} {1}" -f $Day.messageDate, $a[(Get-Date -UFormat %u)] | Out-Host

支持脚本的 .psd1 文件保存在脚本目录的子目录中，其名称与 $PSUICulture 值匹配。

下面是 .\de-DE\sample1.psd1 的完整列表：

# culture="de-DE"
ConvertFrom-StringData @'
    messageDate = Heute ist
    d0 = Sonntag
    d1 = Montag
    d2 = Dienstag
    d3 = Mittwoch
    d4 = Donnerstag
    d5 = Freitag
    d6 = Samstag
'@

因此，在 $PSUICulture 值为 de-DE 的系统上运行 Sample.ps1 时，脚本的输出为：

Heute ist Freitag

通过

about_Script_Internationalization

简短说明

长说明

Data 部分：存储默认字符串

PSD1 文件：存储翻译后的字符串

Import-LocalizedData：动态检索已翻译字符串

示例

另请参阅

其他资源