Localize cadeias na interface da aplicação e no manifesto do pacote da aplicação

Para saber mais sobre a proposta de valor de localizar a sua aplicação Windows App SDK, consulte Globalização e localização .

Se pretender que a sua aplicação ofereça suporte a diferentes idiomas de exibição e tiver literais de texto no seu código, marcação XAML ou manifesto do pacote da aplicação, mova esses textos para um Arquivo de Recursos (.resw). Em seguida, você pode fazer uma cópia traduzida desse Arquivo de Recursos para cada idioma compatível com seu aplicativo.

Literais de texto codificados podem aparecer em código imperativo ou em XAML, por exemplo, como a propriedade Text de um TextBlock. Eles também podem aparecer no ficheiro de origem do manifesto do pacote da aplicação (o ficheiro Package.appxmanifest), por exemplo, como valor para Nome de Exibição na guia Aplicação do Designer de Manifesto do Visual Studio. Mova estas strings para um ficheiro de recursos (.resw) e substitua os literais de strings com código fixo na sua aplicação e no seu manifesto por referências a identificadores de recursos.

Ao contrário dos recursos de imagem, em que apenas um recurso de imagem está contido num ficheiro de recursos de imagem, múltiplos recursos de cadeia de caracteres estão contidos num ficheiro de recursos de cadeia de caracteres. Um arquivo de recurso de cadeia de caracteres é um arquivo de recursos (.resw), e você normalmente cria esse tipo de arquivo de recurso em uma pasta \Strings em seu projeto. Para obter informações básicas sobre como usar qualificadores nos nomes de seus Arquivos de Recursos (.resw), consulte Adaptar seus recursos para idioma, escala e outros qualificadores.

Armazenar cadeias de caracteres em um arquivo de recursos

1. Defina o idioma padrão do seu aplicativo.

   1. Com sua solução aberta no Visual Studio, abra Package.appxmanifest.
   2. Na guia Aplicativo, confirme se o idioma padrão está definido adequadamente (por exemplo, "en" ou "en-US"). As etapas restantes assumirão que você definiu o idioma padrão como "en-US".

   Observação

   No mínimo, você precisa fornecer recursos de cadeia de caracteres localizados para esse idioma padrão. Esses são os recursos que serão carregados se nenhuma correspondência melhor puder ser encontrada para o idioma preferido do usuário ou configurações de idioma de exibição.

2. Crie um arquivo de recursos (.resw) para o idioma padrão.

   1. Dentro do nó do seu projeto, crie uma nova pasta e dê-lhe o nome de Strings.
   2. Em Strings, crie uma nova subpasta e nomeie-a en-US.
   3. Em en-US, crie um novo Arquivo de Recursos (.resw) (sob a tipos de arquivo WinUI na caixa de diálogo Adicionar Novo Item) e confirme se ele é nomeado Resources.resw.

   Observação

   Se você tiver arquivos de recursos .NET (.resx) que deseja portar, consulte Portando XAML e UI.

3. Abra Resources.resw e adicione esses recursos de cadeia de caracteres.

   Strings/en-US/Resources.resw

   

   Neste exemplo, "Saudação" é um identificador de recurso de cadeia de caracteres ao qual você pode se referir a partir de sua marcação, como mostraremos. Para o identificador "Greeting", uma cadeia de caracteres é fornecida para uma propriedade Text e uma cadeia de caracteres é fornecida para uma propriedade Width. "Greeting.Text" é um exemplo de um identificador de propriedade porque corresponde a uma propriedade de um elemento da interface do usuário. Você também pode, por exemplo, adicionar "Greeting.Foreground" na coluna Nome e definir seu Valor como "Vermelho". O identificador "Farewell" é um identificador de recurso de cadeia de caracteres simples; ele não tem subpropriedades e pode ser carregado a partir de código imperativo, como mostraremos. A coluna Comentários é um bom lugar para fornecer instruções especiais aos tradutores.

   Neste exemplo, como temos uma entrada simples de identificador de recurso de cadeia de caracteres chamada "Farewell", não podemos também ter identificadores de propriedade baseados nesse mesmo identificador. Assim, adicionar "Farewell.Text" causaria um erro de entrada duplicada ao criar Resources.resw.

   Os identificadores de recurso não diferenciam maiúsculas de minúsculas e devem ser exclusivos por arquivo de recurso. Certifique-se de usar identificadores de recursos significativos para fornecer contexto adicional para os tradutores. E não altere os identificadores de recursos depois que os recursos de cadeia de caracteres forem enviados para tradução. As equipes de localização usam o identificador de recurso para controlar adições, exclusões e atualizações nos recursos. As alterações nos identificadores de recursos — que também é conhecida como "deslocamento de identificadores de recursos" — exigem que as cadeias de caracteres sejam retraduzidas, porque aparecerá como se as cadeias de caracteres tivessem sido excluídas e outras adicionadas.

Consulte um identificador de recurso de cadeia de caracteres de XAML

Você usa um diretiva x:Uid para associar um controle ou outro elemento em sua marcação com um identificador de recurso de cadeia de caracteres.

<TextBlock x:Uid="Greeting"/>

Em tempo de execução, \Strings\en-US\Resources.resw é carregado (já que agora esse é o único arquivo de recursos no projeto). A diretiva x:Uid no TextBlock faz com que uma pesquisa ocorra, para localizar identificadores de propriedade dentro Resources.resw que contêm o identificador de recurso de cadeia de caracteres "Saudação". Os identificadores de propriedade "Greeting.Text" e "Greeting.Width" são encontrados e os seus valores são aplicados ao TextBlock, substituindo quaisquer valores definidos localmente na marcação. O valor "Greeting.Foreground" também seria aplicado se você tivesse adicionado isso. Mas apenas identificadores de propriedade são usados para definir propriedades em elementos de marcação XAML, portanto, definir x:Uid como "Farewell" neste TextBlock não teria efeito. Resources.resw contém o identificador de recurso de cadeia de caracteres "Farewell", mas não contém identificadores de propriedade para ele.

Ao atribuir um identificador de recurso de cadeia de caracteres a um elemento XAML, certifique-se de que, todos os identificadores propriedade para esse identificador são apropriados para o elemento XAML. Por exemplo, se definires x:Uid="Greeting" num TextBlock, o "Greeting.Text" será processado porque o tipo TextBlock tem uma propriedade Text. Mas se definires x:Uid="Greeting" num botão , "Greeting.Text" causará um erro em tempo de execução porque o tipo de botão não tem uma propriedade de Texto. Uma solução para esse caso é criar um identificador de propriedade chamado "ButtonGreeting.Content" e definir x:Uid="ButtonGreeting" no Button.

Em vez de definir a largura de a partir de um ficheiro de recursos, desejará provavelmente permitir que os controlos se ajustem dinamicamente ao conteúdo.

Greeting.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name

Consulte um identificador de recurso de texto no código.

Você pode carregar explicitamente um recurso de cadeia de caracteres com base em um identificador de recurso de cadeia de caracteres simples.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader();
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Farewell");

Você pode usar esse mesmo código de dentro de um projeto de biblioteca de classes. Durante a execução, os recursos da aplicação que hospeda a biblioteca são carregados. Recomendamos que uma biblioteca carregue recursos do aplicativo que a hospeda, pois é provável que o aplicativo tenha um maior grau de localização. Se uma biblioteca precisar fornecer recursos, ela deve dar ao seu aplicativo de hospedagem a opção de substituir esses recursos como entrada.

Se um nome de recurso for segmentado (ele contém caracteres "." ), substitua pontos por caracteres de barra ("/") no nome do recurso. Os identificadores de propriedade, por exemplo, contêm pontos; então você precisaria fazer essa substituição para carregar um desses do código.

this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Fare/Well"); // <data name="Fare.Well" ...> ...

Em caso de dúvida, você pode usar MakePri.exe para despejar o arquivo PRI do seu aplicativo. O uri de cada recurso é mostrado no arquivo despejado.

<ResourceMapSubtree name="Fare"><NamedResource name="Well" uri="ms-resource://<GUID>/Resources/Fare/Well">...

Consulte um identificador de recurso de cadeia no manifesto do pacote de aplicativos.

1. Abra o arquivo de origem do manifesto do pacote do aplicativo (o arquivo Package.appxmanifest), no qual, por padrão, a Display name do aplicativo é expressa como uma cadeia de caracteres literal.

   

2. Para criar uma versão localizável dessa cadeia de caracteres, abra Resources.resw e adicione um novo recurso de cadeia de caracteres com o nome "AppDisplayName" e o valor "Adventure Works Cycles".

3. Substitua o literal da cadeia de caracteres "nome de exibição" por uma referência ao identificador de recurso da cadeia de caracteres que acabou de criar ("AppDisplayName"). Use o esquema ms-resource URI (Uniform Resource Identifier) para fazer isso.

   

4. Repita esse processo para cada cadeia de caracteres em seu manifesto que você deseja localizar. Por exemplo, o Nome abreviado do seu aplicativo (que você pode configurar para aparecer no bloco do seu aplicativo na tela inicial). Para obter uma lista de todos os itens do manifesto do pacote da aplicação que podem ser localizados, consulte Itens de manifesto localizáveis.

Localizar os recursos de strings

1. Faça uma cópia do seu Arquivo de Recursos (.resw) para outro idioma.

   1. Em "Strings", crie uma nova subpasta e nomeie-a "de-DE" para Deutsch (Deutschland).

   Observação

   Para o nome da pasta, podes usar qualquer etiqueta de idioma BCP-47 . Consulte Adaptar seus recursos para idioma, escala e outros qualificadores para obter detalhes sobre o qualificador de idioma e uma lista de tags de idioma comuns. 2. Faça uma cópia de Strings/en-US/Resources.resw na pasta Strings/de-DE.

2. Traduza as cadeias de caracteres.

   1. Abra Strings/de-DE/Resources.resw e traduza os valores na coluna Valor. Não é necessário traduzir os comentários.

   Strings/de-DE/Resources.resw

   

Se quiser, pode repetir os passos 1 e 2 para um outro idioma.

Strings/fr-FR/Resources.resw

Testar seu aplicativo

Teste o aplicativo para seu idioma de exibição padrão. Em seguida, pode alterar o idioma de exibição em Configurações>Hora e Idioma>Região e idioma>Idiomas e testar novamente a sua aplicação. Veja as cadeias de caracteres na interface do utilizador e também no shell (por exemplo, a barra de título, que é o nome de exibição, e o Nome abreviado nos ícones).

Fatoração de cadeias de caracteres em vários arquivos de recursos

Você pode manter todos os seus strings em um único Arquivo de Recursos (resw), ou pode dividi-los em vários Arquivos de Recursos. Por exemplo, talvez você queira manter suas mensagens de erro em um arquivo de recursos, as cadeias de caracteres de manifesto do pacote do aplicativo em outro e as cadeias de caracteres da interface do usuário em um terceiro. Nesse caso, a sua estrutura de pastas ficaria assim.

Para definir o escopo da referência de um identificador de recurso de cadeia de caracteres para um arquivo específico, basta adicionar /<resources-file-name>/ antes do identificador. O exemplo de marcação abaixo pressupõe que ErrorMessages.resw contém um recurso cujo nome é "PasswordTooWeak.Text" e cujo valor descreve o erro.

<TextBlock x:Uid="/ErrorMessages/PasswordTooWeak"/>

Você só precisa adicionar /<resources-file-name>/ antes do identificador de recurso de string para Arquivos de Recursos , excetoResources.resw. Isso porque "Resources.resw" é o nome de arquivo padrão, então é isso que é assumido se você omitir um nome de arquivo (como fizemos nos exemplos anteriores neste tópico).

O exemplo de código abaixo pressupõe que ErrorMessages.resw contém um recurso cujo nome é "MismatchedPasswords" e cujo valor descreve o erro.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ErrorMessages");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("MismatchedPasswords");

Se você fosse mover seu recurso "AppDisplayName" de Resources.resw para ManifestResources.resw, no manifesto do pacote do aplicativo você mudaria ms-resource:AppDisplayName para ms-resource:/ManifestResources/AppDisplayName.

Se um nome de arquivo de recurso estiver segmentado (ele contém caracteres "." ), deixe os pontos no nome quando você fizer referência a ele. Não substitua os pontos por barras ("/"), como faria com um nome de recurso.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("Err.Msgs");

Em caso de dúvida, você pode usar MakePri.exe para despejar o arquivo PRI do seu aplicativo. O uri de cada recurso é mostrado no arquivo despejado.

<ResourceMapSubtree name="Err.Msgs"><NamedResource name="MismatchedPasswords" uri="ms-resource://<GUID>/Err.Msgs/MismatchedPasswords">...

Carregar um texto para um idioma específico ou outro contexto

O ResourceContext padrão (obtido ao criar um ResourceLoader) contém um valor de qualificador para cada nome de qualificador, representando o contexto de execução padrão (ou seja, as configurações para o utilizador e máquina atuais). Os Arquivos de Recursos (.resw) são comparados — com base nos qualificadores nos seus nomes — com os valores do qualificador nesse contexto de execução.

Mas pode haver momentos em que você queira que seu aplicativo substitua as configurações do sistema e seja explícito sobre o idioma, a escala ou outro valor qualificador a ser usado ao procurar um Arquivo de Recursos correspondente para carregar. Por exemplo, você pode querer que seus usuários possam selecionar um idioma alternativo para dicas de ferramentas ou mensagens de erro.

Você pode fazer isso construindo um novo ResourceContext, substituindo seus valores e, em seguida, usando esse objeto de contexto em suas pesquisas de cadeia de caracteres.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Language"] = "de-DE";
var resourceMap = resourceManager.MainResourceMap.GetSubtree("Resources");
this.myXAMLTextBlockElement.Text = resourceMap.GetValue("Farewell", resourceContext).ValueAsString;

Usar QualifierValues como no exemplo de código acima funciona para qualquer qualificador. Para o caso especial de Linguagem, pode alternativamente fazer isto.

resourceContext.Languages = new string[] { "de-DE" };

Carregar cadeias de caracteres de uma biblioteca de classes

Os recursos de cadeia de caracteres de uma biblioteca de classes referenciada normalmente são adicionados a uma subpasta do pacote no qual estão incluídos durante o processo de compilação. O identificador de recurso de tal cadeia de caracteres geralmente assume a forma LibraryName/ResourcesFileName/ResourceIdentifier.

Uma biblioteca pode obter um ResourceLoader para os seus próprios recursos. Por exemplo, o código a seguir ilustra como uma biblioteca ou um aplicativo que faz referência a ela pode obter um ResourceLoader para os recursos de cadeia de caracteres da biblioteca.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ContosoControl/Resources");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("exampleResourceName");

Em caso de dúvida sobre o caminho, você pode especificar MakePri.exe opções de linha de comando para despejar o arquivo PRI do componente ou da biblioteca. O uri de cada recurso é mostrado no arquivo despejado.

<NamedResource name="exampleResourceName" uri="ms-resource://Contoso.Control/Contoso.Control/ReswFileName/exampleResourceName">...

Carregando strings de outros pacotes

Os recursos de um pacote de aplicações são geridos e acedidos através do ResourceMap de nível superior do próprio pacote, que pode ser acedida a partir doResourceManager. Dentro de cada pacote, vários componentes podem ter as suas próprias subárvores ResourceMap, que pode aceder através de ResourceMap.GetSubtree.

Um pacote de estrutura pode acessar seus próprios recursos com um URI de identificador de recurso absoluto. Consulte também esquemas de URI na documentação da UWP para obter mais informações.

Carregando cadeias de caracteres em aplicações não embaladas

A partir da versão 1903 do Windows (atualização de maio de 2019), os aplicativos não empacotados também podem aproveitar o Sistema de Gerenciamento de Recursos.

Basta criar seus controles/bibliotecas de usuário do SDK do Windows App e armazenar cadeias de caracteres em um arquivo de recursos. Em seguida, você pode fazer referência a um identificador de recurso de cadeia de caracteres deXAML a um identificador de recurso de cadeia de caracteres de códigoou carregar cadeias de caracteres de uma Biblioteca de Classes.

Para usar recursos em aplicativos não empacotados, você deve fazer algumas coisas:

1. Use o construtor sobrecarregado do ResourceManager para passar o nome do arquivo .pri do seu aplicativo ao resolver recursos do código, pois não há exibição padrão em cenários não empacotados.
2. Use MakePri.exe para gerar manualmente o arquivo resources.pri do seu aplicativo.
   • Executar makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri
   • O <PRICONFIG> deve omitir a seção "<packaging>" para que todos os recursos sejam agrupados em um único arquivo resources.pri. Se usar o arquivo de configuração padrão MakePri.exe criado por createconfig, é necessário excluir a seção "<packaging>" manualmente depois de ser criado.
   • O< PRICONFIG >deve conter todos os indexadores relevantes necessários para mesclar todos os recursos em seu projeto em um único arquivo resources.pri. O arquivo de configuração de MakePri.exe padrão criado por createconfig inclui todos os indexadores.
   • Se você não usar a configuração padrão, verifique se o indexador PRI está habilitado (revise a configuração padrão para saber como fazer isso) para mesclar PRIs encontrados a partir de referências de projeto, referências NuGet e assim por diante, que estão localizados na raiz do projeto.

     Observação

     Ao omitir /IndexNamee pelo projeto não ter um manifesto de aplicação, o namespace IndexName/root do arquivo PRI é automaticamente definido como Application, que o tempo de execução entende para aplicações não empacotadas (isto remove a dependência rígida anterior da ID do pacote). Ao especificar URIs de recursos, as referências ms-resource:/// que omitem o namespace raiz inferem Application como o namespace raiz para aplicativos não empacotados (ou você pode especificar Application explicitamente como em ms-resource://Application/).

3. Copie o arquivo PRI para o diretório de saída de compilação do .exe
4. Execute o .exe

   Observação

   O Sistema de Gerenciamento de Recursos usa o idioma de exibição do sistema em vez da lista de idiomas preferidos do usuário ao resolver recursos com base no idioma em aplicativos não empacotados. A lista de idiomas preferidos do usuário é usada apenas para aplicativos empacotados do SDK de aplicativos do Windows App.

APIs importantes

• ApplicationModel.Resources.ResourceLoader

Ver também

• Amostra do núcleo MRT
• Como carregar recursos de cadeia de caracteres