Import-LocalizedData
基于针对操作系统所选择的 UI 区域性,将特定于语言的数据导入脚本和函数。
语法
Import-LocalizedData
[[-BindingVariable] <String>]
[[-UICulture] <String>]
[-BaseDirectory <String>]
[-FileName <String>]
[-SupportedCommand <String[]>]
[<CommonParameters>]
说明
Import-LocalizedData cmdlet 可从子目录动态检索字符串,此子目录的名称与为操作系统的当前用户设置的 UI 语言相匹配。 它专门用于使脚本可以使用当前用户选择的 UI 语言来显示用户消息。
Import-LocalizedData 从脚本目录的特定于语言的子目录中的 .psd1 文件导入数据,并将其保存在命令中指定的局部变量中。 该 cmdlet 根据 $PSUICulture 自动变量的值选择子目录和文件。 当你使用脚本中的局部变量显示用户消息时,将以用户的 UI 语言显示该消息。
你可以使用 Import-LocalizedData 指定替代 UI 区域性、路径和文件名,以添加受支持的命令和取消在未找到 .psd1 文件时显示的错误消息。
Import-LocalizedData cmdlet 支持 Windows PowerShell 2.0 中引入的脚本国际化计划。 此计划旨在通过使脚本更易于使用当前用户的 UI 语言显示用户消息,来为全球用户提供更好的服务。 有关此计划以及 .psd1 文件的格式的详细信息,请参阅 about_Script_Internationalization。
示例
示例 1:导入文本字符串
PS C:\> Import-LocalizedData -BindingVariable "Messages"
此命令将文本字符串导入 $Messages 变量。 它使用其他所有 cmdlet 参数的默认值。
如果该命令包含在 C:\Test 目录中的 Archives.ps1 脚本中,并且 $PsUICulture 自动变量的值为 zh-CN,则 Import-LocalizedData 会将 C:\test\zh-CN 目录中的 Archives.psd1 文件导入 $Messages 变量。
示例 2:导入本地化数据字符串
PS C:\> Import-LocalizedData -FileName "Test.psd1" -UICulture "en-US"
Name Value
---- -----
Msg3 "Use $_ to represent the object that is being processed."
Msg2 "This command requires the credentials of a member of the Administrators group on the...
Msg1 "The Name parameter is missing from the command."
此命令在命令行处运行,而不是在脚本中运行。 它从 Test.psd1 文件中获取本地化的数据字符串,并将它们显示在命令行中。 由于未在脚本中使用该命令,因此 FileName 参数是必需的。 该命令使用 UICuture 参数指定 en-US 区域性。
Import-LocalizedData 返回包含本地化数据字符串的哈希表。
示例 3:导入 UI 区域性字符串
PS C:\> Import-LocalizedData -BindingVariable "MsgTbl" -UICulture "ar-SA" -FileName "Simple" -BaseDirectory "C:\Data\Localized"
此命令可将文本字符串导入脚本的 $MsgTbl 变量中。
它使用 UICulture 参数指示该 cmdlet 从 C:\Data\Localized 的 ar-SA 子目录中的 Simple.psd1 文件中导出数据。
示例 4:将本地化数据导入脚本
PS C:\> # In C:\Test\en-US\Test.psd1:
ConvertFrom-StringData @'
# English strings
Msg1 = "The Name parameter is missing from the command."
Msg2 = "This command requires the credentials of a member of the Administrators group on the computer."
Msg3 = "Use $_ to represent the object that is being processed."
'@
# In C:\Test\Test.ps1
Import-LocalizedData -BindingVariable "Messages"
Write-Host $Messages.Msg2
# In Windows PowerShell
PS C:\> .\Test.ps1
This command requires the credentials of a member of the Administrators group on the computer.
此示例显示如何在简单脚本中使用本地化数据。
该示例的第一部分演示 Test.psd1 文件的内容。 它包含将一系列已命名文本字符串转换为哈希表的 ConvertFrom-StringData 命令。 Test.psd1 文件位于包含该脚本的 C:\Test 目录的 en-US 子目录中。
该示例的第二部分演示 Test.ps1 脚本的内容。 它包含将数据从匹配 .psd1 文件导入 $Messages 变量的 Import-LocalizedData 命令,以及将 $Messages 变量中的一个消息写入主机程序的 Write-Host 命令。
示例的最后一部分将运行该脚本。 输出显示,它使用为操作系统的当前用户设置的 UI 语言显示正确的用户消息。
示例 5:替换脚本中的默认文本字符串
PS C:\> # In TestScript.ps1
$UserMessages = DATA
{ ConvertFrom-StringData @'
# English strings
Msg1 = "Enter a name."
Msg2 = "Enter your employee ID."
Msg3 = "Enter your building number."
'@ }
Import-LocalizedData -BindingVariable "UserMessages"
$UserMessages.Msg1...
此示例显示如何使用在 Import-LocalizedData 替换脚本的 DATA 节中定义的默认文本字符串。
在此示例中,TestScript.ps1 脚本的 DATA 节包含可将 DATA 节的内容转换为哈希表并存储在 $UserMessages 变量的值中的 ConvertFrom-StringData 命令。
此脚本还包括一个 Import-LocalizedData 命令,此命令可从由 $PsUICulture 变量的值指定的子目录中的 TestScript.psd1 文件中导入已转换的字符串。 如果该命令找到 .psd1 文件,则会将该文件中已转换的字符串保存在同一 $UserMessages 变量的值中,覆盖由 DATA 节逻辑保存的哈希表。
第三个命令显示 $UserMessages 变量中的第一条消息。
如果 Import-LocalizedData 命令找到 $PsUICulture 语言的 .psd1 文件,则 $UserMessages 变量的值将包含已转换的文本字符串。 如果出于任何原因命令失败,则该命令将显示在脚本的 DATA 节中定义的默认文本字符串。
示例 6:在找不到 UI 区域性时取消显示错误消息
PS C:\> # In Day1.ps1
Import-LocalizedData -BindingVariable "Day"
# In Day2.ps1
Import-LocalizedData -BindingVariable "Day" -ErrorAction:SilentlyContinue
PS C:\> .\Day1.ps1
Import-LocalizedData : Cannot find PowerShell data file 'Day1.psd1' in directory 'C:\ps-test\fr-BE\' or any parent culture directories.
At C:\ps-test\Day1.ps1:17 char:21+ Import-LocalizedData <<<< Day
Today is Tuesday PS C:\> .\Day2.ps1
Today is Tuesday
此示例演示如何取消显示在以下情况中出现的错误消息:Import-LocalizedData 无法找到与用户的 UI 区域性相匹配的目录或无法在这些目录中找到该脚本的 .psd1 文件。
可以使用值为 SilentlyContinue 的 ErrorAction 通用参数取消显示错误消息。 当你已使用默认或回退语言提供用户消息并且不需要错误消息时,此方法特别有用。
此示例将比较包含 Import-LocalizedData 命令的两个脚本:Day1.ps1 和 Day2.ps1。 这两个脚本完全相同,只不过 Day2 使用值为 SilentlyContinue 的 ErrorAction 通用参数。
示例输出显示在以下情况中运行这两个脚本的结果:UI 区域性设置为 fr-BE 并且该 UI 区域性没有对应的匹配文件或目录。 Day1.ps1 显示错误消息和英语输出。 Day2.ps1 仅显示英语输出。
参数
-BaseDirectory
指定 .psd1 文件所在的基目录。 默认值是脚本所在的目录。 Import-LocalizedData 可在基目录的特定于语言的子目录中搜索脚本的 .psd1 文件。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-BindingVariable
指定文本字符串要导入的变量。 输入不带有美元符号 ($) 的变量名称。
在 Windows PowerShell 2.0 中,此参数是必需的。 在 Windows PowerShell 3.0 中,此参数是必需的。 如果省略此参数,则 Import-LocalizedData 将返回文本字符串的哈希表。 此哈希表将沿着管道传递或在命令行中显示。
当你要使用 Import-LocalizedData 替换在脚本的 DATA 节中指定的默认文本字符串时,请将 DATA 节传递给一个变量,并在 BindingVariable 参数的值中输入 DATA 节变量的名称。 然后,当 Import-LocalizedData 将导入的内容保存在 BindingVariable 中时,导入的数据将替换默认文本字符串。 如果你不指定默认的文本字符串,则可以选择任何变量名称。
Type: | String |
Aliases: | Variable |
Position: | 0 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FileName
指定要导入的数据文件的名称 (.psd1)。 输入文件名。 你可以指定不包含 .psd1 文件扩展名的文件名,或者可以指定包含 .psd1 文件扩展名的文件名。 数据文件应保存为 Unicode 或 UTF-8。
当脚本中未使用 Import-LocalizedData 时,FileName 参数是必需的。 否则,该参数是可选的,并且默认值是脚本的基名称。 你可以使用此参数指示 Import-LocalizedData 搜索其他的 .psd1 文件。
例如,如果未提供 FileName 并且脚本名为 FindFiles.ps1,则 Import-LocalizedData 将搜索 FindFiles.psd1 数据文件。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SupportedCommand
指定仅生成数据的 cmdlet 和函数。
使用此参数以包含已写入或已测试的 cmdlet 和函数。 有关详细信息,请参阅 about_Script_Internationalization。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UICulture
指定替代 UI 区域性。 默认值为 $PsUICulture 自动变量的值。 以<语言>区域<>格式输入 UI 区域性,例如 en-US、de-DE 或 ar-SA。
UICulture 参数的值确定 Import-LocalizedData 从中获取脚本的 .psd1 文件的特定于语言的子目录(在基目录内)。
该 cmdlet 将搜索名称与 UICulture 参数或 $PsUICulture 自动变量的值相同的子目录,例如 de-DE 或 ar-SA。 如果它无法找到该目录,或者该目录不包含该脚本的 .psd1 文件,则它将搜索带有语言代码名的子目录,例如 de 或 ar。 如果它找不到子目录或 .psd1 文件,则该命令将失败,并且将使用脚本中指定的默认语言显示数据。
Type: | String |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
输入
None
不能通过管道将输入传递给此 cmdlet。
输出
Import-LocalizedData 将哈希表保存在由 BindingVariable 参数指定的变量中。
备注
在使用 Import-LocalizedData 前,请对你的用户消息进行本地化。 在包含键-值对的哈希表中对每个区域设置(UI 区域性)对应的消息进行格式设置,并将此哈希表保存在名称与脚本相同、文件扩展名为 .psd1 的文件中。 在脚本目录下为每个受支持的 UI 区域性创建目录,然后将每个 UI 区域性对应的 .psd1 文件保存在带有该 UI 区域性名称的目录中。
例如,对 de-DE 区域设置对应的用户消息进行本地化并在哈希表中对其进行格式设置。 将此哈希表保存在 <ScriptName>.psd1 文件中。 然后在脚本目录下创建一个 de-DE 子目录,并将 de-DE <ScriptName>.psd1 文件保存在 de-DE 子目录中。 为你支持的每个区域设置重复此方法。
Import-LocalizedData 对脚本对应的已本地化用户消息执行结构化搜索。
Import-LocalizedData 在脚本文件(或者 BaseDirectory 参数的值)所在的目录中开始搜索。 然后在基目录中搜索名称与 $PsUICulture 变量的值(或者 UICulture 参数的值)相同的子目录,例如 de-DE 或 ar-SA。 然后,它将在该子目录中搜索名称与该脚本(或 FileName 参数的值)相同的 .psd1 文件。
如果 Import-LocalizedData 找不到带有 UI 区域性名称的子目录,或者该子目录中不包含该脚本的 .psd1 文件,则它将在带有语言代码名的子目录中搜索该脚本的 .psd1 文件,例如 de 或 ar。 如果它找不到该子目录或 .psd1 文件,则命令将失败,将使用脚本中的默认语言显示数据,并且将显示一条说明无法导入数据的错误消息。 若要取消显示该消息并无声地指示失败,请使用值为 SilentlyContinue 的 ErrorAction 通用参数。
如果 Import-LocalizedData 找到子目录和 .psd1 文件,则会将用户消息的哈希表导入命令中的 BindingVariable 参数的值中。 然后,当你显示来自变量中的哈希表的消息时,将显示已本地化的消息。
有关详细信息,请参阅 about_Script_Internationalization (https://go.microsoft.com/fwlink/?LinkID=113262) 。