Compartilhar via


about_Script_Internationalization

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