Construir aplicativos que falam a língua nativa do usuário não é mais um luxo – é uma necessidade de negócios. Como o uso de dispositivos móveis continua a explodir globalmente, os usuários esperam que os aplicativos se sintam locais, do texto que eles lêem para a formatação dos números e datas. Reaja com Nativo, o framework multiplataforma desenvolvido pela Meta, permite que os desenvolvedores criem aplicativos móveis performantes para iOS e Android a partir de uma única base de código. Adicionar suporte multilíngue a esses aplicativos, no entanto, requer planejamento cuidadoso e ferramenta correta. Este guia abrangente o acompanha através dos fundamentos da localização em Reagir Nativo, introduz as bibliotecas mais populares e fornece passos acionáveis para criar uma aplicação multilíngue pronta para produção.

Localização vs. Internacionalização: Definição dos Termos

Antes de mergulhar em código, é importante distinguir entre dois conceitos relacionados. Internacionalização (i18n)] é o processo de projetar sua aplicação para que ela possa ser adaptada a várias línguas e regiões sem precisar de mudanças de engenharia. Envolve extrair texto, usando formatação locale-sabia para datas e números, e planejamento para diferentes sistemas de escrita. Localização (l10n) é a adaptação real de seu aplicativo para uma língua ou região específica – translatando cordas, ajustando layout para scripts de direita para esquerda, e lidando com convenções locais.

O React Native em si fornece apenas algumas APIs básicas para detecção local (por exemplo, do módulo ], mas a localização completa requer uma biblioteca dedicada para gerir os recursos de tradução, a mudança de idioma e a formatação. O ecossistema oferece várias opções maduras, cada uma com os seus próprios pontos fortes.

Bibliotecas de Localização Principal para Reagir Nativo

Três bibliotecas dominam a paisagem de localização nativa Reagir. Compreender seus papéis e como eles se complementam é o primeiro passo para uma implementação robusta.

reacção- i18next

Construído em cima de i18next, um dos frameworks de internacionalização mais populares para JavaScript, é uma solução completa para o gerenciamento de tradução. Ele fornece ganchos de React (, Componentes de Ordenação Superior, e um componente de tradução que automaticamente re-render quando a linguagem muda. A biblioteca suporta o paqueamento de nomes (dividindo traduções em arquivos separados), interpolação, pluralização, traduções específicas de contexto e detecção de linguagem sofisticada.

As principais vantagens do react-i18next incluem o seu rico ecossistema de plugins e a capacidade de carregar traduções sob demanda (dividir por rota ou recurso). Ele também funciona perfeitamente com renderização do lado do servidor e pode ser usado em partes não-reagir do seu código nativo Android ou iOS através do motor i18next subjacente.

Reative-native-localize

Enquanto reacte-i18next lida com a lógica de tradução, ] lida com informações de localização do lado do dispositivo. Ele expõe a localização atual do usuário, fuso horário, unidade de temperatura, sistema de medição e tipo de calendário. Estes valores são críticos para a formatação de números, datas e moedas corretamente. Porque Reagir aplicativos nativos são executados em duas plataformas diferentes, acessando essa informação nativamente usada para ser complicado; ] envolve as APIs nativas e torna-as disponíveis como um objeto JavaScript simples.

Você pode combinar reative-native-localize com reait-i18next, alimentando a linguagem detectada para a inicialização i18next. Isso lhe dá uma experiência perfeita e orientada por dispositivos: quando o usuário muda a linguagem do telefone, o aplicativo muda automaticamente para a tradução correspondente.

i18n-js

Para projetos menores ou desenvolvedores que preferem uma abordagem leve, oferece uma API minimalista. Fornece simples buscas de tradução, regras de pluralização e formatação de data/número. No entanto, não possui detecção de linguagem integrada e não se integra com o ciclo de vida de componentes do React. Muitas equipes o usam como um módulo utilitário para traduções não-UI (por exemplo, em redutores Redux ou auxiliares API) enquanto dependem de reaja-i18next para componentes.

Uma alternativa emergente é , que está incluída no ecossistema da Expo. Ela reflete as capacidades de localização reativa, mas é adaptada para fluxos de trabalho gerenciados pela Expo. Se você estiver construindo com a Expo, é muitas vezes a maneira mais fácil de obter dados locais.

Construindo uma aplicação multilingue: Implementação passo a passo

Vamos caminhar pelo processo de adicionar localização a um novo projeto React Native usando a pilha mais comum: reaja-i18next para traduções e reaja-native-localize para detecção de locale do dispositivo.

1. Instalar dependências

Execute o seguinte comando para adicionar bibliotecas e seus pares:

npm install react-i18next i18next react-native-localize

Se você estiver usando Expo, instale em vez de e adicione os pacotes e .

2. Configurar i18next

Crie um arquivo (ou ] para TypeScript) na raiz do seu projeto. Este arquivo irá configurar a instância i18next, importar recursos de tradução e integrar o detector locale.

Abaixo está uma configuração típica:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import { getLocales } from 'react-native-localize';

import en from './locales/en.json';
import es from './locales/es.json';
import fr from './locales/fr.json';
import de from './locales/de.json';

// Detect device language
const languageDetector = {
 type: 'languageDetector',
 async: false,
 detect: () => {
 const locales = getLocales();
 return locales[0]?.languageCode ?? 'en';
 },
 init: () => {},
 cacheUserLanguage: () => {},
};

i18n
 .use(languageDetector)
 .use(initReactI18next)
 .init({
 resources: {
 en: { translation: en },
 es: { translation: es },
 fr: { translation: fr },
 de: { translation: de },
 },
 fallbackLng: 'en',
 interpolation: {
 escapeValue: false, // React already safes from XSS
 },
 });

export default i18n;

Esta configuração utiliza o react-native-localize para recuperar a linguagem principal do dispositivo. A linguagem de retrocesso garante que as traduções em falta não quebrem a UI.

3. Criar arquivos de tradução JSON

Dentro de uma pasta , crie arquivos JSON separados para cada idioma suportado. Por exemplo:

{
 "welcome": "Welcome",
 "greeting": "Hello, {{name}}!",
 "notifications": {
 "new_message": "You have {{count}} new message",
 "new_message_plural": "You have {{count}} new messages"
 }
}

{
 "welcome": "Bienvenido",
 "greeting": "¡Hola, {{name}}!",
 "notifications": {
 "new_message": "Tienes {{count}} mensaje nuevo",
 "new_message_plural": "Tienes {{count}} mensajes nuevos"
 }
}

Observe o sufixo —i18next lida automaticamente com formulários plurais com base na contagem fornecida ao chamar a função de tradução.

4. Embrulhe o aplicativo com um provedor i18next

No seu componente raiz (por exemplo, , importa a configuração i18n e envolve tudo com o (opcional, mas recomendado para a testabilidade). Na maioria dos casos, simplesmente importar é suficiente porque registra-o com o contexto do React.

import React from 'react';
import { SafeAreaView } from 'react-native';
import './i18n'; // Ensure i18n is initialized before any component
import MainScreen from './screens/MainScreen';

const App = () => (
 <SafeAreaView style={{ flex: 1 }}>
 <MainScreen />
 </SafeAreaView>
);

export default App;

5. Use traduções dentro dos componentes

Dentro de qualquer componente funcional, use o gancho para acessar a função :

import React from 'react';
import { View, Text, Button } from 'react-native';
import { useTranslation } from 'react-i18next';

const MainScreen = () => {
 const { t, i18n } = useTranslation();

 const changeLanguage = (lng) => {
 i18n.changeLanguage(lng);
 };

 return (
 <View>
 <Text>{t('welcome')}</Text>
 <Text>{t('greeting', { name: 'Maria' })}</Text>
 <Button title="Español" onPress={() => changeLanguage('es')} />
 <Button title="Français" onPress={() => changeLanguage('fr')} />
 </View>
 );
};

export default MainScreen;

A função reavalia automaticamente quando a linguagem muda, e o componente re-rende-se graças à integração de contexto Reagir.

Características de Localização Avançada

Além da tradução simples de valor-chave, aplicativos de produção requerem suporte para pluralização, formatação de data/número e adaptação de layout direita-esquerda (RTL).

Pluralização e Contexto

O i18next usa o formato de mensagem da UTI para lidar com regras plurais. O exemplo acima com e demonstra o caso mais simples. Para linguagens com regras plurais mais complexas (por exemplo, árabe, russo), você pode fornecer formulários adicionais como , , ou usar a variável dentro da interpolação.

// Example for Russian
{
 "unread_messages": "{{count}} непрочитанное сообщение",
 "unread_messages_few": "{{count}} непрочитанных сообщения",
 "unread_messages_many": "{{count}} непрочитанных сообщений"
}

Para formatar datas e números, você pode usar a API (disponível em motores JavaScript modernos) ou confiar em uma biblioteca como Luxon ou date-fns. Um padrão comum é criar funções de utilitário que aceitam uma string locale e retornar valores formatados, em seguida, usá-los ao lado de suas traduções.

Suporte à disposição da direita para a esquerda (RTL)

Reagir Nativo tem suporte incorporado para línguas RTL como o árabe e o hebraico. Habilite-o definindo o e no seu arquivo raiz, baseado na língua atual. Quando o usuário mudar para uma localidade RTL, todas as direções flexbox automaticamente invertem. No entanto, você deve garantir que seus estilos usem propriedades lógicas (por exemplo, ] em vez de ]) para evitar direções codificadas.

import { I18nManager } from 'react-native';

// Inside your language switch handler:
if (newLanguage === 'ar') {
 I18nManager.forceRTL(true);
} else {
 I18nManager.forceRTL(false);
}

Esteja ciente de que alternar RTL requer um aplicativo completo reiniciar em algumas versões Android. Você pode avisar o usuário ou implementar um reinício usando .

Melhores práticas para a Localização Preparada para Produção

Obter o básico de trabalho é uma coisa; construir um sistema de localização sustentável e escalável é outra. As seguintes melhores práticas vão poupar-lhe tempo e evitar erros frustrantes.

Organizar os Ficheiros de Tradução por Característica

Os grandes aplicativos devem evitar um único arquivo JSON monolítico por idioma. Em vez disso, use o recurso de espaço de nomes do i18next para dividir traduções por recurso ou tela. Por exemplo, , . Isto mantém os arquivos pequenos e torna os pedidos de pull de mesclagem mais fáceis. Carregue espaços de nomes sob demanda com a chamada de gancho .

Sempre forneça uma língua de retorno

O seu aplicativo nunca deve falhar porque falta uma chave de tradução. Defina uma linguagem de recurso (geralmente em inglês) que contenha todas as chaves usadas na aplicação. Se uma chave não existir na língua do usuário, o i18next irá mostrar o valor de recurso. Isto é especialmente importante durante o desenvolvimento inicial, quando nem todas as traduções estiverem completas.

Usar uma Convenção de Nomeação de Chaves

Adote uma estrutura consistente para as suas chaves de tradução. As convenções comuns incluem o uso de notação de pontos (, ]) ou imitar a hierarquia de componentes (). As chaves devem ser descritivas o suficiente para que você possa localizar o seu uso rapidamente.

Separar traduções de texto do conteúdo

Nem tudo o que aparece na UI é uma string estática. Conteúdo gerado pelo usuário, nomes de produtos ou dados dinâmicos não devem ser passados através da função – eles precisam de sua própria lógica de armazenamento e formatação. Mantenha os recursos de tradução puramente para etiquetas de aplicativos, erros e mensagens.

Automatizar fluxos de trabalho de tradução

Para equipes com tradutores profissionais, considere integrar-se com um sistema de gerenciamento de traduções (TMS) como Lokalise, Crowdin ou Phrase. Estas plataformas se conectam ao seu repositório de código, empurram strings de código atualizados e puxam arquivos traduzidos de volta. Esta automação impede traduções antigas e reduz o esforço manual.

Testando aplicativos localizados

Testando aplicativos multilingues requer mais do que apenas verificar se o texto muda. Você deve verificar se todos os elementos se ajustam corretamente, que layouts não quebram, e que a formatação de dados corresponde à localização do usuário.

Simular Locais Diferentes em Simuladores

Tanto o Xcode quanto o Android Studio permitem- lhe definir a região e a linguagem do dispositivo. Para iOS, você pode alterar o idioma nas opções Executar do esquema; para Android, você pode criar um novo emulador com uma localização personalizada. Teste cada idioma suportado em ambas as plataformas para descobrir peculiaridades específicas de plataforma (por exemplo, os catadores de datas podem não respeitar a sua localização escolhida nas versões Android mais antigas).

Procuras de Tradução de Testes de Unidade

Escreva testes unitários para a sua configuração i18n para garantir que todas as teclas se resolvem corretamente para as linguagens base e de retorno. Use uma estrutura de teste como o Jest para carregar a configuração e chamar ] para cada idioma. Uma tecla em falta aparecerá como na saída, tornando-a fácil de detectar.

import i18n from '../i18n';

test('all translation keys exist in English', () => {
 const keys = ['welcome', 'greeting', 'notifications.new_message'];
 keys.forEach(key => {
 expect(i18n.t(key)).not.toBe(key);
 });
});

Teste de Regressão Visual

Textos longos em línguas como o alemão ou o finlandês podem causar o excesso de disposição. Use o teste de instantâneo (por exemplo, instantâneos de Jest com diferentes configurações locais) ou ferramentas de regressão visual dedicadas como Percy para capturar quebra de interface. Simule o modo RTL forçando no seu ambiente de teste.

Considerações sobre o desempenho

A localização não deve comprometer o desempenho do aplicativo. Aqui estão algumas dicas para manter seu aplicativo rápido.

  • Traduções de carga despreocupadas: Use a opção do i18next] ou importações dinâmicas para obter arquivos de idioma apenas quando necessário. Isso reduz o tamanho inicial do pacote.
  • Evite re-registrar recursos: Inicialize sua instância i18n uma vez na inicialização do aplicativo. Alterar o idioma não deve exigir recarregar todos os arquivos de tradução da rede.
  • Memoize valores formatados: Se você está realizando uma data cara ou formatação de números dentro de um loop de renderização, envolva o resultado em para evitar recalculações em cada re-re-render.
  • Considere usando um cache de tradução: Para aplicativos que permitem a mudança de idioma offline, armazenar traduções em AsyncStorage ou um banco de dados local semelhante.

Conclusão

Criar um aplicativo nativo de React multilingue envolve mais do que apenas trocar strings. Requer uma arquitetura pensativa que lida com detecção local de dispositivos, gerenciamento de tradução, pluralização, formatação de números/datas e layout RTL. Ao escolher uma biblioteca robusta como reajante-i18next emparelhada com reata-nativo-localize, você pode construir uma experiência que se sinta nativa de usuários em todos os cantos do mundo.

Lembre-se que a localização é um processo contínuo - as traduções precisam de atualizações, novas linguagens podem ser adicionadas, e as nuances culturais devem ser respeitadas.Invista em ferramentas precoces, estabeleça fluxos de trabalho claros com sua equipe de tradução e teste implacavelmente.O esforço compensa a satisfação do usuário, a retenção maior e o alcance expandido do mercado.

Para mais leitura, consulte a documentação oficial de react-i18next e react-native-localize[. Você também pode encontrar a i18next plugin list útil para estender a funcionalidade. Com a estratégia correta, seu aplicativo React Native pode falar qualquer idioma fluentemente.