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 pastasres/anim-<qualifiers>
.res/xml/
: obrigatório se você tiver pastasres/xml-<qualifiers>
.res/raw/
: obrigatório se você tiver pastasres/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:
res/values/strings.xml
Contém texto em inglês para todas as strings que o app usa, incluindo texto para uma string chamadatitle
.res/values-fr/strings.xml
Contém texto em francês para todas as strings, incluindotitle
.res/values-ja/strings.xml
Contém texto em japonês para todas as strings, excetotitle
.
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 arquivores/values/strings.xml
. - Se o dispositivo estiver configurado para o francês, o Android vai carregar
title
pelo arquivores/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 incluitext_a
no idioma padrão do app, no caso, inglês.res/values-hi/strings.xml
, que incluitext_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:
- Escolha a localidade que você quer testar e determine a tag de idioma BCP-47,
como
fr-CA
para francês canadense.
- Inicie um emulador.
- 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
- 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:
- 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 emres/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. - Execute o app.
- 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.