TÓPICO
about_Script_Internationalization
DESCRIÇÃO RESUMIDA
Descreve os recursos de internacionalização de scripts do Windows
PowerShell 2.0, que facilitam a exibição nos scripts de mensagens
e instruções para os usuários no idioma da sua interface do usuário.
DESCRIÇÃO LONGA
Os recursos de internacionalização de scripts do Windows
PowerShell permitem que você atenda melhor a usuários de todo
o mundo, exibindo a Ajuda e as mensagens para o usuário sobre
scripts e funções no idioma da interface do usuário.
Os recursos de internacionalização de scripts consultam a cultura
da interface do usuário do sistema operacional durante a execução,
importam as cadeias de texto traduzidas apropriadas e as exibem
ao usuário. A seção Data permite armazenar cadeias de texto
separadas do código, de forma a serem facilmente identificadas
e extraídas. Um novo cmdlet, ConvertFrom-StringData, converte
cadeias de texto em tabelas de hash semelhantes a um dicionário
para facilitar a tradução.
Os recursos do Windows PowerShell 2.0 usados na internacionalizaçã
o de scripts não têm suporte no Windows PowerShell 1.0. Os
scripts que incluem esses recursos não poderão ser executados no
Windows PowerShell 1.0 sem modificação.
Para dar suporte ao texto internacional de Ajuda, o Windows
PowerShell 2.0 inclui os seguintes recursos:
-- Uma seção Data que separa as cadeias de texto das
instruções de código. Para obter mais informações sobre
a seção Data, consulte about_Data_Sections.
-- Novas variáveis automáticas, $PSCulture e $PSUICulture.
$PSCulture armazena o nome do idioma de interface do
usuário usado no sistema para elementos como data, hora
e moeda. A variável $PSUICulture armazena o nome do idioma
de interface do usuário usado no sistema para elementos da
interface do usuário como menus e cadeias de texto.
-- Um cmdlet, ConvertFrom-StringData, que converte cadeias de
texto em tabelas de hash semelhantes a um dicionário para
facilitar a tradução. Para obter mais informações, consulte
ConvertFrom-StringData.
-- Um novo tipo de arquivo, .psd1, que armazena cadeias de
texto traduzidas. Os arquivos .psd1 são armazenados em
subdiretórios específicos de idioma no diretório de scripts.
-- Um cmdlet, Import-LocalizedData, que importa para um script
cadeias de texto traduzidas para um idioma especificado em
tempo de execução. Esse cmdlet reconhece e importa cadeias
de caracteres em qualquer idioma suportado pelo Windows.
Para obter mais informações, consulte Import-LocalizedData.
A SEÇÃO DATA: armazenando cadeias de caracteres padrão
Use uma seção Data no script para armazenar as cadeias de texto
no idioma padrão.
Organize as cadeias de caracteres em pares de chave/valor em uma
cadeia de caracteres here. Cada par de chave/valor deve estar em
uma linha separada. Se você incluir comentários, eles deverão
estar em linhas separadas.
O cmdlet ConvertFrom-StringData converte os pares de chave/valor
na cadeia de caracteres here em uma tabela de hash semelhante
a um dicionário, armazenada no valor de variável da seção Data.
No exemplo a seguir, a seção Data do script World.ps1 inclui
o conjunto de mensagens de prompt em inglês dos EUA (en-US) para
um script. O cmdlet ConvertFrom-StringData converte as cadeias
de caracteres em uma tabela de hash e as armazena na variável
$msgtable.
$msgTable = Data {
# culture=\\"en-US\\"
ConvertFrom-StringData @'
helloWorld = Hello, World.
errorMsg1 = You cannot leave the user name field blank.
promptMsg = Please enter your user name.
'@
}
Para obter mais informações sobre as cadeias de caracteres here, consulte
about_Quoting_Rules.
ARQUIVOS PSD1: armazenando cadeias de caracteres traduzidas
Salve as mensagens de script para cada idioma de interface do
usuário em arquivos de texto separados com o mesmo nome do script
e a extensão de nome de arquivo .psd1. Armazene os arquivos em
subdiretórios do diretório de scripts com nomes de culturas no
seguinte formato:
<idioma>-<região>
Exemplos: de-DE, ar-SA e zh-Hans
Por exemplo, se o script World.ps1 fosse armazenado no diretório
C:\Scripts, você criaria uma estrutura de diretório de arquivos
semelhante à seguinte:
C:\Scripts
C:\Scripts\World.ps1
C:\Scripts\de-DE\World.psd1
C:\Scripts\ar-SA\World.psd1
C:\Scripts\zh-CN\World.psd1
...
O arquivo World.psd1 no subdiretório de-DE do diretório de
scripts poderia incluir a seguinte instrução:
ConvertFrom-StringData @'
helloWorld = Hello, World (em alemão).
errorMsg1 = You cannot leave the user name field blank (em alemão).
promptMsg = Please enter your user name (em alemão).
'@
Da mesma forma, o arquivo World.psd1 no subdiretório ar-SA do
diretório de scripts poderia incluir a seguinte instrução:
ConvertFrom-StringData @'
helloWorld = Hello, World (em árabe).
errorMsg1 = You cannot leave the user name field blank (em árabe).
promptMsg = Please enter your user name (em árabe).
'@
IMPORT-LOCALIZEDDATA: recuperação dinâmica de cadeias de caracteres
traduzidas
Para recuperar as cadeias de caracteres no idioma de interface do
usuário atual, use o cmdlet Import-LocalizedData.
Import-LocalizedData localiza o valor da variável automática
$PSUICulture e importa o conteúdo dos arquivos <nome_do_script>.ps
d1 para o subdiretório correspondente ao valor de $PSUICulture.
Depois, salva o conteúdo importado na variável especificada pelo
valor do parâmetro BindingVariable.
import-localizeddata -bindingVariable msgTable
Por exemplo, se o comando Import-LocalizedData aparecer no script
C:\Scripts\World.ps1 e o valor de $PSUICulture for "ar-SA",
Import-LocalizedData localizará o seguinte arquivo:
C:\Scripts\ar-SA\World.psd1
Depois, importará as cadeias de texto em árabe do arquivo para a
variável $msgTable, substituindo qualquer cadeia padrão que possa
estar definida na seção Data do script World.ps1.
Como resultado, quando o script usar a variável $msgTable para
exibir mensagens para o usuário, as mensagens serão exibidas em árabe.
Por exemplo, o script a seguir exibe a mensagem "Please enter
your user name" em árabe:
if (!($username)) { $msgTable.promptMsg }
Se Import-LocalizedData não conseguir localizar um arquivo .psd1
correspondente ao valor de $PSUIculture, o valor de $msgTable não
será substituído e a chamada para $msgTable.promptMsg exibirá as
cadeias de caracteres de fallback, em en-US.
Exemplo
Este exemplo mostra como os recursos de internacionalização de
scripts são usados em um script para exibir um dia da semana aos
usuários no idioma definido no computador.
A seguir, há uma listagem completa do arquivo de script Sample1.ps1.
O script começa com uma seção Data denominada Day ($Day), que
contém um comando ConvertFrom-StringData. A expressão enviada
a ConvertFrom-StringData é uma cadeia de caracteres here que contém
os nomes dos dias na cultura de interface do usuário padrão,
en-US, em pares de chave/valor. O cmdlet ConvertFrom-StringData
converte os pares de chave/valor na cadeia de caracteres here em
uma tabela de hash, para depois salvá-la no valor da variável $Day.
O comando Import-LocalizedData importa o conteúdo do arquivo
.psd1 para o diretório correspondente ao valor da variável
automática $PSUICulture, e depois o salva na variável $Day,
substituindo os valores de $Day definidos na seção Data.
Os comandos restantes carregam as cadeias de caracteres em uma
matriz e as exibem.
$Day = DATA {
# culture=\\"en-US\\"
ConvertFrom-StringData @'
messageDate = Today is
d1 = Monday
d2 = Tuesday
d3 = Wednesday
d4 = Thursday
d5 = Friday
d6 = Saturday
d7 = Sunday
'@
}
Import-LocalizedData -BindingVariable Day
# Criar uma matriz de dias da semana.
$a = $Day.d1, $Day.d2, $Day.d3, $Day.d4, $Day.d5, $Day.d6, $Day.d7
# Obter o dia da semana como um número (Monday = 1).
# Indexar em &a para obter o nome do dia.
# Usar formatação de cadeia de caracteres para criar uma oração.
"{0} {1}" -f $Day.messageDate, $a[(get-date -uformat %u)] | Out-Host
Os arquivos .psd1 que oferecem suporte ao script são salvos em
subdiretórios do diretório de scripts com nomes correspondentes
aos valores de $PSUICulture.
A seguir, há uma listagem completa de .\pt-BR\sample1.psd1:
# culture=\\"en-US\\"
ConvertFrom-StringData @'
messageDate = Today is
d1 = Monday (em português)
d2 = Tuesday (em português)
d3 = Wednesday (em português)
d4 = Thursday (em português)
d5 = Friday (em português)
d6 = Saturday (em português)
d7 = Sunday (em português)
'@
Como resultado, quando você executar Sample.ps1 em um sistema no
qual o valor de $PSUICulture for pt-BR, a saída do script será:
Today is Friday (em português)
CONSULTE TAMBÉM
about_Data_Sections
about_Automatic_Variables
about_Hash_Tables
about_Quoting_Rules
ConvertFrom-StringData
Import-LocalizedData