about_Script_Internationalization

Artigo
11/17/2015

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0

TÓPICO

DESCRIÇÃO BREVE

Descreve os recursos de internacionalização de script do Windows PowerShell® 2.0 que facilita a exibição de mensagens e instruções por scripts para os usuários no seu idioma de UI (interface do usuário).

DESCRIÇÃO LONGA

Os recursos de internacionalização de script do Windows PowerShell permitem que você atenda melhor os usuários em todo o mundo, exibindo mensagens de ajuda e de usuário para scripts e funções no idioma da UI.

Os recursos de internacionalização de script consulta a cultura de UI do sistema operacional durante a execução, importam as cadeias de caracteres de texto traduzido apropriadas e exibem para o usuário. A seção de dados permite armazenar cadeias de caracteres de texto separadas do código para que elas sejam facilmente identificadas e extraídas. Um novo cmdlet, ConvertFrom-StringData, converte cadeias de caracteres 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 script não têm suporte pelo Windows PowerShell 1.0. Os scripts que incluem esses recursos não serão executados no Windows PowerShell 1.0 sem modificação.

Para dar suporte a texto de ajuda internacional, o Windows PowerShell 2.0 inclui os seguintes recursos:

-- Uma seção de dados que separa cadeias de caracteres de texto de instruções de código. Para obter mais informações sobre a seção de dados, consulte about_Data_Sections.
-- Novas variáveis automáticas, $PSCulture e $PSUICulture. $PSCulture armazena o nome do idioma da UI usado no sistema para elementos, como data, hora e moeda. A variável $PSUICulture armazena o nome do idioma da UI usado no sistema para elementos de interface do usuário, como menus e cadeias de caracteres de texto.
-- Um cmdlet, ConvertFrom-StringData, converte cadeias de caracteres 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 caracteres de texto traduzido. Os arquivos .psd1 são armazenados em subdiretórios específicos a um idioma do diretório do script.
-- Um cmdlet, Import-LocalizedData, que importa cadeias de caracteres de texto traduzido para um idioma especificado em um script no 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 DE DADOS: ARMAZENANDO CADEIAS DE CARACTERES PADRÃO

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

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

No exemplo a seguir, a seção de dados do script World.ps1 inclui o conjunto Inglês-Estados Unidos (en-US) das mensagens de prompt 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 here-strings, consulte about_Quoting_Rules.

ARQUIVOS PSD1: ARMAZENANDO CADEIAS DE CARACTERES TRADUZIDAS

Salve as mensagens de script para cada idioma de UI em arquivos de texto separados com o mesmo nome que o script e a extensão de nome de arquivo .psd1. 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 script World.ps1 é armazenado no diretório C:\Scripts, você criaria uma estrutura de diretórios 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 arquivo World.psd1 no subdiretório de-DE do diretório do script pode incluir a seguinte instrução:

        ConvertFrom-StringData @'
            helloWorld = Hello, World (in German).
            errorMsg1 = You cannot leave the user name field blank (in German).
            promptMsg = Please enter your user name (in German).
        '@

De modo semelhante, o arquivo World.psd1 no subdiretório ar-SA do diretório do script pode incluir a seguinte instrução:

        ConvertFrom-StringData @'
            helloWorld = Hello, World (in Arabic).
            errorMsg1 = You cannot leave the user name field blank (in Arabic).
            promptMsg = Please enter your user name (in Arabic).
        '@

IMPORT-LOCALIZEDDATA: RECUPERAÇÃO DINÂMICA DE CADEIAS DE CARACTERES TRADUZIDAS

Para recuperar as cadeias de caracteres no idioma da UI do usuário atual, use o cmdlet Import-LocalizedData. Insira o corpo da seção aqui.

Import-LocalizedData localiza o valor da variável $PSUICulture automática e importa o conteúdo dos arquivos <script-name>.psd1 no subdiretório que corresponde ao valor de $PSUICulture. 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 comando Import-LocalizedData aparece no script C:\Scripts\World.ps1 e o valor de $PSUICulture é "ar-SA", Import-LocalizedData encontra o seguinte arquivo:

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

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

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

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

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

Se a Import-LocalizedData não localizar um arquivo .psd1 que corresponde ao valor de $PSUIculture, o valor de $msgTable não é substituído e a chamada para $msgTable.promptMsg exibe as cadeias de caracteres en-US de fallback.

EXEMPLO

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

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

O script começa com uma seção de dados chamada Day ($Day) que contém um comando ConvertFrom-StringData. A expressão enviada ao ConvertFrom-StringData é uma here-string que contém os nomes de dias na cultura da UI padrão, en-US, em pares de chave/valor. O cmdlet ConvertFrom-StringData converte os pares de chave/valor na here-string em uma tabela de hash e, então, a salva no valor da variável $Day.

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

Os comandos restantes carregam as cadeias de caracteres em uma matriz e exibe-os.

        $Day = DATA {
        # culture=\"en-US\"
        ConvertFrom-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 arquivos .psd1 que dão suporte ao script são salvos em subdiretórios do diretório do script com nomes que correspondem aos valores $PSUICulture.

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

        # culture=\"de-DE\"
        ConvertFrom-StringData @'
        messageDate = Today is 
            d0 = Sunday (in German)
            d1 = Monday (in German)
            d2 = Tuesday (in German)
            d3 = Wednesday (in German)
            d4 = Thursday (in German)
            d5 = Friday (in German)
            d6 = Saturday (in German)
        '@

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

        Today is Friday (in German)

CONSULTE TAMBÉM

about_Data_Sections

about_Automatic_Variables

about_Hash_Tables

about_Quoting_Rules

ConvertFrom-StringData

Import-LocalizedData

about_Script_Internationalization

TÓPICO

DESCRIÇÃO BREVE

DESCRIÇÃO LONGA

A SEÇÃO DE DADOS: ARMAZENANDO CADEIAS DE CARACTERES PADRÃO

ARQUIVOS PSD1: ARMAZENANDO CADEIAS DE CARACTERES TRADUZIDAS

IMPORT-LOCALIZEDDATA: RECUPERAÇÃO DINÂMICA DE CADEIAS DE CARACTERES TRADUZIDAS

EXEMPLO

CONSULTE TAMBÉM

Recursos adicionais