Partilhar via

Import-LocalizedData

Módulo:
Microsoft.PowerShell.Utility Module

Importa dados específicos do idioma para scripts e funções com base na cultura da interface do usuário selecionada para o sistema operacional.

Sintaxe

Default (Predefinição) 

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

Description

O cmdlet Import-LocalizedData recupera dinamicamente cadeias de caracteres de um subdiretório cujo nome corresponde ao idioma da interface do usuário definido para o usuário atual do sistema operacional. Ele foi projetado para permitir que os scripts exibam mensagens do usuário no idioma da interface do usuário selecionado pelo usuário atual.

Import-LocalizedData importa dados de arquivos .psd1 em subdiretórios específicos do idioma do diretório de script e os salva em uma variável local especificada no comando. O cmdlet seleciona o subdiretório e o arquivo com base no valor da variável automática $PSUICulture. Quando você usa a variável local no script para exibir uma mensagem do usuário, a mensagem aparece no idioma da interface do usuário do usuário.

Você pode usar os parâmetros do Import-LocalizedData para especificar uma cultura, caminho e nome de arquivo alternativos da interface do usuário, para adicionar comandos suportados e para suprimir a mensagem de erro que aparece se os arquivos .psd1 não forem encontrados.

O cmdlet Import-LocalizedData dá suporte à iniciativa de internacionalização de scripts que foi introduzida no Windows PowerShell 2.0. Esta iniciativa visa servir melhor os utilizadores em todo o mundo, tornando mais fácil para os scripts exibirem mensagens do utilizador no idioma da IU do utilizador atual. Para obter mais informações sobre isso e sobre o formato dos arquivos .psd1, consulte about_Script_Internationalization.

Exemplos

Exemplo 1: Importar cadeias de texto

Este exemplo importa cadeias de caracteres de texto para a variável $Messages. Ele usa os valores padrão de todos os outros parâmetros do cmdlet.

Import-LocalizedData -BindingVariable "Messages"

Se o comando estiver incluído no script Archives.ps1 no diretório C:\Test e o valor da variável automática $PSUICulture for zh-CN, Import-LocalizedData importará o arquivo Archives.psd1 no diretório C:\test\zh-CN para a variável $Messages.

Exemplo 2: Importar cadeias de dados localizadas

Este exemplo é executado na linha de comando, não em um script. Ele obtém cadeias de dados localizadas do arquivo Test.psd1 e as exibe na linha de comando. Como o comando não é usado em um script, o parâmetro FileName é necessário. O comando usa o parâmetro UICulture para especificar a cultura 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 retorna uma hashtable que contém as cadeias de caracteres de dados localizados.

Exemplo 3: Importar cadeias de caracteres de cultura da interface do usuário

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

Este comando importa cadeias de caracteres de texto para a variável $MsgTbl de um script.

Ele usa o parâmetro UICulture para direcionar o cmdlet para importar dados do arquivo Simple.psd1 no subdiretório ar-SA do C:\Data\Localized.

Exemplo 4: Importar dados localizados para um script

Este exemplo mostra como usar dados localizados em um script simples.

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.

A primeira parte do exemplo mostra o conteúdo do arquivo Test.psd1. Ele contém um comando ConvertFrom-StringData que converte uma série de cadeias de caracteres de texto nomeado em uma hashtable. O arquivo Test.psd1 está localizado no subdiretório en-US do diretório C:\Test que contém o script.

A segunda parte do exemplo mostra o conteúdo do script Test.ps1. Ele contém um comando Import-LocalizedData que importa os dados do arquivo de .psd1 correspondente para a variável $Messages e um comando Write-Host que grava uma das mensagens na variável $Messages para o programa host.

A última parte do exemplo executa o script. A saída mostra que ele exibe a mensagem de usuário correta no idioma da interface do usuário definido para o usuário atual do sistema operacional.

Exemplo 5: Substituir cadeias de texto padrão em um script

Este exemplo mostra como usar Import-LocalizedData para substituir cadeias de texto padrão definidas na seção DATA de um script.

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

Neste exemplo, a seção DATA do script TestScript.ps1 contém um comando ConvertFrom-StringData que converte o conteúdo da seção DATA em uma hashtable e armazena o valor da variável $UserMessages.

O script também inclui um comando Import-LocalizedData, que importa uma hashtable de cadeias de texto traduzidas do arquivo TestScript.psd1 no subdiretório especificado pelo valor da variável $PSUICulture. Se o comando encontrar o arquivo .psd1, ele salvará as cadeias de caracteres traduzidas do arquivo no valor da mesma variável $UserMessages, substituindo a hashtable salva pela lógica da seção DATA.

O terceiro comando exibe a primeira mensagem na variável $UserMessages.

Se o comando Import-LocalizedData encontrar um arquivo .psd1 para o idioma $PSUICulture, o valor da variável $UserMessages conterá as cadeias de caracteres de texto traduzidas. Se o comando falhar por qualquer motivo, ele exibirá as cadeias de texto padrão definidas na seção DATA do script.

Exemplo 6: Suprimir mensagens de erro se a cultura da interface do usuário não for encontrada

Este exemplo mostra como suprimir as mensagens de erro que aparecem quando Import-LocalizedData não consegue encontrar os diretórios que correspondem à cultura da interface do usuário do usuário ou não consegue encontrar um arquivo .psd1 para o script nesses diretórios.

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

Você pode usar o ErrorAction parâmetro comum com um valor de SilentlyContinue para suprimir a mensagem de erro. Isso é especialmente útil quando você forneceu mensagens de usuário em um idioma padrão ou de fallback e nenhuma mensagem de erro é necessária.

Este exemplo compara dois scripts, Day1.ps1 e Day2.ps1, que incluem um comando Import-LocalizedData. Os scripts são idênticos, exceto que Day2 usa o ErrorAction parâmetro comum com um valor de SilentlyContinue.

A saída de exemplo mostra os resultados da execução de ambos os scripts quando a cultura da interface do usuário está definida como fr-BE e não há arquivos ou diretórios correspondentes para essa cultura da interface do usuário. Day1.ps1 exibe uma mensagem de erro e saída em inglês. Day2.ps1 apenas exibe a saída em inglês.

Parâmetros

-BaseDirectory

Especifica o diretório base onde os arquivos .psd1 estão localizados. O padrão é o diretório onde o script está localizado. Import-LocalizedData procura o arquivo .psd1 para o script em um subdiretório específico do idioma do diretório base.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-BindingVariable

Especifica a variável para a qual as cadeias de caracteres de texto são importadas. Insira um nome de variável sem cifrão ($).

No Windows PowerShell 2.0, esse parâmetro é necessário. No Windows PowerShell 3.0, esse parâmetro é opcional. Se você omitir esse parâmetro, Import-LocalizedData retornará uma hashtable das cadeias de caracteres de texto. A hashtable é passada pelo pipeline ou exibida na linha de comando.

Ao usar Import-LocalizedData para substituir cadeias de texto padrão especificadas na seção DATA de um script, atribua a seção DATA a uma variável e insira o nome da variável de seção DATA no valor do parâmetro BindingVariable. Em seguida, quando Import-LocalizedData salvar o conteúdo importado no BindingVariable, os dados importados substituirão as cadeias de texto padrão. Se você não estiver especificando cadeias de caracteres de texto padrão, poderá selecionar qualquer nome de variável.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Variável

Conjuntos de parâmetros

(All)
Position:0
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-FileName

Especifica o nome do arquivo de dados (.psd1) a ser importado. Insira um nome de arquivo. Você pode especificar um nome de arquivo que não inclua sua extensão de nome de arquivo .psd1 ou pode especificar o nome do arquivo incluindo a extensão de nome de arquivo .psd1. Os arquivos de dados devem ser salvos como Unicode ou UTF-8.

O parâmetro FileName é necessário quando Import-LocalizedData não é usado em um script. Caso contrário, o parâmetro é opcional e o valor padrão é o nome base do script. Você pode usar esse parâmetro para direcionar Import-LocalizedData para procurar um arquivo .psd1 diferente.

Por exemplo, se o FileName for omitido e o nome do script for FindFiles.ps1, Import-LocalizedData procurará o arquivo de dados FindFiles.psd1.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-SupportedCommand

Especifica cmdlets e funções que geram apenas dados.

Use esse parâmetro para incluir cmdlets e funções que você escreveu ou testou. Para obter mais informações, consulte about_Script_Internationalization.

Propriedades dos parâmetros

Tipo:

String[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-UICulture

Especifica uma cultura de interface do usuário alternativa. O padrão é o valor da variável automática $PSUICulture. Insira uma cultura de interface do usuário em <language>-<region> formato, como en-US, de-DEou ar-SA.

O valor do parâmetro UICulture determina o subdiretório específico do idioma (dentro do diretório base) a partir do qual Import-LocalizedData obtém o arquivo .psd1 para o script.

O cmdlet procura um subdiretório com o mesmo nome que o valor do parâmetro UICulture ou a variável automática $PSUICulture, como de-DE ou ar-SA. Se não conseguir encontrar o diretório ou se o diretório não contiver um arquivo .psd1 para o script, ele procurará um subdiretório com o nome do código do idioma, como de ou ar. Se não conseguir encontrar o subdiretório ou .psd1 arquivo, o comando falhará e os dados serão exibidos no idioma padrão especificado no script.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:1
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

Hashtable

Este cmdlet salva a hashtable na variável especificada pelo valor do parâmetro BindingVariable.

Notas

  • Antes de usar Import-LocalizedData, localize suas mensagens de usuário. Formate as mensagens para cada localidade (cultura da interface do usuário) em uma hashtable de pares chave-valor e salve a hashtable em um arquivo com o mesmo nome do script e uma extensão de nome de arquivo .psd1. Crie um diretório sob o diretório de script para cada cultura de interface do usuário suportada e, em seguida, salve o arquivo de .psd1 para cada cultura de interface do usuário no diretório com o nome da cultura da interface do usuário.

    Por exemplo, localize suas mensagens de usuário para a localidade de-DE e formate-as em uma hashtable. Salve a hashtable em um arquivo <ScriptName>.psd1. Em seguida, crie um subdiretório de-DE no diretório script e salve o arquivo <ScriptName>.psd1 alemão no subdiretório de-DE. Repita esse método para cada localidade que você suporta.

  • Import-LocalizedData executa uma pesquisa estruturada para as mensagens de usuário localizadas para um script.

    Import-LocalizedData inicia a pesquisa no diretório onde o arquivo de script está localizado (ou o valor do parâmetro BaseDirectory). Em seguida, ele procura no diretório base um subdiretório com o mesmo nome que o valor da variável $PSUICulture (ou o valor do parâmetro UICulture), como de-DE ou ar-SA. Em seguida, ele procura nesse subdiretório por um arquivo .psd1 com o mesmo nome do script (ou o valor do parâmetro FileName).

    Se Import-LocalizedData não conseguir encontrar um subdiretório com o nome da cultura da interface do usuário, ou se o subdiretório não contiver um arquivo .psd1 para o script, ele procurará um arquivo .psd1 para o script em um subdiretório com o nome do código do idioma, como de ou ar. Se não conseguir encontrar o subdiretório ou .psd1 arquivo, o comando falhará, os dados serão exibidos no idioma padrão no script e uma mensagem de erro será exibida explicando que os dados não puderam ser importados. Para suprimir a mensagem e falhar normalmente, use o ErrorAction parâmetro comum com um valor de SilentlyContinue.

    Se Import-LocalizedData encontrar o subdiretório e o arquivo .psd1, ele importará a hashtable de mensagens do usuário para o valor do parâmetro BindingVariable no comando. Em seguida, quando você exibe uma mensagem da hashtable na variável, a mensagem localizada é exibida.

    Para obter mais informações, consulte about_Script_Internationalization.