Import-LocalizedData

發行項
10/30/2009

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

語法

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

描述

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。

參數

-BaseDirectory <string>

指定 .psd1 檔案所在的基底目錄。預設為指令碼所在的目錄。Import-LocalizedData 會在基底目錄的特定語言子目錄中搜尋指令碼的 .psd1 檔案。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-BindingVariable <string>

指定匯入文字字串的目標變數。請輸入變數名稱，但不要加上貨幣符號 ($)。

使用 Import-LocalizedData 取代指令碼的 DATA 區段中所指定的預設文字字串時，請指派 DATA 區段給變數，並在 BindingVariable 參數的值中輸入 DATA 區段變數的名稱。那麼，Import-LocalizedData 將匯入的內容儲存到 BindingVariable 時，匯入的資料就會取代預設的文字字串。如果您未指定預設文字字串，可以選取任何變數名稱。

必要?	true
位置?	1
預設值
接受管線輸入?	false
接受萬用字元?	false

-FileName <string>

指定要匯入的 .psd1 檔名。請輸入檔名，但不要加上副檔名。

預設為指令碼的名稱。例如，若指令碼為 FindFiles.ps1，Import-LocalizedData 會搜尋 FindFiles.psd1。您可以使用此參數指示 Import-LocalizedData 搜尋不同的 .psd1 檔案。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-SupportedCommand <string[]>

指定只產生資料的 Cmdlet 和函數。

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

必要?	false
位置?	named
預設值	無
接受管線輸入?	false
接受萬用字元?	false

-UICulture <string>

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

UICulture 參數的值決定 Import-LocalizedData Cmdlet 從中取得指令碼的 .psd1 檔案的特定語言子目錄 (位於基底目錄內)。

此 Cmdlet 會搜尋與 UICulture 參數或 $PsUICulture 自動變數的值同名的子目錄，例如 "de-DE" 或 "ar-SA"。如果它找不到該目錄，或該目錄未包含指令碼的 .psd1 檔案，則會搜尋與語言代碼同名的子目錄，例如 "de" 或 "ar"。如果它找不到該子目錄或 .psd1 檔案，則命令會失敗，而且資料會以指令碼中指定的預設語言顯示。

必要?	false
位置?	2
預設值
接受管線輸入?	false
接受萬用字元?	false

<CommonParameters>

這個 Cmdlet 支援一般參數：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊，請參閱 about_Commonparameters.

輸入和輸出

輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。

輸入

無

您無法經由管道將輸入輸出至這個 Cmdlet。

輸出

System.Collections.Hashtable

Import-LocalizedData 會將雜湊表儲存在 BindingVariable 參數值所指定的變數中。

附註

使用 Import-LocalizedData 之前，請先將您的使用者訊息當地語系化。針對每個地區設定 (UI 文化特性)，以索引鍵值組的雜湊表形式格式化使用者訊息，然後將雜湊表儲存到與指令碼同名且副檔名為 .psd1 的檔案中。針對每個支援的 UI 文化特性，在指令碼目錄下建立目錄，然後將每個 UI 文化特性的 .psd1 檔案儲存到與 UI 文化特性同名的目錄。

例如，針對 de-DE 地區設定，將您的使用者訊息當地語系化，然後以雜湊表形式加以格式化。接著，將雜湊表儲存到 <ScriptName>.psd1 檔案，然後在指令碼目錄下建立 de-DE 子目錄，再將 de-DE <ScriptName>.psd1 檔案儲存到 de-DE 子目錄。針對每個所能支援的地區設定，重複上述方法。

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

Import-LocalizedData 會在指令碼檔所在的目錄 (或 BaseDirectory 參數的值) 中開始進行搜尋，然後在基底目錄內搜尋與 $PsUICulture 變數的值 (或 UICulture 參數的值) 同名的子目錄，例如 "de-DE" 或 "ar-SA"，再在該子目錄中搜尋與指令碼 (或 FileName 參數的值) 同名的 .psd1 檔案。

如果 Import-LocalizedData 找不到與 UI 文化特性同名的子目錄，或該子目錄並未包含指令碼的 .psd1 檔案，則會在與語言代碼同名的子目錄 (如 "de" 或 "ar") 中搜尋指令碼的 .psd1 檔案。如果它找不到該子目錄或 .psd1 檔案，則命令會失敗、資料會以指令碼中的預設語言顯示，而且出現一個錯誤訊息，說明無法匯入資料。若要隱藏這個訊息，而且讓失敗不嚴重，請使用值為 SilentlyContinue 的一般參數 ErrorAction。

如果 Import-LocalizedData 找到該子目錄和 .psd1 檔案，則會將使用者訊息的雜湊表匯入命令中的 BindingVariable 參數值。然後，當您顯示來自變數中的雜湊表的訊息時，即會顯示當地語系化訊息。

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

範例 1

C:\PS>import-localizeddata -bindingVariable messages

描述
-----------
這個命令會將文字字串匯入 $messages 變數，並使用 Cmdlet 參數的所有預設值。

如果在 C:\test 目錄中的 Archives.ps1 指令碼內包含命令，而且 $PsUICulture 自動變數的值為 zh-CN，Import-LocalizedData 則會匯入 C:\test\zh-CN 目錄中的 Archives.psd1 檔案。

範例 2

C:\PS>import-localizeddata -bindingVariable msgTbl -uiculture ar-SA -filename Simple -baseDirectory C:\Data\Localized

描述
-----------
這個命令會將文字字串匯入指令碼的 $msgTbl 變數。

它會使用 UICulture 參數指示 Cmdlet 從 C:\Data\Localized 的 ar-SA 子目錄中的 Simple.psd1 檔案匯入資料。

範例 3

C:\PS># 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

C:\PS> .\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 語言設定來顯示正確的使用者訊息。

範例 4

C:\PS># 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
...

描述
-----------
這個範例示範如何使用 Import-LocalizedData 取代指令碼的 DATA 區段中所定義的預設文字字串。

在此範例中，TestScript.ps1 指令碼的 DATA 區段包含 ConvertFrom-StringData 命令，此命令會將 DATA 區段的內容轉換成雜湊表，並儲存在 $UserMessages 變數的值中。

此指令碼也包含 Import-LocalizedData 命令，此命令會從 $PsUICulture 變數值所指定之子目錄中的 TestScript.psd1 檔案匯入翻譯文字字串的雜湊表。如果此命令找到 .psd1 檔案，它會將檔案中的翻譯字串儲存到同一個 $UserMessages 變數的值中，覆寫 DATA 區段邏輯所儲存的雜湊表。

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

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

範例 5

C:\PS># In Day1.ps1
Import-LocalizedData -bindingVariable Day
Day.MessageDate

# In Day2.ps1
Import-LocalizedData -bindingVariable Day -errorAction:silentlycontinue
Day.MessageDate

C:\PS> .\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


C:\PS> .\Day2.ps1

Today is Tuesday

描述
-----------
這個範例示範如何隱藏 Import-LocalizedData 找不到與使用者 UI 文化特性對應的目錄或在那些目錄中找不到指令碼的 .psd1 檔案時所顯示的錯誤訊息。

您可以使用值為 "SilentlyContinue" 的一般 ErrorAction 參數，隱藏錯誤訊息。當您已經以預設或「遞補」語言提供使用者訊息，而且不需要任何錯誤訊息時，這種做法特別有用。

這個範例比較兩個都包含 Import-LocalizedData 命令的指令碼：Day1.ps1 與 Day2.ps1。Day2 使用值為 SilentlyContinue 的一般 ErrorAction 參數，除這點以外兩個指令碼完全相同。

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

請參閱

概念

about_Script_Internationalization

共用方式為