Import-LocalizedData

模块:

Microsoft.PowerShell.Utility

基于针对操作系统所选择的 UI 区域性，将特定于语言的数据导入脚本和函数。

语法

Import-LocalizedData
      [[-BindingVariable] <String>]
      [[-UICulture] <String>]
      [-BaseDirectory <String>]
      [-FileName <String>]
      [-SupportedCommand <String[]>]
      [<CommonParameters>]

说明

cmdlet Import-LocalizedData 从子目录中动态检索字符串，该子目录中的名称与操作系统当前用户设置的 UI 语言匹配。 它专门用于使脚本可以使用当前用户选择的 UI 语言来显示用户消息。

Import-LocalizedData 从 .psd1 脚本目录的特定于语言的子目录中的文件导入数据，并将其保存在 命令中指定的局部变量中。 cmdlet 根据自动变量的值 $PSUICulture 选择子目录和文件。 当你使用脚本中的局部变量显示用户消息时，将以用户的 UI 语言显示该消息。

可以使用 的参数 Import-LocalizedData 指定备用 UI 区域性、路径和文件名，以添加支持的命令，以及禁止在找不到文件时 .psd1 显示的错误消息。

cmdlet Import-LocalizedData 支持 Windows PowerShell 2.0 中引入的脚本国际化计划。 此计划旨在通过使脚本更易于使用当前用户的 UI 语言显示用户消息，来为全球用户提供更好的服务。 有关此内容和 .psd1 文件格式的详细信息，请参阅 about_Script_Internationalization。

示例

示例 1：导入文本字符串

此示例将文本字符串 $Messages 导入 变量。 它使用其他所有 cmdlet 参数的默认值。

Import-LocalizedData -BindingVariable "Messages"

如果命令包含在目录中的 Archives.ps1 脚本中 C:\Test ，并且自动变量的 $PsUICulture 值为 zh-CN， Import-LocalizedData 则 Archives.psd1 会将 目录中的文件 C:\test\zh-CN 导入到 变量中 $Messages 。

示例 2：导入本地化数据字符串

此示例在命令行上运行，而不是在脚本中运行。 它从 Test.psd1 文件中获取本地化的数据字符串，并将它们显示在命令行中。 由于未在脚本中使用该命令，因此 FileName 参数是必需的。 该命令使用 UICuture 参数指定 en-US 区域性。

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."

Import-LocalizedData 返回包含本地化数据字符串的哈希表。

示例 3：导入 UI 区域性字符串

Import-LocalizedData -BindingVariable "MsgTbl" -UICulture "ar-SA" -FileName "Simple" -BaseDirectory "C:\Data\Localized"

此命令将文本字符串 $MsgTbl 导入脚本的 变量。

它使用 UICulture 参数指示 cmdlet 从 Simple.psd1ar-SA 的 子目录中的文件 C:\Data\Localized导入数据。

示例 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 。 它包含将数据 Import-LocalizedData 从匹配 .psd1 文件 $Messages 导入变量的命令，以及一个 Write-Host 将变量中的 $Messages 一条消息写入主机程序的命令。

示例的最后一部分将运行该脚本。 输出显示，它使用为操作系统的当前用户设置的 UI 语言显示正确的用户消息。

示例 5：替换脚本中的默认文本字符串

此示例演示如何使用 Import-LocalizedData 替换脚本的 DATA 节中定义的默认文本字符串。

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...

在此示例中，TestScript.ps1 脚本的 DATA 节包含一个 ConvertFrom-StringData 命令，该命令将 DATA 节的内容转换为哈希表，并存储在 变量的值 $UserMessages 中。

该脚本还包括一个 Import-LocalizedData 命令，该命令从变量的值指定的子目录中的 TestScript.psd1 文件中导入已翻译文本字符串的 $PsUICulture 哈希表。 如果命令找到 .psd1 该文件，它会将文件中已翻译的字符串保存在同一 $UserMessages 变量的值中，并覆盖 DATA 节逻辑保存的哈希表。

第三个命令显示 变量中的 $UserMessages 第一条消息。

Import-LocalizedData如果命令找到.psd1语言的文件$PsUICulture，则 变量的值$UserMessages将包含已翻译的文本字符串。 如果出于任何原因命令失败，则该命令将显示在脚本的 DATA 节中定义的默认文本字符串。

示例 6：在找不到 UI 区域性时取消显示错误消息

此示例演示如何禁止显示当找不到与用户 UI 区域性匹配的目录或无法在这些目录中找到.psd1脚本的文件时Import-LocalizedData显示的错误消息。

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

可以使用值为 SilentlyContinue 的 ErrorAction 通用参数取消显示错误消息。 当你已使用默认或回退语言提供用户消息并且不需要错误消息时，此方法特别有用。

此示例比较包含 命令的两个Import-LocalizedData脚本Day1.ps1和 Day2.ps1。 脚本是相同的，只不过 Day2 使用值为 的 SilentlyContinueErrorAction 通用参数。

示例输出显示当 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 节变量的名称。 然后，将导入的内容保存在 BindingVariable 中时Import-LocalizedData，导入的数据将替换默认文本字符串。 如果你不指定默认的文本字符串，则可以选择任何变量名称。

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 区域性 <language>-<region> ，例如 en-US、 de-DE或 ar-SA。

UICulture 参数的值确定基目录中特定于语言的子目录 (，) 从中Import-LocalizedData获取.psd1脚本的文件。

该 cmdlet 搜索与 UICulture 参数或自动变量（如 de-DE 或 ar-SA）的值同名的$PsUICulture子目录。 如果找不到目录，或者目录不包含 .psd1 脚本的文件，它会搜索具有语言代码名称的子目录，例如 de 或 ar。 如果找不到子目录或 .psd1 文件，则命令将失败，并且数据以脚本中指定的默认语言显示。

Type:	String
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

输入

None

不能通过管道将输入传递给此 cmdlet。

输出

Hashtable

Import-LocalizedData 将哈希表保存在 由 BindingVariable 参数的值指定的变量中。

备注

• 使用 Import-LocalizedData之前，请本地化用户消息。 在键值对的哈希表中设置每个区域设置 (UI 区域性) 的消息的格式，并将哈希表保存在与脚本同名且 .psd1 文件扩展名相同的文件中。 对于每个受支持的 UI 区域性，Create脚本目录下的目录，然后使用 UI 区域性名称将每个 UI 区域性的文件保存在.psd1目录中。

  例如，对 de-DE 区域设置对应的用户消息进行本地化并在哈希表中对其进行格式设置。 将哈希表保存在文件中 <ScriptName>.psd1 。 然后在脚本目录下创建一个 de-DE 子目录，并将德语 <ScriptName\>.psd1 文件 de-DE 保存在子目录中。 为你支持的每个区域设置重复此方法。

• Import-LocalizedData 对脚本的本地化用户消息执行结构化搜索。

  Import-LocalizedData 在脚本文件所在的目录中开始搜索 (或 BaseDirectory 参数的值) 。 然后，它在基目录中搜索一个子目录，该子目录的名称与变量 (的值 $PsUICulture 或 UICulture 参数的值) 相同，例如 de-DE 或 ar-SA。 然后，它会在该子目录中 .psd1 搜索与脚本 (同名的文件或 FileName 参数的值) 。

  如果 Import-LocalizedData 找不到具有 UI 区域性名称的子目录，或者子目录不包含 .psd1 脚本的文件，则会在具有语言代码名称的子目录中搜索 .psd1 脚本文件，例如 de 或 ar。 如果找不到子目录或 .psd1 文件，则命令将失败，数据以脚本中的默认语言显示，并显示一条错误消息，说明无法导入数据。 若要取消显示该消息并无声地指示失败，请使用值为 SilentlyContinue 的 ErrorAction 通用参数。

  如果 Import-LocalizedData 找到子目录和 .psd1 文件，则会将用户消息的哈希表导入命令中 BindingVariable 参数的值。 然后，当你显示来自变量中的哈希表的消息时，将显示已本地化的消息。

  有关详细信息，请参阅 about_Script_Internationalization。

相关链接

• Write-Host
• Import-PowerShellDataFile