共用方式為

Import-LocalizedData

  • 參考
模組:
Microsoft.PowerShell.Utility

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

語法

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 檔案時出現的錯誤訊息。

Import-LocalizedData Cmdlet 支援 Windows PowerShell 2.0 中引進的腳本國際化計劃。 此方案旨在讓腳本輕鬆地以目前使用者的UI語言顯示使用者訊息，以更好地為世界各地的使用者提供服務。 如需這個和 .psd1 檔案格式的詳細資訊，請參閱 about_Script_Internationalization。

範例

範例 1：匯入文字字串

本範例會將文字字串匯入 $Messages 變數。 它會使用所有其他 Cmdlet 參數的預設值。

Import-LocalizedData -BindingVariable "Messages"

如果命令包含在 C:\Test 目錄中的 Archives.ps1 腳本中，且 $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 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 從 C:\Data\Localizedar-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 腳本的內容。 其中包含 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 命令，它會從 $PsUICulture 變數值所指定的子目錄中，從 TestScript.psd1 檔案匯入翻譯文字字串的哈希表。 如果命令找到 .psd1 檔案，它會將檔案中的翻譯字串儲存在相同 $UserMessages 變數的值中，並覆寫 DATA 區段邏輯所儲存的哈希表。

第三個命令會顯示 $UserMessages 變數中的第一則訊息。

如果 Import-LocalizedData 命令找到 $PsUICulture 語言的 .psd1 檔案，則 $UserMessages 變數的值會包含翻譯的文字字串。 如果命令因任何原因而失敗，命令會顯示腳本之 DATA 區段中定義的預設文字字串。

範例 6：如果找不到 UI 文化特性，隱藏錯誤訊息

此範例示範如何隱藏 Import-LocalizedData 找不到符合使用者 UI 文化特性的目錄，或找不到這些目錄中腳本的 .psd1 檔案時出現的錯誤訊息。

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 common 參數搭配 SilentlyContinue 值來隱藏錯誤訊息。 當您以預設或後援語言提供使用者訊息，而且不需要錯誤訊息時，這特別有用。

此範例會比較包含 Import-LocalizedData 命令的兩個腳本，Day1.ps1 和 Day2.ps1。 腳本完全相同，不同之處在於 Day2 會使用 ErrorAction common 參數搭配 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時，匯入的數據將會取代預設的文字字串。 如果您未指定預設文字字串，您可以選取任何變數名稱。

類型: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 的值。 以 <language>-<region> 格式輸入 UI 文化特性，例如 en-US、de-DE或 ar-SA。

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

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

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

輸入

None

您無法使用管線將輸入傳送至此 Cmdlet。

輸出

Hashtable

會將哈希表儲存在由 bindingVariable 參數 值所指定的變數中。

備註

  • 使用 Import-LocalizedData之前，請將您的使用者訊息當地語系化。 將索引鍵/值組哈希表中每個地區設定（UI 文化特性）的訊息格式化，並將哈希表儲存在與腳本相同名稱的檔案中，以及 .psd1 擴展名。 針對每個支援的 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 common 參數搭配 SilentlyContinue 值。

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

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