Compartilhar 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 (Default) 

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 conjunto de idiomas da interface do usuário para o usuário atual do sistema operacional. Ele foi projetado para permitir que scripts exibam mensagens de 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 ao usuário, a mensagem aparece no idioma da interface do usuário.

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

O cmdlet Import-LocalizedData dá suporte à iniciativa de internacionalização de script introduzida no Windows PowerShell 2.0. Essa iniciativa tem como objetivo atender melhor os usuários em todo o mundo, facilitando a exibição de mensagens do usuário no idioma da interface do usuário 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 caracteres 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 de 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 caracteres de dados localizadas

Este exemplo é executado na linha de comando que não está em um script. Ele obtém cadeias de caracteres 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 um hashtable que contém as cadeias de caracteres de dados localizadas.

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"

Esse 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 de 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 nomeadas em um 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 ela exibe a mensagem correta do usuário no idioma da interface configurado para o usuário atual do sistema operacional.

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

Este exemplo mostra como usar Import-LocalizedData para substituir cadeias de caracteres 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 um hashtable e armazena no valor da variável $UserMessages.

O script também inclui um comando Import-LocalizedData, que importa um hashtable de cadeias de caracteres 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 salva as cadeias de caracteres traduzidas do arquivo no valor da mesma variável $UserMessages, substituindo a tabela de hash 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 algum motivo, o comando exibirá as cadeias de caracteres 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 diretórios que correspondam à cultura da interface do usuário ou nem 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 parâmetro ErrorAction comum com um valor de SilentlyContinue para suprimir a mensagem de erro. Isso é especialmente útil quando você fornece 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 parâmetro ErrorAction 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 de interface do usuário. Day1.ps1 exibe uma mensagem de erro e uma saída em inglês. Day2.ps1 exibe apenas a saída em inglês.

Parâmetros

-BaseDirectory

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

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-BindingVariable

Especifica a variável na qual as cadeias de caracteres de texto são importadas. Insira um nome de variável sem um sinal de dólar ($).

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á um hashtable das cadeias de caracteres de texto. A tabela de hash é passada pelo pipeline ou exibida na linha de comando.

Ao usar Import-LocalizedData para substituir cadeias de caracteres 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 salva o conteúdo importado na BindingVariable , os dados importados substituirão os textos padrão. Se você não estiver especificando cadeias de caracteres de texto padrão, poderá selecionar qualquer nome de variável.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:Variável

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 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 pesquisar um arquivo de .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 do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SupportedCommand

Especifica os cmdlets e funções que geram somente dados.

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

Propriedades do parâmetro

Tipo:

String[]

Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 no formato <language>-<region>, 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) 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 ele não conseguir localizar 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 de idioma, como de ou ar. Se ele não encontrar o subdiretório ou .psd1 arquivo, o comando falhará e os dados serão exibidos no idioma padrão especificado no script.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:1
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 transferir objetos para esse cmdlet.

Saídas

Hashtable

Esse cmdlet salva a tabela de hash na variável especificada pelo valor do parâmetro BindingVariable.

Observações

  • Antes de usar Import-LocalizedData, localize suas mensagens de usuário. Formate as mensagens para cada localidade (cultura da interface do usuário) em um hash de pares chave-valor e salve o hashtable em um arquivo com o mesmo nome do script e uma extensão de nome de arquivo .psd1. Crie um diretório no diretório de script para cada cultura de interface do usuário com suporte e salve o arquivo .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 do de-DE e formate-as em um hashtable. Salve o hashtable em um arquivo de <ScriptName>.psd1. Em seguida, crie um subdiretório de-DE no diretório de script e salve o arquivo de <ScriptName>.psd1 alemão no subdiretório de-DE. Repita este método para cada localidade que você oferece suporte.

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

    Import-LocalizedData inicia a pesquisa no diretório em que o arquivo de script está localizado (ou o valor do parâmetro BaseDirectory). Em seguida, ele pesquisa 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 pesquisa nesse subdiretório 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 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 de idioma, como de ou ar. Se não conseguir localizar 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 graciosamente, use o parâmetro ErrorAction comum com um valor de SilentlyContinue.

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

    Para obter mais informações, consulte about_Script_Internationalization.