Freigeben über

Import-LocalizedData

  • Referenz
Modul:
Microsoft.PowerShell.Utility

Importiert sprachspezifische Daten in Skripts und Funktionen basierend auf der für das Betriebssystem ausgewählten Benutzeroberflächenkultur.

Syntax

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

Beschreibung

Das Cmdlet Import-LocalizedData ruft Zeichenfolgen dynamisch aus einem Unterverzeichnis ab, dessen Name der Benutzeroberflächensprache für den aktuellen Benutzer des Betriebssystems entspricht. Es wurde entwickelt, um Skripts zum Anzeigen von Benutzermeldungen in der vom aktuellen Benutzer ausgewählten Benutzersprache zu ermöglichen.

Import-LocalizedData importiert Daten aus .psd1 Dateien in sprachspezifischen Unterverzeichnissen des Skriptverzeichnisses und speichert sie in einer lokalen Variablen, die im Befehl angegeben ist. Das Cmdlet wählt das Unterverzeichnis und die Datei basierend auf dem Wert der automatischen Variablen $PSUICulture aus. Wenn Sie die lokale Variable im Skript verwenden, um eine Benutzermeldung anzuzeigen, wird die Meldung in der Benutzeroberflächensprache angezeigt.

Sie können die Parameter von Import-LocalizedData verwenden, um eine alternative Benutzeroberflächenkultur, einen Pfad und dateinamen anzugeben, unterstützte Befehle hinzuzufügen und die Fehlermeldung zu unterdrücken, die angezeigt wird, wenn die .psd1 Dateien nicht gefunden werden.

Das cmdlet Import-LocalizedData unterstützt die Skript-Internationalisierungsinitiative, die in Windows PowerShell 2.0 eingeführt wurde. Diese Initiative zielt darauf ab, Benutzer weltweit besser zu bedienen, indem skripts die Anzeige von Benutzermeldungen in der Benutzeroberflächensprache des aktuellen Benutzers erleichtert werden. Weitere Informationen hierzu und zum Format der .psd1-Dateien finden Sie unter about_Script_Internationalization.

Beispiele

Beispiel 1: Importieren von Textzeichenfolgen

In diesem Beispiel werden Textzeichenfolgen in die variable $Messages importiert. Es verwendet die Standardwerte aller anderen Cmdlet-Parameter.

Import-LocalizedData -BindingVariable "Messages"

Wenn der Befehl im skript Archives.ps1 im verzeichnis C:\Test enthalten ist und der Wert der automatischen variablen $PSUICulture zh-CNist, importiert Import-LocalizedData die Archives.psd1 Datei im verzeichnis C:\test\zh-CN in die variable $Messages.

Beispiel 2: Importieren lokalisierter Datenzeichenfolgen

Dieses Beispiel wird an der Befehlszeile ausgeführt, die sich nicht in einem Skript befindet. Sie ruft lokalisierte Datenzeichenfolgen aus der Test.psd1-Datei ab und zeigt sie an der Befehlszeile an. Da der Befehl nicht in einem Skript verwendet wird, ist der FileName Parameter erforderlich. Der Befehl verwendet den parameter UICulture, um die en-US Kultur anzugeben.

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 gibt eine Hashtabelle zurück, die die lokalisierten Datenzeichenfolgen enthält.

Beispiel 3: Importieren von Ui-Kulturzeichenfolgen

Import-LocalizedData -BindingVariable "MsgTbl" -UICulture "ar-SA" -FileName "Simple" -BaseDirectory "C:\Data\Localized"

Mit diesem Befehl werden Textzeichenfolgen in die $MsgTbl Variable eines Skripts importiert.

Es verwendet den parameter UICulture, um das Cmdlet zum Importieren von Daten aus der Simple.psd1-Datei im Unterverzeichnis ar-SA von C:\Data\Localizedzu leiten.

Beispiel 4: Importieren lokalisierter Daten in ein Skript

In diesem Beispiel wird gezeigt, wie lokalisierte Daten in einem einfachen Skript verwendet werden.

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.

Der erste Teil des Beispiels zeigt den Inhalt der datei Test.psd1. Sie enthält einen ConvertFrom-StringData-Befehl, der eine Reihe benannter Textzeichenfolgen in eine Hashtabelle konvertiert. Die Test.psd1 Datei befindet sich im Unterverzeichnis en-US des C:\Test Verzeichnisses, das das Skript enthält.

Der zweite Teil des Beispiels zeigt den Inhalt des skripts Test.ps1. Sie enthält einen Import-LocalizedData-Befehl, der die Daten aus der übereinstimmenden .psd1 Datei in die $Messages Variable und einen Write-Host Befehl importiert, der eine der Nachrichten in der $Messages Variablen in das Hostprogramm schreibt.

Der letzte Teil des Beispiels führt das Skript aus. Die Ausgabe zeigt, dass die richtige Benutzermeldung in der Für den aktuellen Benutzer des Betriebssystems festgelegten Benutzersprache angezeigt wird.

Beispiel 5: Ersetzen von Standardtextzeichenfolgen in einem Skript

In diesem Beispiel wird gezeigt, wie Sie Import-LocalizedData verwenden, um im DATA-Abschnitt eines Skripts definierte Standardtextzeichenfolgen zu ersetzen.

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...

In diesem Beispiel enthält der DATA-Abschnitt des skripts TestScript.ps1 einen ConvertFrom-StringData Befehl, der den Inhalt des DATENabschnitts in eine Hashtabelle konvertiert und im Wert der $UserMessages Variablen speichert.

Das Skript enthält auch einen Import-LocalizedData-Befehl, der eine Hashtabelle von übersetzten Textzeichenfolgen aus der TestScript.psd1 Datei im Unterverzeichnis importiert, das durch den Wert der $PSUICulture Variablen angegeben wird. Wenn der Befehl die .psd1 Datei findet, speichert er die übersetzten Zeichenfolgen aus der Datei im Wert derselben $UserMessages Variablen, wobei die hashtable überschrieben wird, die von der DATA-Abschnittslogik gespeichert wird.

Der dritte Befehl zeigt die erste Meldung in der variablen $UserMessages an.

Wenn der Befehl Import-LocalizedData eine .psd1 Datei für die $PSUICulture Sprache findet, enthält der Wert der variablen $UserMessages die übersetzten Textzeichenfolgen. Wenn der Befehl aus irgendeinem Grund fehlschlägt, zeigt der Befehl die im DATENabschnitt des Skripts definierten Standardtextzeichenfolgen an.

Beispiel 6: Unterdrücken von Fehlermeldungen, wenn die UI-Kultur nicht gefunden wird

In diesem Beispiel wird gezeigt, wie die Fehlermeldungen unterdrückt werden, die angezeigt werden, wenn Import-LocalizedData die Verzeichnisse, die der Benutzeroberflächenkultur entsprechen, nicht finden oder eine .psd1 Datei für das Skript in diesen Verzeichnissen nicht finden können.

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

Sie können den ErrorAction- allgemeinen Parameter mit dem Wert "SilentlyContinue" verwenden, um die Fehlermeldung zu unterdrücken. Dies ist besonders hilfreich, wenn Sie Benutzernachrichten in einer Standard- oder Fallbacksprache bereitgestellt haben und keine Fehlermeldung erforderlich ist.

In diesem Beispiel werden zwei Skripts, Day1.ps1 und Day2.ps1, verglichen, die einen Import-LocalizedData Befehl enthalten. Die Skripts sind identisch, außer dass Day2 den ErrorAction gemeinsamen Parameter mit dem Wert SilentlyContinueverwendet.

Die Beispielausgabe zeigt die Ergebnisse der Ausführung beider Skripts, wenn die Benutzeroberflächenkultur auf fr-BE festgelegt ist und keine übereinstimmenden Dateien oder Verzeichnisse für diese Benutzeroberflächenkultur vorhanden sind. Day1.ps1 zeigt eine Fehlermeldung und eine englische Ausgabe an. Day2.ps1 zeigt nur die englische Ausgabe an.

Parameter

-BaseDirectory

Gibt das Basisverzeichnis an, in dem sich die .psd1 Dateien befinden. Der Standardwert ist das Verzeichnis, in dem sich das Skript befindet. Import-LocalizedData sucht nach der .psd1-Datei für das Skript in einem sprachspezifischen Unterverzeichnis des Basisverzeichnisses.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-BindingVariable

Gibt die Variable an, in die die Textzeichenfolgen importiert werden. Geben Sie einen Variablennamen ohne Dollarzeichen ein ($).

In Windows PowerShell 2.0 ist dieser Parameter erforderlich. In Windows PowerShell 3.0 ist dieser Parameter optional. Wenn Sie diesen Parameter weglassen, gibt Import-LocalizedData eine Hashtabelle der Textzeichenfolgen zurück. Die Hashtabelle wird an die Pipeline übergeben oder in der Befehlszeile angezeigt.

Wenn Sie Import-LocalizedData verwenden, um im DATA-Abschnitt eines Skripts angegebene Standardtextzeichenfolgen zu ersetzen, weisen Sie den DATA-Abschnitt einer Variablen zu, und geben Sie den Namen der DATA-Abschnittsvariablen in den Wert des BindingVariable-Parameters ein. Wenn dann Import-LocalizedData den importierten Inhalt im BindingVariablespeichert, werden die importierten Daten die Standardtextzeichenfolgen ersetzt. Wenn Sie keine Standardtextzeichenfolgen angeben, können Sie einen beliebigen Variablennamen auswählen.

Typ:String
Aliase:Variable
Position:0
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-FileName

Gibt den Namen der zu importierenden Datendatei (.psd1) an. Geben Sie einen Dateinamen ein. Sie können einen Dateinamen angeben, der seine .psd1 Dateinamenerweiterung nicht enthält, oder Sie können den Dateinamen einschließlich der .psd1 Dateinamenerweiterung angeben. Datendateien sollten als Unicode oder UTF-8 gespeichert werden.

Der FileName Parameter ist erforderlich, wenn Import-LocalizedData nicht in einem Skript verwendet wird. Andernfalls ist der Parameter optional, und der Standardwert ist der Basisname des Skripts. Sie können diesen Parameter verwenden, um Import-LocalizedData zu leiten, um nach einer anderen .psd1 Datei zu suchen.

Wenn beispielsweise der FileName- weggelassen wird und der Skriptname FindFiles.ps1ist, sucht Import-LocalizedData nach der FindFiles.psd1-Datendatei.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-SupportedCommand

Gibt Cmdlets und Funktionen an, die nur Daten generieren.

Verwenden Sie diesen Parameter, um Cmdlets und Funktionen einzuschließen, die Sie geschrieben oder getestet haben. Weitere Informationen finden Sie unter about_Script_Internationalization.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-UICulture

Gibt eine alternative Benutzeroberflächenkultur an. Der Standardwert ist der Wert der $PSUICulture automatischen Variablen. Geben Sie eine Benutzeroberflächenkultur in <language>-<region> Format ein, z. B. en-US, de-DEoder ar-SA.

Der Wert des parameters UICulture bestimmt das sprachspezifische Unterverzeichnis (innerhalb des Basisverzeichnisses), aus dem Import-LocalizedData die .psd1 Datei für das Skript abruft.

Das Cmdlet sucht nach einem Unterverzeichnis mit demselben Namen wie der Wert des parameters UICulture oder die $PSUICulture automatische Variable, z. B. de-DE oder ar-SA. Wenn das Verzeichnis nicht gefunden werden kann oder das Verzeichnis keine .psd1 Datei für das Skript enthält, sucht es nach einem Unterverzeichnis mit dem Namen des Sprachcodes, z. B. de oder ar. Wenn das Unterverzeichnis oder .psd1 Datei nicht gefunden werden kann, schlägt der Befehl fehl, und die Daten werden in der im Skript angegebenen Standardsprache angezeigt.

Typ:String
Position:1
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

Hashtable

Mit diesem Cmdlet wird die Hashtabelle in der Variablen gespeichert, die durch den Wert des BindingVariable-Parameters angegeben wird.

Hinweise

  • Bevor Sie Import-LocalizedDataverwenden, lokalisieren Sie Ihre Benutzernachrichten. Formatieren Sie die Nachrichten für jedes Gebietsschema (UI-Kultur) in einer Hashtable von Schlüsselwertpaaren, und speichern Sie die Hashtable in einer Datei mit demselben Namen wie das Skript und eine .psd1 Dateinamenerweiterung. Erstellen Sie ein Verzeichnis unter dem Skriptverzeichnis für jede unterstützte Benutzeroberflächenkultur, und speichern Sie dann die .psd1 Datei für jede Benutzeroberflächenkultur im Verzeichnis mit dem Namen der Benutzeroberflächenkultur.

    Lokalisieren Sie beispielsweise Ihre Benutzernachrichten für das gebietsschema de-DE, und formatieren Sie sie in einer Hashtabelle. Speichern Sie die Hashtabelle in einer <ScriptName>.psd1 Datei. Erstellen Sie dann ein de-DE Unterverzeichnis unter dem Skriptverzeichnis, und speichern Sie die deutsche <ScriptName>.psd1-Datei im Unterverzeichnis de-DE. Wiederholen Sie diese Methode für jedes gebietsschema, das Sie unterstützen.

  • Import-LocalizedData führt eine strukturierte Suche nach den lokalisierten Benutzernachrichten für ein Skript aus.

    Import-LocalizedData beginnt die Suche im Verzeichnis, in dem sich die Skriptdatei befindet (oder den Wert des BaseDirectory-Parameters). Anschließend wird im Basisverzeichnis nach einem Unterverzeichnis mit demselben Namen wie der Wert der $PSUICulture Variablen (oder der Wert des UICulture Parameters) durchsucht, z. B. de-DE oder ar-SA. Anschließend wird in diesem Unterverzeichnis nach einer .psd1 Datei mit demselben Namen wie das Skript (oder der Wert des FileName-Parameters) durchsucht.

    Wenn Import-LocalizedData kein Unterverzeichnis mit dem Namen der Benutzeroberflächenkultur finden kann oder das Unterverzeichnis keine .psd1 Datei für das Skript enthält, wird nach einer .psd1 Datei für das Skript in einem Unterverzeichnis mit dem Namen des Sprachcodes gesucht, z. B. de oder ar. Wenn das Unterverzeichnis oder .psd1 Datei nicht gefunden werden kann, schlägt der Befehl fehl, werden die Daten in der Standardsprache im Skript angezeigt, und es wird eine Fehlermeldung angezeigt, in der erläutert wird, dass die Daten nicht importiert werden konnten. Um die Nachricht zu unterdrücken und ordnungsgemäß fehlzuschlagen, verwenden Sie den ErrorAction allgemeinen Parameter mit dem Wert "SilentlyContinue".

    Wenn Import-LocalizedData das Unterverzeichnis und die .psd1 Datei findet, importiert sie die Hashtabelle von Benutzernachrichten in den Wert des BindingVariable-Parameters im Befehl. Wenn Sie dann eine Nachricht aus der Hashtabelle in der Variablen anzeigen, wird die lokalisierte Nachricht angezeigt.

    Weitere Informationen finden Sie unter about_Script_Internationalization.