Import-LocalizedData

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

Sintaxe

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

Descrição

O cmdlet Import-LocalizedData recupera cadeias de caracteres dinamicamente de um subdiretório a cujo nome corresponde o idioma de interface do usuário definido para o usuário atual do sistema operacional. Ele foi criado para habilitar scripts para exibir mensagens de usuário no idioma de interface do usuário selecionado pelo usuário atual.

Import-LocalizedData importa dados de arquivos .psd1 de 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 de 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 de usuário, um caminho e um nome de arquivo alternativos, além de adicionar comandos suportados e suprimir a mensagem de erro que aparece se os arquivos .psd1 não forem localizados.

O cmdlet Import-LocalizedData suporta a internacionalização de scripts no Windows PowerShell 2.0. Esta iniciativa tem como objetivo atender melhor os usuários do mundo todo, pois possibilita aos scripts exibirem mensagens de usuário no idioma de interface do usuário atual. Para obter mais informações sobre esse recurso e sobre o formato dos arquivos .psd1, consulte about_Script_Internationalization.

Parâmetros

-BaseDirectory <string>

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

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-BindingVariable <string>

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

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

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-FileName <string>

Especifica o nome do arquivo .psd1 a ser importado. Digite um nome de arquivo sem a extensão .psd1.

O padrão é o nome do script. Por exemplo, se o script for FindFiles.ps1, Import-LocalizedData procurará FindFiles.psd1. Você pode usar este parâmetro para direcionar Import-LocalizedData para procurar um arquivo .psd1 diferente.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-SupportedCommand <string[]>

Especifica cmdlets e funções que só geram dados.

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

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-UICulture <string>

Especifica uma cultura de interface do usuário alternativa. O padrão é o valor da variável automática $PsUICulture. Digite uma cultura de interface do usuário no formato " <idioma> - <região>", como en-US, de-DE ou ar-SA.

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

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

Necessário?	false
Posição?	2
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas	Nenhum Você não pode canalizar a entrada para este cmdlet.
Saídas	System.Collections.Hashtable Import-LocalizedData 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 uma tabela de hash de pares de chave e valor e salve a tabela de hash em um arquivo com o mesmo nome do script e a extensão .psd1. Crie um diretório sob o diretório de script para cada cultura da interface do usuário suportada e salve o arquivo .psd1 para cada cultura da interface do usuário no diretório com o nome de cultura da interface do usuário.

Por exemplo, localize suas mensagens de usuário para a localidade de-DE e formate-as em uma tabela de hash. Salve a tabela de hash em um arquivo .psd1 < ScriptName >. Então crie um subdiretório de-DE sob o diretório de script e salve o arquivo .psd1 < ScriptName > de-DE no subdiretório de-DE. Repita este método para cada localidade que você suportar.

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

Import-LocalizedData começa a pesquisa no diretório onde o arquivo de script é localizado (o valor do parâmetro BaseDirectory). O cmdlet procura no diretório base um subdiretório de mesmo nome do valor da variável $PsUICulture (ou o valor do parâmetro UICulture), como "de-DE" ou "ar-SA”. Então, pesquisa naquele subdiretório um arquivo .psd1 com o mesmo nome do script (ou o valor do parâmetro FileName).

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

Se Import-LocalizedData localizar 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. Então, ao exibir uma mensagem da tabela de hash na variável, a mensagem localizada é exibida.

Para obter mais informações, consulte about_Script_Internationalization.

Exemplo 1

C:\PS>import-localizeddata -bindingVariable messages

Descrição
-----------
Este comando importa cadeias de texto na variável $messages. Ele usa todos os valores padrão para os parâmetros de cmdlet.

Se o comando for 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 importa o arquivo Archives.psd1 para o diretório C:\test\zh-CN.

Exemplo 2

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

Descrição
-----------
Este comando importa cadeias de texto para a variável $msgTbl de um script. 

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

Descrição
-----------
Este exemplo mostra como usar dados localizados em um script simples.

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 texto nomeadas em uma tabela de hash. 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 .psd1 correspondente na variável $Messages e um comando Write-Host que escreve 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 de interface do usuário definido para o usuário atual do sistema operacional.

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

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

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 tabela de hash e o armazena no valor da variável $UserMessages. 

Além disso, o script inclui um comando Import-LocalizedData, o qual importa uma tabela de hash de cadeias de texto convertidas do arquivo TestScript.psd1 no subdiretório especificado pelo valor da variável $PsUICulture. Se o comando localizar o arquivo .psd1, ele salvará as cadeias de caracteres convertidas do arquivo no valor da mesma variável $ UserMessages, substituindo a tabela de hash salva pela lógica de seção DATA.

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

Se o comando Import-LocalizedData localizar um arquivo .psd1 para o idioma $PsUICulture, o valor da variável $UserMessages conterá as cadeias de texto convertidas. Se o comando falhar por qualquer razão, o comando exibirá as cadeias de texto padrão definidas na seção DATA do script.

Exemplo 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

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

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

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

O exemplo de saída mostra os resultados da execução de ambos os scripts quando a cultura da interface do usuário é definida para fr-BE e não há nenhum arquivo ou diretório compatível para aquela cultura de interface do usuário. Day1.ps1 exibe uma mensagem de erro e saída em inglês. Day2.ps1 exibe apenas a saída em inglês.

Consulte também

Conceitos

about_Script_Internationalization