Traduza seu aplicativo Expo e React Native | Internacionalização (i18n)

Veja o Modelo de Aplicação no GitHub.

O que é o Intlayer?

Intlayer é uma biblioteca inovadora e open-source de internacionalização (i18n) que simplifica o suporte multilíngue em aplicações modernas. Ela funciona em diversos ambientes JavaScript/TypeScript, incluindo React Native (via o pacote react-intlayer).

Com o Intlayer, você pode:

• Gerenciar traduções facilmente usando dicionários declarativos no nível do componente.
• Garantir suporte ao TypeScript com tipos gerados automaticamente.
• Localizar dinamicamente o conteúdo, incluindo strings da interface do usuário (e no React para web, também pode localizar metadados HTML, etc.).
• Aproveitar recursos avançados, como detecção e troca dinâmica de localidade.

Passo 1: Instalar Dependências

No seu projeto React Native, instale os seguintes pacotes:

npm install intlayer react-intlayernpm install --save-dev react-native-intlayernpx intlayer init

Pacotes

• intlayer
  O kit de ferramentas i18n principal para configuração, conteúdo do dicionário, geração de tipos e comandos CLI.

• react-intlayer
  Integração React que fornece os provedores de contexto e hooks React que você usará no React Native para obter e trocar localidades.

• react-native-intlayer
  Integração React Native que fornece o plugin Metro para integrar o Intlayer com o bundler do React Native.

Passo 2: Criar uma Configuração Intlayer

Na raiz do seu projeto (ou em qualquer lugar conveniente), crie um arquivo de configuração do Intlayer. Pode ser algo assim:

/**
 * Se os tipos Locales não estiverem disponíveis, tente definir moduleResolution como "bundler" no seu tsconfig.json
 */
import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // ... Adicione quaisquer outras localidades que você precisar
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Dentro desta configuração, você pode:

• Configurar sua lista de localidades suportadas.
• Definir uma localidade padrão.
• Posteriormente, você pode adicionar opções mais avançadas (por exemplo, logs, diretórios personalizados de conteúdo, etc.).
• Veja a documentação de configuração do Intlayer para mais informações.

Passo 3: Adicione o plugin Metro

Metro é um empacotador para React Native. É o empacotador padrão para projetos React Native criados com o comando react-native init. Para usar o Intlayer com o Metro, você precisa adicionar o plugin ao seu arquivo metro.config.js:

const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => {  const defaultConfig = getDefaultConfig(__dirname);  return await configMetroIntlayer(defaultConfig);})();

Passo 4: Adicione o provedor Intlayer

Para manter sincronizada a linguagem do usuário em toda a sua aplicação, você precisa envolver seu componente raiz com o componente IntlayerProvider do react-intlayer-native.

Certifique-se de usar o provedor do react-native-intlayer em vez do react-intlayer. A exportação do react-native-intlayer inclui polyfills para a API web.

import { Stack } from "expo-router";
import { getLocales } from "expo-localization";
import { IntlayerProvider } from "react-native-intlayer";
import { type FC } from "react";

const getDeviceLocale = () => getLocales()[0]?.languageTag;

const RootLayout: FC = () => {
  return (
    <IntlayerProvider defaultLocale={getDeviceLocale()}>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      </Stack>
    </IntlayerProvider>
  );
};

export default RootLayout;

Passo 5: Declare Seu Conteúdo

Crie arquivos de declaração de conteúdo em qualquer lugar do seu projeto (comumente dentro de src/), usando qualquer um dos formatos de extensão que o Intlayer suporta:

• .content.json
• .content.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• etc.

Exemplo (TypeScript com nós TSX para React Native):

import { t, type Dictionary } from "intlayer";
import type { ReactNode } from "react";

/**
 * Dicionário de conteúdo para nosso domínio "app"
 */
import { t, type Dictionary } from "intlayer";

const homeScreenContent = {
  key: "home-screen",
  content: {
    title: t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    }),
  },
} satisfies Dictionary;

export default homeScreenContent;

Para detalhes sobre declarações de conteúdo, veja a documentação de conteúdo do Intlayer.

Passo 4: Use o Intlayer em Seus Componentes

Use o hook useIntlayer em componentes filhos para obter conteúdo localizado.

Exemplo

import { Image, StyleSheet, Platform } from "react-native";
import { useIntlayer } from "intlayer";
import { HelloWave } from "@/components/HelloWave";
import ParallaxScrollView from "@/components/ParallaxScrollView";
import { ThemedText } from "@/components/ThemedText";
import { ThemedView } from "@/components/ThemedView";
import { type FC } from "react";

const HomeScreen = (): FC => {
  const { title, steps } = useIntlayer("home-screen");

  return (
    <ParallaxScrollView
      headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
      headerImage={
        <Image
          source={require("@/assets/images/partial-react-logo.png")}
          style={styles.reactLogo}
        />
      }
    >
      <ThemedView style={styles.titleContainer}>
        <ThemedText type="title">{title}</ThemedText>
        <HelloWave />
      </ThemedView>
    </ParallaxScrollView>
  );
};

const styles = StyleSheet.create({
  titleContainer: {
    flexDirection: "row",
    alignItems: "center",
    gap: 8,
  },
});

export default HomeScreen;

Ao usar content.someKey em props baseadas em string (por exemplo, o title de um botão ou os children de um componente Text), chame content.someKey.value para obter a string real.

Se a sua aplicação já existe, você pode usar o Intlayer Compiler em conjunto com o comando extract para converter milhares de componentes em um segundo.

(Opcional) Passo 5: Alterar o Locale do App

Para trocar os locales dentro dos seus componentes, você pode usar o método setLocale do hook useLocale:

import { type FC } from "react";
import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
import { getLocaleName } from "intlayer";
import { useLocale } from "react-intlayer";

export const LocaleSwitcher: FC = () => {
  const { setLocale, availableLocales } = useLocale();

  return (
    <View style={styles.container}>
      {availableLocales.map((locale) => (
        <TouchableOpacity
          key={locale}
          style={styles.button}
          onPress={() => setLocale(locale)}
        >
          <Text style={styles.text}>{getLocaleName(locale)}</Text>
        </TouchableOpacity>
      ))}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flexDirection: "row",
    justifyContent: "center",
    alignItems: "center",
    gap: 8,
  },
  button: {
    paddingVertical: 6,
    paddingHorizontal: 12,
    borderRadius: 6,
    backgroundColor: "#ddd",
  },
  text: {
    fontSize: 14,
    fontWeight: "500",
    color: "#333",
  },
});

Isto provoca uma nova renderização de todos os componentes que utilizam conteúdo do Intlayer, mostrando agora as traduções para a nova localidade.

Veja a documentação de useLocale para mais detalhes.

Configurar TypeScript (se usar TypeScript)

O Intlayer gera definições de tipos numa pasta oculta (por defeito .intlayer) para melhorar a autocompletação e detetar erros de tradução:

// tsconfig.json{  // ... sua configuração TS existente  "include": [    "src", // seu código fonte    ".intlayer/types/**/*.ts", // <-- garantir que os tipos gerados automaticamente estejam incluídos    // ... qualquer outra coisa que você já inclua  ],}

Isto é o que habilita funcionalidades como:

• Autocompletar para as chaves do seu dicionário.
• Verificação de tipos que avisa se você acessar uma chave inexistente ou incompatível com o tipo.

Configuração do Git

Para evitar o commit de arquivos gerados automaticamente pelo Intlayer, adicione o seguinte ao seu .gitignore:

#  Ignorar os arquivos gerados pelo Intlayer.intlayer

Extensão VS Code

Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a Extensão oficial Intlayer para VS Code.

Instalar a partir do VS Code Marketplace

Esta extensão oferece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Visualizações inline do conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções facilmente.

Para mais detalhes sobre como usar a extensão, consulte a documentação da Extensão Intlayer para VS Code.

Ir Além

• Editor Visual: Use o Editor Visual Intlayer para gerenciar traduções visualmente.
• Integração com CMS: Você também pode externalizar e buscar o conteúdo do seu dicionário a partir de um CMS.
• Comandos CLI: Explore o Intlayer CLI para tarefas como extrair traduções ou verificar chaves faltantes.

Aproveite para construir seus aplicativos React Native com i18n totalmente potencializado através do Intlayer!