Participe do evento ⁠#Android11: apresentação de lançamento da versão Beta no dia 3 de junho.

Localizar seu app

O Android é usado por muitos dispositivos em várias regiões. Para chegar ao maior número possível de usuários, seu app precisará lidar com texto, arquivos de áudio, números, unidades monetárias e gráficos de maneira apropriada às localidades em que ele será usado.

Este documento descreve as práticas recomendadas para localização de apps para Android.

É recomendável ter conhecimento prático da linguagem de programação Java, além de familiaridade com o carregamento de recursos do Android, a declaração de elementos da interface do usuário em XML, considerações de desenvolvimento como ciclo de vida da atividade e princípios gerais de internacionalização e localização.

Uma das práticas recomendadas é usar o framework de recursos do Android para separar o máximo possível os aspectos localizados do seu app da funcionalidade principal baseada em Java:

  • Você pode colocar a maior parte ou todo o conteúdo da interface do usuário do seu app em arquivos de recurso, como descrito neste documento e em Fornecer recursos.
  • O comportamento da interface do usuário, por outro lado, é orientado pelo código baseado em Java. Por exemplo, se os usuários inserirem dados que precisam ser formatados ou classificados de forma diferente dependendo da localidade, você usará a linguagem de programação Java para gerenciar os dados programaticamente. Este documento não aborda como localizar seu código baseado em Java.

Para ver um breve guia sobre localização de strings no seu app, consulte a aula Compatibilidade com diferentes idiomas.

Visão geral: alternância de recursos no Android

Recursos são strings de texto, layouts, sons, gráficos e outros dados estáticos necessários para seu app Android. Um app pode incluir vários conjuntos de recursos, cada um personalizado para uma configuração de dispositivo diferente. Quando um usuário executa o app, o Android seleciona e carrega automaticamente os recursos que melhor correspondem ao dispositivo.

Este documento se concentra em localização e localidade. Para ver uma descrição completa da alternância de recursos e todos os tipos de configuração que podem ser especificados (orientação da tela, tipo de tela touchscreen etc.), consulte Fornecimento de recursos alternativos.

Ao criar seu app, você cria recursos padrão e alternativos para ele usar. Quando os usuários executam seu app, o sistema do Android seleciona quais recursos carregar, com base na localidade do dispositivo. Para criar recursos, coloque arquivos em subdiretórios com nomes específicos dentro do diretório res/ do projeto.

Por que os recursos padrão são importantes

Sempre que o app é executado em uma localidade para a qual você não forneceu um texto específico, o Android carrega as strings padrão de res/values/strings.xml. Se esse arquivo padrão estiver ausente ou se estiver faltando uma string necessária, seu app não será executado, e o usuário receberá uma mensagem de erro. O exemplo abaixo ilustra o que pode acontecer quando o arquivo de texto padrão está incompleto.

Exemplo:

Código baseado em Java de um app com referência a apenas duas strings, text_a e text_b. Esse app inclui um arquivo de recurso localizado (res/values-en/strings.xml) que define text_a e text_b em inglês. Ele também inclui um arquivo de recurso padrão (res/values/strings.xml) que apresenta uma definição para text_a, mas não para text_b:

  • Quando o app é aberto em um dispositivo com localidade definida como inglês, ele pode ser executado sem problemas, já que res/values-en/strings.xml contém as duas strings de texto necessárias.
  • No entanto, o usuário verá uma mensagem de erro e um botão "Forçar fechamento" quando o app for aberto em um dispositivo com outro idioma. O app não será carregado.

Para evitar essa situação, verifique se existe um arquivo res/values/strings.xml definindo todas as strings necessárias. A situação se aplica a todos os tipos de recursos, não apenas strings: você precisa criar um conjunto de arquivos de recurso padrão que contenha todos os recursos chamados pelo seu app: layouts, drawables, animações etc. Para ver informações sobre testes, consulte Como testar recursos padrão.

Como usar recursos de localização

Como criar recursos padrão

Coloque o texto padrão do app em res/values/strings.xml.

As strings de texto em res/values/strings.xml precisam usar o idioma padrão, que é o idioma que você espera que a maioria dos seus usuários entenda.

O conjunto de recursos padrão também precisa incluir drawables e layouts padrão e pode incluir outros tipos de recursos, como animações:

  • res/drawable/ - diretório obrigatório com pelo menos um arquivo gráfico para o ícone do app no Google Play.
  • res/layout/ - diretório obrigatório com um arquivo XML que define o layout padrão.
  • res/anim/ - obrigatório se você tiver pastas res/anim-<qualifiers>.
  • res/xml/ - obrigatório se você tiver pastas res/xml-<qualifiers>.
  • res/raw/ - obrigatório se você tiver pastas res/raw-<qualifiers>.

Dica: no seu código, examine cada referência a um recurso do Android. Um recurso padrão precisa ser definido para cada um. Verifique também se o arquivo de strings padrão está completo: um arquivo de strings localizadas pode conter um subconjunto das strings, mas o arquivo de strings padrão precisa conter todas elas.

Como criar recursos alternativos

Uma parte importante da localização de um app é fornecer textos alternativos para idiomas diferentes. Em alguns casos, você também fornece gráficos, sons, layouts e outros recursos específicos da localidade.

Um app pode especificar vários diretórios res/<qualifiers>/, cada um com diferentes qualificadores. Para criar um recurso alternativo para uma localidade diferente, use um qualificador que especifique um idioma ou uma combinação de região e idioma. O nome de um diretório de recursos precisa estar em conformidade com o esquema de nomenclatura descrito em Fornecimento de recursos alternativos. Do contrário, seu app não será compilado.

Exemplo:

Suponha que o idioma padrão do seu app seja o inglês. Suponha também que você quer localizar todo o texto do app para o francês, e a maior parte do texto, exceto o título, para o japonês. Nesse caso, você poderá criar três arquivos strings.xml alternativos, cada um armazenado em um diretório de recursos específico de localidade:

  1. res/values/strings.xml
    Contém texto em inglês para todas as strings que o app usa, incluindo texto para uma string chamada title.
  2. res/values-fr/strings.xml
    Contém texto em francês para todas as strings, incluindo title.
  3. res/values-ja/strings.xml
    Contém texto em japonês para todas as strings, exceto title.

Se o código Java se referir a R.string.title, veja o que acontece no momento da execução:

  • Se o dispositivo estiver configurado para qualquer idioma diferente do francês, o Android carregará title pelo arquivo res/values/strings.xml.
  • Se o dispositivo estiver configurado para o francês, o Android carregará title pelo arquivo res/values-fr/strings.xml.

Observe que, se o dispositivo estiver configurado para o japonês, o Android procurará o title no arquivo res/values-ja/strings.xml. No entanto, como essa string não está incluída nesse arquivo, o Android voltará ao padrão e carregará title em inglês pelo arquivo res/values/strings.xml.

Quais recursos têm prioridade?

Se vários arquivos de recurso corresponderem à configuração de um dispositivo, o Android seguirá um conjunto de regras para decidir qual arquivo usar. Entre os qualificadores que podem ser especificados em um nome de diretório de recursos, a localidade quase sempre tem prioridade.

Exemplo:

Suponha que um app inclui um conjunto padrão de gráficos e dois outros conjuntos de gráficos, cada um otimizado para uma configuração de dispositivo diferente:

  • res/drawable/
    Contém gráficos padrão.
  • res/drawable-small-land-stylus/
    Contém elementos gráficos otimizados para uso com um dispositivo que espera a entrada de uma stylus e tem uma tela QVGA de baixa densidade na orientação paisagem.
  • res/drawable-ja/
    Contém elementos gráficos otimizados para uso em japonês.

Se o app for executado em um dispositivo configurado para o japonês, o Android carregará gráficos de res/drawable-ja/, mesmo que o dispositivo espere a entrada de uma stylus e tenha uma tela QVGA de baixa densidade na orientação paisagem.

Exceção: os únicos qualificadores que têm prioridade sobre a localidade no processo de seleção são MCC e MNC (código de país do dispositivo móvel e código da rede móvel).

Exemplo:

Suponha que você tenha a seguinte situação:

  • O código do app chama R.string.text_a
  • Dois arquivos de recurso relevantes estão disponíveis:
    • res/values-mcc404/strings.xml, que inclui text_a no idioma padrão do app (no caso, inglês).
    • res/values-hi/strings.xml, que inclui text_a em hindi.
  • O app está sendo executado em um dispositivo com a seguinte configuração:
    • O chip está conectado a uma rede móvel na Índia (MCC 404).
    • O idioma está definido como hindi (hi).

O Android carrega text_a pelo res/values-mcc404/strings.xml (em inglês), mesmo que o dispositivo esteja configurado para hindi. Isso acontece porque, no processo de seleção de recursos, o Android prefere uma correspondência do MCC em vez de uma correspondência de idioma.

O processo de seleção nem sempre é tão simples quanto esses exemplos sugerem. Leia Como o Android encontra o melhor recurso correspondente para ver uma descrição mais detalhada do processo. Todos os qualificadores estão descritos e listados em ordem de precedência na Tabela 2 de Fornecimento de recursos alternativos.

Como incluir recursos no código

Se o código do seu app é baseado em Java, a referência aos recursos é feita com a sintaxe R.resource_type.resource_name ou android.R.resource_type.resource_name. Para saber mais, consulte Acesso aos recursos.

Como gerenciar strings para localização

Mover todas as strings para strings.xml

Ao criar seus apps, não codifique nenhuma string. Em vez disso, declare todas as strings como recursos em um arquivo strings.xml padrão, facilitando a atualização e localização. As strings no arquivo strings.xml podem ser facilmente extraídas, traduzidas e integradas novamente ao app (com os qualificadores apropriados), sem nenhuma mudança no código compilado.

Se você gerar imagens com texto, coloque essas strings em strings.xml e gere novamente as imagens após a tradução.

Seguir as diretrizes do Android para strings de IU

Ao projetar e desenvolver suas IUs, preste muita atenção em como você fala com seu usuário. Em geral, use um estilo sucinto e objetivo (link em inglês) que seja amigável, mas breve, e use um estilo consistente em todas as IUs.

Não se esqueça de ler e seguir as recomendações do Material Design sobre estilo de escrita e escolha de palavras (link em inglês). Isso fará com que seus apps pareçam mais refinados para os usuários, além de ajudá-los a entender sua IU mais rapidamente.

Além disso, use a terminologia padrão do Android sempre que possível, por exemplo, para elementos da IU como "Barra de ações", "Menu de opções", "Barra de sistema", "Notificações" etc. O uso correto e consistente de termos do Android facilita a tradução e resulta em um produto final melhor para os usuários.

Fornecer contexto suficiente para strings declaradas

Ao declarar strings no seu arquivo strings.xml, descreva o contexto em que a string será usada. Essa informação é essencial para o tradutor e resulta em uma tradução de melhor qualidade. Ela também ajuda você a gerenciar suas strings com mais eficácia.

Veja um exemplo:

<!-- The action for submitting a form. This text is on a button that can fit 30 chars -->
    <string name="login_submit_button">Sign in</string>
    

Recomendamos que você forneça informações de contexto que incluam o seguinte:

  • Para que serve essa string? Quando e onde ela é apresentada ao usuário?
  • Onde isso aparece no layout? Por exemplo, as traduções são menos flexíveis em botões do que em caixas de texto.

Marcar as partes da mensagem que não serão traduzidas

Muitas vezes, as strings contêm texto que não será traduzido para outros idiomas. Exemplos comuns podem ser uma parte de código, um marcador de valor, um símbolo especial ou um nome. Ao preparar as strings para tradução, procure e marque o texto que permanecerá sem tradução para que ele não seja modificado.

Para marcar um texto que não será traduzido, use uma tag de marcador <xliff:g>. Veja uma tag de exemplo que garante que o texto "%1$s" não será mudado durante a tradução, o que poderia gerar um erro na mensagem:

    <string name="countdown">
      <xliff:g id="time" example="5 days">%1$s</xliff:g> until holiday
    </string>
    

Ao declarar uma tag de marcador, sempre adicione um atributo de ID que explique para o que é o marcador. Se os apps substituirão o valor do marcador posteriormente, forneça um atributo de exemplo para esclarecer o uso esperado.

Veja alguns exemplos de tags de marcador:

    <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <!-- Example placeholder for a special unicode symbol -->
    <string name="star_rating">Check out our 5
        <xliff:g id="star">\u2605</xliff:g>
    </string>
    <!-- Example placeholder for a for a URL -->
    <string name="app_homeurl">
        Visit us at <xliff:g
        id="application_homepage">http://my/app/home.html</xliff:g>
    </string>
    <!-- Example placeholder for a name -->
    <string name="prod_name">
        Learn more at <xliff:g id="prod_gamegroup">Game Group</xliff:g>
    </string>
    <!-- Example placeholder for a literal -->
    <string name="promo_message">
        Please use the "<xliff:g id="promotion_code">ABCDEFG</xliff:g>" to get a discount.
    </string>
    ...
    </resources>
    

Lista de verificação de localização

Para uma visão geral completa do processo de localização e distribuição de um app para Android, consulte o documento Lista de verificação de localização.

Dicas de localização

Projete seu app para funcionar em qualquer localidade

Nunca presuma nada sobre o dispositivo em que um usuário executa seu app. Ele pode ter algum hardware que você não esperava ou pode estar configurado para uma localidade que você não planejou ou em que não pode testar. Projete seu app para que ele funcione normalmente ou falhe corretamente, não importa em qual dispositivo ele seja executado.

Importante: verifique se o app inclui um conjunto completo de recursos padrão.

Não se esqueça de incluir pastas res/drawable/ e res/values/, sem outros modificadores nos nomes, com todas as imagens e textos de que o app precisa.

Se um único recurso padrão estiver ausente, o app não será executado em um dispositivo configurado para uma localidade incompatível. Por exemplo, o arquivo padrão res/values/strings.xml pode não ter uma string necessária para o app: quando o app for executado em uma localidade incompatível e tentar carregar res/values/strings.xml, o usuário verá uma mensagem de erro e um botão "Forçar fechamento".

Para mais informações, consulte Como testar recursos padrão.

Projetar um layout flexível

Se você precisar reorganizar seu layout para ajustá-lo a um determinado idioma, como o alemão, que tem palavras longas, crie um layout alternativo para esse idioma (por exemplo, res/layout-de/main.xml). No entanto, fazer isso pode dificultar a manutenção do app. É melhor criar um único layout que seja mais flexível.

Outra situação típica é um idioma que exige alguma coisa diferente no layout. Por exemplo, você pode ter um formulário de contato com dois campos de nome quando o app for executado em japonês, mas três campos de nome quando ele for executado em algum outro idioma. Isso pode ser feito de duas maneiras:

  • Crie um layout com um campo que pode ser programaticamente ativado ou desativado, dependendo do idioma.
  • Ou faça com que o layout principal inclua outro layout com o campo a ser modificado. O segundo layout pode ter configurações diferentes para idiomas diferentes.

Evite criar mais arquivos de recursos e strings de texto do que o necessário

Você provavelmente não precisa criar uma alternativa específica de localidade para todos os recursos no seu app. Por exemplo, o layout definido no arquivo res/layout/main.xml pode funcionar em qualquer localidade. Nesse caso, não seria necessário criar arquivos de layout alternativos.

Além disso, talvez não seja necessário criar um texto alternativo para cada string. Por exemplo, suponha que:

  • o idioma padrão do seu app é o inglês dos EUA; todas as strings que o app usa são definidas, com a grafia dos EUA, em res/values/strings.xml;
  • para algumas frases importantes, você quer fornecer a grafia do inglês britânico; você quer que essas strings alternativas sejam usadas quando seu app for executado em um dispositivo no Reino Unido.

Para fazer isso, crie um pequeno arquivo chamado res/values-en-rGB/strings.xml, que inclua somente as strings que precisarem ser diferentes quando o app for executado no Reino Unido. Para todo o restante das strings, o app retornará aos padrões e usará o que foi definido em res/values/strings.xml.

Use o objeto de contexto do Android para pesquisa manual de localidade

Você pode procurar a localidade usando o objeto Context disponibilizado pelo Android:

Kotlin

    val primaryLocale: Locale = context.resources.configuration.locales[0]
    val locale: String = primaryLocale.displayName
    

Java

    Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0);
    String locale = primaryLocale.getDisplayName();
    

Use o Serviço de tradução de apps

O Serviço de tradução de apps está integrado ao Play Console e também pode ser acessado pelo Android Studio (links em inglês). Ele é uma maneira rápida e simples de receber uma cotação instantânea e fazer um pedido para uma empresa de tradução. É possível solicitar traduções para um ou mais idiomas de strings da IU do app, texto de detalhes na Play Store, nomes de IAP e texto da campanha de publicidade.

Como testar apps localizados

Como testar em um dispositivo

Lembre-se de que o dispositivo em que você está testando pode ser significativamente diferente dos dispositivos disponíveis para consumidores de outras regiões. As localidades disponíveis no seu dispositivo podem ser diferentes das disponíveis em outros dispositivos. Além disso, a resolução e a densidade da tela do dispositivo podem ser diferentes, o que pode afetar a exibição de strings e drawables na IU.

Para mudar a localidade ou o idioma de um dispositivo, use o app Config.

Como testar em um emulador

Para saber mais sobre como usar o emulador, consulte Android Emulator.

Como criar e usar uma localidade personalizada

Uma localidade "personalizada" é uma combinação de idioma/região que não é explicitamente compatível com a imagem do sistema Android. Você pode testar como seu app é executado em uma localidade personalizada criando uma no emulador. Há duas maneiras de fazer isso:

  • Use o app Localidade personalizada, que pode ser acessado na guia do app. Depois de criar uma localidade personalizada, alterne para ela tocando no nome da localidade e mantendo-o pressionado.
  • Mude para uma localidade personalizada pelo adb shell, conforme descrito abaixo.

Quando você define o emulador para uma localidade que não está disponível na imagem do sistema Android, o próprio sistema é exibido no idioma padrão. No entanto, seu app provavelmente será localizado de modo correto.

Como mudar a localidade do emulador pelo adb shell

Para mudar a localidade no emulador usando o adb shell, faça o seguinte:

  1. Escolha a localidade que você quer testar e determine a tag de idioma BCP-47. Por exemplo, em francês do Canadá, fr-CA.
  2. Inicie um emulador.
  3. A partir de um shell de linha de comando no computador host, execute o seguinte comando:
    adb shell ou, se você tiver um dispositivo conectado, especifique que quer o emulador adicionando a opção -e: adb -e shell
  4. No prompt do adb shell (#), execute este comando:
    setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
    Substitua as seções com colchetes pelos códigos apropriados da Etapa 1.

Por exemplo, para testar em francês do Canadá:

setprop persist.sys.locale fr-CA;stop;sleep 5;start

Isso fará com que o emulador seja reiniciado. Isso parece uma reinicialização completa, mas não é. Quando a tela inicial aparecer novamente, abra seu app. Ele será iniciado com a nova localidade.

Como testar os recursos padrão

Veja como testar se um app inclui todos os recursos de string necessários:

  1. Defina o emulador ou o dispositivo para um idioma incompatível com o app. Por exemplo, se o app tiver strings em francês em res/values-fr/, mas não tiver strings em espanhol em res/values-es/, defina a localidade do emulador para o espanhol. Você pode usar o app Localidade personalizada para definir o emulador para uma localidade incompatível.
  2. Execute o app.
  3. Se o app exibir uma mensagem de erro e um botão "Forçar fechamento", ele pode estar procurando por uma string que não está disponível. Verifique se res/values/strings.xml inclui uma definição para cada string usada pelo app.

Se o teste for bem-sucedido, repita-o com outros tipos de configuração. Por exemplo, se o app tiver um arquivo de layout chamado res/layout-land/main.xml, mas não tiver um arquivo chamado res/layout-port/main.xml, defina o emulador ou dispositivo para a orientação retrato e veja se o app é executado.