Share via

Import-LocalizedData

  • 參考
模組:
Microsoft.PowerShell.Utility

根據為作業系統選取的 UI 文化特性，將語言特定資料匯入指令碼和函式。

Syntax

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

Description

Import-LocalizedData Cmdlet 會從名稱與操作系統目前用戶設定的 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中，而且自動變數的值是 zh-CN，Import-LocalizedData則會Archives.psd1將目錄中的$PsUICulture檔案C:\test\zh-CN匯入變數$Messages中。

範例 2︰匯入當地語系化資料字串

此範例是在不在文稿中的命令行上執行。 它會從 Test.psd1 檔案取得當地語系化資料字串，並在命令列中顯示這些字串。 由於此命令不是用於指令碼中，因此必須使用 FileName 參數。 此命令使用 UICulture 參數來指定 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.psd1 的子目錄中C:\Data\Localized的檔案ar-SA匯入數據。

範例 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變數的命令，以及將變數中$Messages其中一則Write-Host訊息寫入主機程式的命令。

此範例的最後一個部分會執行指令碼。 此輸出顯示它使用了為作業系統目前使用者設定的 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

您可以使用 ErrorAction 一般參數搭配 SilentlyContinue 值來抑制錯誤訊息。 當您已用預設語言或遞補語言提供使用者訊息，而不需要任何錯誤訊息時，這會特別有用。

此範例會比較包含命令的兩個腳本 Day1.ps1 和 Day2.ps1 Import-LocalizedData 。 腳本完全相同，不同之處在於 Day2 會使用 ErrorAction 一般參數與 值 SilentlyContinue。

範例輸出會顯示當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 或 $PsUICulturear-SA。 如果找不到目錄，或目錄不包含 .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 和擴展名相同的檔案中。 Create 每個支援的UI文化特性腳本目錄下的目錄，然後使用UI文化特性名稱將檔案儲存.psd1在目錄中的每個UI文化特性。

    例如，將您的使用者訊息針對 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 檔案，命令會失敗，數據會以腳本中的預設語言顯示，並顯示錯誤訊息，說明無法匯入數據。 若要抑制訊息並執行正常失敗程序，請使用 ErrorAction 一般參數搭配 SilentlyContinue 值。

    如果 Import-LocalizedData 找到子目錄和 .psd1 檔案，它會將使用者訊息的哈希表匯入命令中的 BindingVariable 參數值。 然後，當您從變數中的雜湊表顯示訊息時，就會顯示已翻譯成當地語言的訊息。

    如需詳細資訊，請參閱 about_Script_Internationalization。