Começando a Internacionalizar (i18n) com Intlayer e React Native

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

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 sincronizado o idioma do usuário em toda a sua aplicação, você precisa envolver seu componente raiz com o componente IntlayerProvider do react-intlayer.

Além disso, você precisa adicionar a função intlayerPolyfill ao seu arquivo index.js para garantir que o Intlayer funcione corretamente.

import { Stack } from "expo-router";import { getLocales } from "expo-localization";import { IntlayerProviderContent } from "react-intlayer";import { intlayerPolyfill } from "react-native-intlayer";import { type FC } from "react";intlayerPolyfill();const getDeviceLocale = () => getLocales()[0]?.languageTag;const RootLayout: FC = () => {  return (    <IntlayerProviderContent defaultLocale={getDeviceLocale()}>      <Stack>        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />      </Stack>    </IntlayerProviderContent>  );};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.

(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!

Histórico do Documento

• 5.5.10 - 2025-06-29: Histórico inicial