about_Script_Internationalization

Artigo
10/04/2023

Descrição breve

Descreve os recursos de internacionalização de script que facilitam a exibição de mensagens e instruções para os usuários no idioma da interface do usuário.

Descrição longa

Os recursos de internacionalização de script do PowerShell permitem que você atenda melhor os usuários em todo o mundo exibindo mensagens de ajuda e de usuário no idioma do usuário.

Os recursos de internacionalização de script 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 para o usuário. A seção Dados permite armazenar cadeias de caracteres de texto separadas do código para que sejam facilmente identificadas e extraídas. Um novo cmdlet, ConvertFrom-StringData, converte cadeias de caracteres de texto em tabelas de hash semelhantes a dicionários para facilitar a tradução.

Para oferecer suporte ao texto da Ajuda internacional, o PowerShell inclui os seguintes recursos:

Uma seção Dados que separa cadeias de caracteres de texto de instruções de código. Para obter mais informações sobre a seção Dados, consulte about_Data_Sections.
Novas variáveis automáticas $PSCulture e $PSUICulture. $PSCulture armazena o nome do idioma da interface do usuário usado no sistema para elementos como data, hora e moeda. A $PSUICulture variável armazena o nome do idioma da interface do usuário usado no sistema para elementos da interface do usuário, como menus e cadeias de caracteres de texto.
Um cmdlet, ConvertFrom-StringData, que converte cadeias de caracteres de texto em tabelas de hash semelhantes a dicionários para facilitar a tradução. Para obter mais informações, consulte ConvertFrom-StringData.
Um novo tipo de arquivo, .psd1, que armazena cadeias de caracteres de texto traduzidas. Os .psd1 arquivos são armazenados em subdiretórios específicos do idioma do diretório de script.
Um cmdlet, Import-LocalizedData, que importa cadeias de caracteres de texto traduzidas para um idioma especificado em um script em tempo de execução. Esse cmdlet reconhece e importa cadeias de caracteres em qualquer idioma com suporte do Windows. Para obter mais informações, consulte Import-LocalizedData.

A seção Dados: Armazenando cadeias de caracteres padrão

Use uma seção Dados no script para armazenar as cadeias de caracteres de texto no idioma padrão. Organize as cadeias de caracteres em pares chave/valor em uma cadeia de caracteres aqui. Cada par chave/valor deve estar em uma linha separada. Se você incluir comentários, os comentários devem estar em linhas separadas.

O ConvertFrom-StringData cmdlet converte os pares chave/valor na cadeia de caracteres aqui em uma tabela de hash semelhante a um dicionário que é armazenada no valor da variável de seção Dados.

No exemplo a seguir, a World.ps1 seção Dados do script inclui o conjunto de mensagens de prompt Inglês-Estados Unidos (en-US) para um script. O ConvertFrom-StringData cmdlet converte as cadeias de caracteres em uma tabela de hash e as armazena $msgtable na variável.

$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 cadeias de caracteres aqui, consulte about_Quoting_Rules.

Arquivos PSD1: Armazenando cadeias de caracteres traduzidas

Salve as mensagens de script para cada idioma da interface do usuário em arquivos de texto separados com o mesmo nome do script e a extensão de nome de .psd1 arquivo. Armazene os arquivos em subdiretórios do diretório de script com nomes de culturas no seguinte formato:

<language>-<region>

Exemplos: de-DE, ar-SA e zh-Hans

Por exemplo, se o World.ps1 script for armazenado no C:\Scripts diretório, você criaria uma estrutura de diretório de arquivo 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 World.psd1 arquivo no subdiretório de-DE do diretório de script pode incluir a seguinte instrução:

ConvertFrom-StringData -StringData @'
helloWorld = Hallo, Welt.
errorMsg1 = Das Feld Benutzername darf nicht leer sein.
promptMsg = Geben Sie Ihren Benutzernamen ein.
'@

Da mesma forma, o World.psd1 arquivo no subdiretório ar-SA do diretório de script pode incluir a seguinte instrução:

ConvertFrom-StringData -StringData @'
helloWorld = مرحبًا أيها العالَم
errorMsg1 = لا يمكنك ترك حقل اسم المستخدم فارغًا
promptMsg = يرجى إدخال اسم المستخدم الخاص بك
'@

Import-LocalizedData: recuperação dinâmica de cadeias de caracteres traduzidas

Para recuperar as cadeias de caracteres no idioma da interface do usuário do usuário atual, use o Import-LocalizedData cmdlet.

Import-LocalizedData Localiza o $PSUICulture valor da variável automática e importa o conteúdo dos <script-name>.psd1 arquivos no subdiretório que corresponde ao $PSUICulture valor. Em seguida, ele salva o conteúdo importado na variável especificada pelo valor do parâmetro BindingVariable .

Import-LocalizedData -BindingVariable msgTable

Por exemplo, se o Import-LocalizedData comando aparecer no C:\Scripts\World.ps1 script e o valor de $PSUICulture for "ar-SA", Import-LocalizedData localizará o seguinte arquivo:

C:\Scripts\ar-SA\World.psd1

Em seguida, ele importa as cadeias de caracteres de texto árabe do arquivo para a $msgTable variável, substituindo quaisquer cadeias de caracteres padrão que possam ser definidas na seção Dados do World.ps1 script.

Como resultado, quando o script usa a variável para exibir mensagens do $msgTable usuário, as mensagens são exibidas em árabe.

Por exemplo, o script a seguir exibe a mensagem "Digite seu nome de usuário" em árabe:

if (!($username)) { $msgTable.promptMsg }

Se Import-LocalizedData não for possível localizar um .psd1 arquivo que corresponda ao valor de , o valor de não será substituído e a chamada para $msgTable.promptMsg exibirá as cadeias de $PSUIculture$msgTable caracteres de fallback en-US.

Exemplos

Este exemplo mostra como os recursos de internacionalização de script são usados em um script para exibir um dia da semana aos usuários no idioma definido no computador.

A seguir está uma lista completa do arquivo de script Sample1.ps1.

O script começa com uma seção Data chamada Day ($Day) que contém um ConvertFrom-StringData comando. A expressão enviada para ConvertFrom-StringData é uma cadeia de caracteres aqui que contém os nomes de dia na cultura de interface do usuário padrão, en-US, em pares chave/valor. O ConvertFrom-StringData cmdlet converte os pares chave/valor na cadeia de caracteres aqui em uma tabela de hash e, em seguida, a salva no valor da $Day variável.

O Import-LocalizedData comando importa o conteúdo do .psd1 arquivo no diretório que corresponde ao valor da $PSUICulture variável automática e, em seguida, o salva na $Day variável, substituindo os valores $Day definidos na seção Dados.

Os comandos restantes carregam as cadeias de caracteres em uma matriz e as exibem.

$Day = Data {
#culture="en-US"
ConvertFrom-StringData -StringData @'
    messageDate = Today is
    d0 = Sunday
    d1 = Monday
    d2 = Tuesday
    d3 = Wednesday
    d4 = Thursday
    d5 = Friday
    d6 = Saturday
'@
}

Import-LocalizedData -BindingVariable Day

#Build an array of weekdays.
$a = $Day.d0, $Day.d1, $Day.d2, $Day.d3, $Day.d4, $Day.d5, $Day.d6

# Get the day of the week as a number (Monday = 1).
# Index into $a to get the name of the day.
# Use string formatting to build a sentence.

"{0} {1}" -f $Day.messageDate, $a[(Get-Date -UFormat %u)] | Out-Host

Os .psd1 arquivos que oferecem suporte ao script são salvos em subdiretórios do diretório de script com nomes que correspondem aos $PSUICulture valores.

A seguir está uma lista completa de .\de-DE\sample1.psd1:

# culture="de-DE"
ConvertFrom-StringData @'
    messageDate = Heute ist
    d0 = Sonntag
    d1 = Montag
    d2 = Dienstag
    d3 = Mittwoch
    d4 = Donnerstag
    d5 = Freitag
    d6 = Samstag
'@

Como resultado, quando você executa Sample.ps1 em um sistema no qual o valor de $PSUICulture é de-DE, a saída do script é:

Heute ist Freitag