共用方式為

Import-LocalizedData

  • 參考
模組:
Microsoft.PowerShell.Utility

根據針對操作系統選取的UI文化特性，將特定語言數據匯入腳本和函式。

語法

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請將目錄中的C:\test\zh-CN檔案匯Archives.psd1入$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 從 ar-SA Simple.psd1 的子目錄中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'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以及將變數中$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 : 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 值來隱藏錯誤訊息。 當您以預設或後援語言提供使用者訊息，而且不需要錯誤訊息時，這特別有用。

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

範例輸出會顯示當UI文化特性設定為 fr-BE 時執行這兩個腳本的結果，而且該UI文化特性沒有相符的檔案或目錄。 Day1.ps1 會顯示錯誤訊息和英文輸出。 Day2.ps1 只會顯示英文輸出。

參數

-BaseDirectory

指定檔案所在的 .psd1 基底目錄。 預設值是腳本所在的目錄。 Import-LocalizedData 在基底目錄的語言特定子目錄中搜尋 .psd1 腳本的檔案。

類型:String
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-BindingVariable

指定匯入文字字串的變數。 輸入不含貨幣符號的變數名稱 （$）。

在 Windows PowerShell 2.0 中，需要此參數。 在 Windows PowerShell 3.0 中，此參數是選擇性的。 如果您省略此參數， Import-LocalizedData 則會傳回文字字串的哈希表。 哈希表會向下傳遞管線，或在命令行上顯示。

使用 Import-LocalizedData 取代文稿之 DATA 區段中指定的預設文字字串時，請將 DATA 區段指派給變數，並在 BindingVariable 參數的值中輸入 DATA 區段變數的名稱。 然後，將匯入的內容儲存在 BindingVariable 中時Import-LocalizedData，匯入的數據將會取代預設的文字字串。 如果您未指定預設文字字串，您可以選取任何變數名稱。

類型:String
別名:Variable
Position:0
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-FileName

指定要匯入的數據檔.psd1) 名稱。 輸入檔名。 您可以指定不包含其 .psd1 擴展名的檔名，也可以指定檔名，包括 .psd1 擴展名。 數據文件應該儲存為 Unicode 或 UTF-8。

當腳本中未使用時Import-LocalizedData，需要 FileName 參數。 否則，參數是選擇性的，而預設值是腳本的基底名稱。 您可以使用此參數來直接 Import-LocalizedData 搜尋不同的 .psd1 檔案。

例如，如果 省略 FileName 且腳本名稱為 FindFiles.ps1， Import-LocalizedData 則會搜尋 FindFiles.psd1 數據檔。

類型:String
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-SupportedCommand

指定只產生數據的 Cmdlet 和函式。

使用此參數來包含您已撰寫或測試的 Cmdlet 和函式。 如需詳細資訊，請參閱 about_Script_Internationalization。

類型:String[]
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-UICulture

指定替代UI文化特性。 預設值是自動變數的值 $PsUICulture 。 以格式輸入 UI 文化特性 <language>-<region> ，例如 en-US、 de-DE或 ar-SA。

UICulture 參數的值會決定從中取得.psd1腳本檔案的語言特定子目錄（在基底目錄Import-LocalizedData內）。

Cmdlet 會搜尋名稱與 UICulture 參數值或$PsUICulture自動變數相同的子目錄，例如 de-DE 或 ar-SA。 如果找不到目錄，或目錄不包含 .psd1 腳本的檔案，則會搜尋具有語言代碼名稱的子目錄，例如 de 或 ar。 如果找不到子目錄或 .psd1 檔案，命令會失敗，而且數據會顯示在腳本中指定的默認語言中。

類型:String
Position:1
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

Hashtable

這個 Cmdlet 會將哈希表儲存在 BindingVariable 參數的值所指定的變數中。

備註

  • 使用 Import-LocalizedData之前，請先將使用者訊息當地語系化。 將索引鍵/值組哈希表中每個地區設定（UI 文化特性）的訊息格式化，並將哈希表儲存在與腳本和 .psd1 擴展名相同的檔案中。 針對每個支援的UI文化特性，在腳本目錄下建立目錄，然後使用 .psd1 UI文化特性名稱儲存目錄中每個UI文化特性的檔案。

    例如，將 de-DE 地區設定的使用者訊息當地語系化，並將其格式化為哈希表。 將哈希表儲存在檔案中 <ScriptName>.psd1 。 然後在腳本目錄下建立 de-DE 子目錄，並將德文 <ScriptName>.psd1 檔案儲存在 de-DE 子目錄中。 針對您支援的每個地區設定重複這個方法。

  • Import-LocalizedData 會針對文稿執行當地語系化使用者訊息的結構化搜尋。

    Import-LocalizedData會在腳本檔案所在的目錄中開始搜尋 （或BaseDirectory 參數的值）。 然後，它會在基底目錄中搜尋與變數值（或 UICulture 參數的值）相同名稱的$PsUICulture子目錄，例如 de-DE 或 ar-SA。 然後，它會在該子目錄中.psd1搜尋與腳本相同名稱的檔案（或 FileName 參數的值）。

    如果 Import-LocalizedData 找不到具有UI文化特性名稱的子目錄，或子目錄不包含 .psd1 腳本的檔案，則會在子目錄中搜尋 .psd1 具有語言代碼名稱的腳本檔案，例如de或ar。 如果找不到子目錄或 .psd1 檔案，命令會失敗，數據會顯示在腳本的默認語言中，並顯示錯誤訊息，說明無法匯入數據。 若要隱藏訊息並正常失敗，請使用 ErrorAction 一般參數搭配 SilentlyContinue 值。

    如果Import-LocalizedData找到子目錄和.psd1檔案，它會將使用者訊息的哈希表匯入命令中 BindingVariable 參數的值。 然後，當您在變數中顯示來自哈希表的訊息時，就會顯示本地化的訊息。

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