Import-LocalizedData
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 de Import-LocalizedData para especificar uma cultura de interface do usuário alternativa, caminho e nome de arquivo, 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
PS C:\> Import-LocalizedData -BindingVariable "Messages"
Este comando 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.
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
PS C:\> Import-LocalizedData -FileName "Test.psd1" -UICulture "en-US"
Name Value
---- -----
Msg3 "Use $_ to represent the object that is 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."
Este comando é 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 retorna uma tabela de hash que contém as cadeias de caracteres de dados localizadas.
Exemplo 3: Importar cadeias de caracteres de cultura da interface do usuário
PS C:\> 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 de C:\Data\Localized.
Exemplo 4: Importar dados localizados para um script
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 is 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.
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 caracteres de texto nomeado 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 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
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...
Este exemplo mostra como usar Import-LocalizedData para substituir cadeias de caracteres de texto padrão definidas 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 armazena o valor da variável $UserMessages.
O script também inclui um comando
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
PS C:\> # In Day1.ps1
Import-LocalizedData -BindingVariable "Day"
# In Day2.ps1
Import-LocalizedData -BindingVariable "Day" -ErrorAction:SilentlyContinue
PS C:\> .\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 PS C:\> .\Day2.ps1
Today is Tuesday
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 não consegue encontrar um arquivo .psd1 para o script nesses diretórios.
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 tabela de hash das cadeias de caracteres de texto. A tabela de hash é passada pelo pipeline ou exibida na linha de comando.
Ao usar
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 de 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 da interface do usuário em <idioma>-<região> 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) 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 o arquivo .psd1, 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 a entrada para este cmdlet.
Saídas
Hashtable
Import-LocalizedData salva a tabela de hash 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 tabela de hash de pares chave/valor e salve a tabela de hash 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 .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 tabela de hash. Salve a tabela de hash em um <ScriptName>arquivo .psd1. Em seguida, crie um subdiretório de-DE no diretório de script e salve o de-DE <ScriptName>arquivo .psd1 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 dentro do diretório base por 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 for possível encontrar o subdiretório ou o arquivo .psd1, 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 tabela de hash de mensagens do usuário para o valor do parâmetro BindingVariable no comando. Em seguida, quando você exibe uma mensagem da tabela de hash na variável, a mensagem localizada é exibida. Para obter mais informações, consulte about_Script_Internationalization (https://go.microsoft.com/fwlink/?LinkID=113262).