about_Script_Internationalization

發行項
03/19/2024

簡短描述

描述文本國際化功能，可讓腳本在使用者介面（UI）語言中輕鬆地向用戶顯示訊息和指示。

詳細描述

PowerShell 腳本國際化功能可讓您藉由以使用者語言顯示說明和使用者訊息，以更好地為世界各地的使用者提供服務。

腳本國際化功能會在執行期間查詢操作系統的UI文化特性、匯入適當的翻譯文字字串，並將其顯示給使用者。 [數據] 區段可讓您將文字字串與程式代碼分開儲存，以便輕鬆地識別和擷取它們。新的 Cmdlet ConvertFrom-StringData會將文字字串轉換成類似字典的哈希表，以利翻譯。

為了支持國際說明文字，PowerShell 包含下列功能：

數據區段，分隔文字字串與程式代碼指示。如需數據一節的詳細資訊，請參閱 about_Data_Sections。
新的自動變數 $PSCulture 與 $PSUICulture。 $PSCulture 會儲存系統上用於日期、時間和貨幣等元素的UI語言名稱。 $PSUICulture變數會儲存系統上用於使用者介面元素的 UI 語言名稱，例如功能表和文字字串。
Cmdlet ConvertFrom-StringData，可將文字字串轉換成類似字典的哈希表，以利翻譯。如需詳細資訊，請參閱 ConvertFrom-StringData。
儲存翻譯文字字串的新檔案類型 .psd1。這些 .psd1 檔案會儲存在文稿目錄的語言特定子目錄中。
Cmdlet Import-LocalizedData，會將指定語言的翻譯文字字串匯入運行時間的腳本。此 Cmdlet 會以任何 Windows 支援的語言辨識並匯入字串。如需詳細資訊，請參閱 Import-LocalizedData。

數據區段：儲存預設字串

使用文稿中的數據區段，以預設語言儲存文字字串。以 here-string 中的索引鍵/值組排列字串。每個索引鍵/值組都必須位於個別行上。如果您包含批注，批注必須位於個別行。

Cmdlet 會將 ConvertFrom-StringData here-string 中的索引鍵/值組轉換成儲存在 Data 區段變數值中的類似字典的哈希表。

在下列範例中，腳本的 World.ps1 Data 區段包含腳本的英文美國（en-US）提示訊息集。 Cmdlet 會將 ConvertFrom-StringData 字串轉換成哈希表，並將其儲存在變數中 $msgtable 。

$msgTable = Data {
    #culture="en-US"
    ConvertFrom-StringData @'
    helloWorld = Hello, World.
    errorMsg1 = You cannot leave the user name field blank.
    promptMsg = Please enter your user name.
'@
}

如需 here-strings 的詳細資訊，請參閱 about_Quoting_Rules。

PSD1 檔案：儲存翻譯的字串

將每個 UI 語言的腳本訊息儲存在與腳本 .psd1 和擴展名相同的個別文字檔中。以下列格式將檔案儲存在文稿目錄的子目錄中，其文化特性名稱如下：

<language>-<region>

範例：de-DE、ar-SA 和 zh-Hans

例如，如果 World.ps1 文稿儲存在 C:\Scripts 目錄中，您會建立類似下列的檔案目錄結構：

C:\Scripts
C:\Scripts\World.ps1
C:\Scripts\de-DE\World.psd1
C:\Scripts\ar-SA\World.psd1
C:\Scripts\zh-CN\World.psd1
...

World.psd1文稿目錄 de-DE 子目錄中的檔案可能包含下列語句：

ConvertFrom-StringData -StringData @'
helloWorld = Hallo, Welt.
errorMsg1 = Das Feld Benutzername darf nicht leer sein.
promptMsg = Geben Sie Ihren Benutzernamen ein.
'@

同樣地， World.psd1 腳稿目錄 ar-SA 子目錄中的檔案可能包含下列語句：

ConvertFrom-StringData -StringData @'
helloWorld = مرحبًا أيها العالَم
errorMsg1 = لا يمكنك ترك حقل اسم المستخدم فارغًا
promptMsg = يرجى إدخال اسم المستخدم الخاص بك
'@

Import-LocalizedData：動態擷取翻譯字串

若要以目前使用者的UI語言擷取字串，請使用 Import-LocalizedData Cmdlet。

Import-LocalizedData會尋找自動變數的值$PSUICulture，並匯入符合$PSUICulture值的子目錄中的檔案內容<script-name>.psd1。然後，它會將匯入的內容儲存在 BindingVariable 參數的值所指定的變數中。

Import-LocalizedData -BindingVariable msgTable

例如，如果 Import-LocalizedData 命令出現在腳本中 C:\Scripts\World.ps1 ，且的值 $PSUICulture 是「ar-SA」， Import-LocalizedData 則會尋找下列檔案：

C:\Scripts\ar-SA\World.psd1

然後，它會將檔案中的阿拉伯文文字字串匯入 $msgTable 變數，並取代腳本的 Data 區段中 World.ps1 可能定義的任何預設字串。

因此，當腳本使用 $msgTable 變數來顯示使用者訊息時，訊息會以阿拉伯文顯示。

例如，下列文稿會以阿拉伯文顯示「請輸入您的使用者名稱」訊息：

if (!($username)) { $msgTable.promptMsg }

如果 Import-LocalizedData 找不到 .psd1 符合的值的 $PSUIculture檔案，則不會取代的值 $msgTable ，以及顯示 $msgTable.promptMsg 後援 en-US 字串的呼叫。

範例

此範例示範腳本國際化功能如何在腳本中使用，以計算機上的語言向用戶顯示一周中的一天。

以下是 Sample1.ps1 腳本檔案的完整清單。

腳本的開頭是名為 Day （$Day）的數據區段，其中包含 ConvertFrom-StringData 命令。提交給 ConvertFrom-StringData 的表達式是一個 here-string，其中包含預設 UI 文化特性 en-US 中索引鍵/值組中的日期名稱。 Cmdlet 會將 ConvertFrom-StringData here-string 中的索引鍵/值組轉換成哈希表，然後將它儲存在變數的值 $Day 中。

Import-LocalizedData命令會匯入目錄中符合自動變數值$PSUICulture之檔案的內容.psd1，然後將它儲存在變數中$Day，取代 Data 區段中定義的值$Day。

其餘命令會將字串載入數位列並加以顯示。

$Day = Data {
#culture="en-US"
ConvertFrom-StringData -StringData @'
    messageDate = Today is
    d0 = Sunday
    d1 = Monday
    d2 = Tuesday
    d3 = Wednesday
    d4 = Thursday
    d5 = Friday
    d6 = Saturday
'@
}

Import-LocalizedData -BindingVariable Day

#Build an array of weekdays.
$a = $Day.d0, $Day.d1, $Day.d2, $Day.d3, $Day.d4, $Day.d5, $Day.d6

# Get the day of the week as a number (Monday = 1).
# Index into $a to get the name of the day.
# Use string formatting to build a sentence.

"{0} {1}" -f $Day.messageDate, $a[(Get-Date -UFormat %u)] | Out-Host

.psd1支援文稿的檔案會儲存在腳本目錄的子目錄中，其中包含符合$PSUICulture值的名稱。

以下是的完整清單 .\de-DE\sample1.psd1：

# culture="de-DE"
ConvertFrom-StringData @'
    messageDate = Heute ist
    d0 = Sonntag
    d1 = Montag
    d2 = Dienstag
    d3 = Mittwoch
    d4 = Donnerstag
    d5 = Freitag
    d6 = Samstag
'@

因此，當您在值為 de-DE 的系統上 $PSUICulture 執行 Sample.ps1 時，腳本的輸出為：

Heute ist Freitag

共用方式為