Localizar o aplicativo

O Android é usado por muitos dispositivos em várias regiões. Para alcançar o maior número possível de usuários, verifique se o app processa textos, arquivos de áudio, números, moedas e gráficos da maneira correta nas localidades em que ele será usado.

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

Ter conhecimento prático de programação em Kotlin ou Java linguagem natural e se familiarizar com Carregamento de recursos do Android, declarar 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 app da funcionalidade principal:

  • Coloque a maior parte ou todo o conteúdo da interface do usuário do app em arquivos de recurso, conforme descrito nesta página e na Visão geral de recursos de app.
  • O comportamento da interface do usuário, por outro lado, é orientado pelo código baseado em Kotlin ou Java. Por exemplo, se os usuários inserirem dados que precisam ser formatados ou classificados de forma diferente dependendo da localidade, use o Kotlin ou a linguagem de programação Java para gerenciar os dados programaticamente. Este tópico não aborda como localizar o código baseado em Kotlin ou Java.

Para um guia rápido sobre localização de strings no seu app, consulte Suporte para diferentes idiomas e culturas.

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 atendem ao dispositivo.

Esta página se concentra em localização e localidades. Para uma descrição completa da alternância de recursos e todos os tipos de configuração que você pode especificar, como orientação da tela ou tipo de tela touchscreen, consulte Oferecer 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

Quando o app é executado em alguma localidade para a qual você não tenha fornecido textos específicos, 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, o app não vai 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:

O código baseado em Kotlin ou Java de um app se refere 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, quando o app for iniciado em um dispositivo com um idioma diferente do inglês, o usuário vai encontrar uma mensagem de erro e um botão "Forçar fechamento". O app não vai ser carregado.

Para evitar essa situação, verifique se existe um arquivo res/values/strings.xml definindo todas as strings necessárias. Essa 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 contendo todos os recursos chamados pelo seu app, como layouts, drawables ou animações. Para informações sobre testes, consulte a seção Testar recursos padrão.

Usar recursos de localização

Esta seção discute como criar recursos padrão e recursos alternativos. Ela também explica como os recursos são atribuídos à precedência e como você se refere a eles no código.

Criar recursos padrão

Coloque o texto padrão do app em res/values/strings.xml. Para essas strings, use o idioma padrão, aquele que você espera que a maioria dos seus usuários fale.

O conjunto de recursos padrão também inclui drawables e layouts padrão e pode incluir outros tipos de recursos, como animações. Esses recursos ficam nos diretórios abaixo:

  • 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 referência. 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.

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 Fornecer recursos alternativos. Caso contrário, seu app não poderá ser compilado.

Exemplo:

Suponha que o idioma padrão do seu app seja o inglês e que você queira localizar todo o texto do app para o francês e todo o texto, exceto o título do app, para o japonês. Nesse caso, você cria três arquivos strings.xml, 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 baseado em Kotlin ou Java se referir a R.string.title, o seguinte acontece durante a execução:

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

Se o dispositivo estiver configurado para o japonês, o Android vai procurar o title no arquivo res/values-ja/strings.xml. No entanto, como essa string não está incluída nesse arquivo, o Android vai 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 vai 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 vai 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 o código de país para dispositivos móveis (MCC) e o código de rede móvel (MNC).

Exemplo:

Suponha que você encontre esta 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 configuração abaixo:
    • 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. Para uma descrição mais detalhada do processo, consulte Como o Android encontra o melhor recurso correspondente. Todos os qualificadores estão descritos e listados em ordem de precedência na Visão geral de recursos de app.

Consultar os recursos no código

No código do seu app com base em Kotlin ou Java, a referência aos recursos é feita com a sintaxe R.resource_type.resource_name ou android.R.resource_type.resource_name. Para mais informações, consulte Acessar os recursos do app.

Gerenciar as cadeias de caracteres para localização

Esta seção descreve as práticas recomendadas para gerenciar strings relacionadas à localização.

Mover todas as strings para strings.xml

Ao criar seus apps, não fixe strings no código. Em vez disso, declare todas as strings como recursos em um arquivo strings.xml padrão, o que facilita o processo de 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 interface

Ao projetar e desenvolver suas interfaces, preste muita atenção em como você se comunica com o usuário. Em geral, use um estilo sucinto que seja amigável, mas breve, e use um estilo consistente em todas as interfaces.

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). Seguir essas recomendações faz com que seus apps pareçam mais refinados para os usuários e os ajuda a entender a interface mais rapidamente.

Além disso, use a terminologia padrão do Android sempre que possível, como para elementos da interface, como a barra de apps, o menu de opções, a barra do sistema e as notificações. 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 elas são usadas. Essa informação é essencial para os tradutores e resulta em uma tradução de melhor qualidade. Ela também ajuda você a gerenciar suas strings com mais eficácia.

Confira 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>

Considere fornecer informações de contexto como estas:

  • 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 são 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 vai 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 de posição <xliff:g>. Confira o exemplo de tag abaixo que indica que o texto "%1$s" não será modificado durante a tradução, para evitar erros 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 de posição, sempre adicione um atributo de ID que explique para o que serve o marcador. Se os apps vão substituir o valor do marcador no futuro, forneça um atributo de exemplo para esclarecer o uso esperado.

Confira 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 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 ter uma visão geral completa do processo de localização e distribuição de um app Android, consulte Traduzir e localizar seu app.

Dicas de localização

Siga estas dicas ao localizar o app.

Projete seu app para funcionar em qualquer localidade

Não presuma nada sobre o dispositivo em que um usuário executa seu app. O dispositivo 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. Crie 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, incluindo pastas res/drawable/ e res/values/ sem outros modificadores, e que contêm todas as imagens e textos de que o app precisa.

Se um único recurso padrão estiver ausente, o app não vai ser executado em um dispositivo configurado para uma localidade sem suporte. Por exemplo, se o arquivo padrão res/values/strings.xml não tiver uma string necessária para o app, quando ele for executado em uma localidade sem suporte e tentar carregar res/values/strings.xml, o usuário vai encontrar uma mensagem de erro e um botão "Forçar fechamento".

Para mais informações, consulte a seção Testar recursos padrão.

Projetar um layout flexível

Caso seja necessário reorganizar seu layout para que ele se encaixe em um determinado idioma, crie um layout alternativo para esse idioma, como res/layout-de/main.xml para um layout em alemão. No entanto, 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 é 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 o 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 apenas as strings diferentes quando o app for executado no Reino Unido. Para todas as outras strings, o app vai voltar para o padrão e usar o que estiver 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, conforme mostrado no exemplo abaixo:

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 do app

O Serviço de tradução de apps está integrado ao Play Console. Ele permite que você receba uma cotação instantânea e faça um pedido para uma empresa de tradução. É possível solicitar traduções para um ou mais idiomas de strings da interface do app, texto de detalhes na Play Store, nomes de compras no app e textos de campanha de publicidade.

Testar apps localizados

Teste o app localizado em um dispositivo ou usando o Android Emulator. Especificamente, teste o app para garantir que todos os recursos padrão necessários estejam incluídos.

Testar em um dispositivo

Não esqueça que o dispositivo em que você está testando pode ser significativamente diferente dos dispositivos disponíveis aos consumidores em outros lugares. 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 interface.

Para mudar a localidade ou o idioma de um dispositivo, use o app Configurações.

Testar em um emulador

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

Criar e usar uma localidade personalizada

Uma localidade "personalizada" é uma combinação de idioma ou região que não tem suporte explícito da imagem do sistema Android. Você pode criar uma localidade personalizada no emulador para testar como seu app é executado nela. Há duas maneiras de fazer isso:

  • Use o app "Localidade personalizada", que pode ser acessado na guia de apps. Depois de criar uma localidade personalizada, mude para ela tocando e pressionando no nome dela.
  • Mude para uma localidade personalizada pelo shell adb, conforme descrito na próxima seção.

Quando você define o emulador para uma localidade que não está disponível na imagem do sistema Android, o sistema é mostrado no idioma padrão. No entanto, o app é localizado corretamente.

Mudar a localidade do emulador pelo shell do adb

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

  1. Escolha a localidade que você quer testar e determine a tag de idioma BCP-47, como fr-CA para francês canadense.
  2. Inicie um emulador.
  3. Em um shell de linha de comando no computador host, execute este comando:
    adb shell
    ou, se você tiver um dispositivo conectado, especifique que quer usar o emulador adicionando a opção -e:
    adb -e shell
  4. No prompt do shell adb (#), execute este comando:
    setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
    Substitua as seções entre 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 faz com que o emulador seja reiniciado. Quando a tela inicial aparecer de novo, abra seu app. Ele será iniciado com a nova localidade.

Testar os recursos padrão

Para testar se um app inclui todos os recursos de string necessários, faça o seguinte:

  1. Defina o emulador ou o dispositivo para um idioma que não tem suporte do 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 sem suporte.
  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, teste de novo com outros tipos de configuração. Por exemplo, se o app tiver um arquivo de layout com o nome res/layout-land/main.xml, mas não tiver um arquivo com o nome res/layout-port/main.xml, defina o emulador ou dispositivo para a orientação retrato e verifique se o app é executado.

Próxima
Testar o aplicativo com pseudolocalidades