Import-LocalizedData
根據為操作系統選取的UI文化特性,將特定語言數據匯入腳本和函式。
Syntax
Import-LocalizedData
[[-BindingVariable] <String>]
[[-UICulture] <String>]
[-BaseDirectory <String>]
[-FileName <String>]
[-SupportedCommand <String[]>]
[<CommonParameters>]
Description
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 參數。 此命令使用 UICulture 參數來指定 en-US 文化特性。
Import-LocalizedData -FileName "Test.psd1" -UICulture "en-US"
Name Value
---- -----
Msg3 "Use $_ to represent the object that's 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's 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 : Can't 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
。 輸入格式的 <language>-<region>
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。
輸出
這個 Cmdlet 會將哈希表儲存在 BindingVariable 參數的值所指定的變數中。
備註
使用
Import-LocalizedData
之前,請先將使用者訊息當地語系化。 將每個地區設定 (UI 文化特性的訊息格式化為索引鍵/值組的哈希表中) ,並將哈希表儲存在與腳本和.psd1
擴展名相同的檔案中。 Create 每個支援的UI文化特性腳本目錄下的目錄,然後使用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
檔案,命令會失敗,數據會顯示在腳本的默認語言中,並顯示錯誤訊息,說明無法匯入數據。 若要抑制訊息並執行正常失敗程序,請使用 ErrorAction 一般參數搭配 SilentlyContinue 值。如果
Import-LocalizedData
找到子目錄和.psd1
檔案,它會將使用者訊息的哈希表匯入命令中 BindingVariable 參數的值。 然後,當您在變數中顯示來自哈希表的訊息時,就會顯示本地化的訊息。如需詳細資訊,請參閱 about_Script_Internationalization。