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

Índice

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como react-native-localize ou i18next, Intlayer é uma solução que vem com otimizações integradas como:

1. 1

   Instalar Dependências

   Consulte o Modelo de Aplicativo no GitHub.

   No seu projeto React Native, instale os seguintes pacotes:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npx intlayer@canary init --interactive    # v9# npx intlayer init                       # v8

   A flag --interactive é opcional. Use intlayer-cli init se você for um agente de IA.

   Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install intlayer 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-native-intlayer
     Integração React Native que fornece os provedores de contexto e hooks React que você usará para obter e trocar localidades, os polyfills do React Native e o plugin Metro para integrar o Intlayer com o bundler do React Native. Reexporta tudo de react-intlayer, portanto você só precisa deste único pacote em um aplicativo React Native.

   ---

2. 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:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   /**
    * 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.
3. 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:

   metro.config.js

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

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

   Nota: configMetroIntlayer é uma função que retorna uma promise. Use configMetroIntlayerSync se quiser usá-la de forma síncrona ou evitar IIFE (Immediately Invoked Function Expression). Nota: configMetroIntlayerSync não permite construir dicionários intlayer no início do servidor

4. 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-native-intlayer.

   Sempre importe de react-native-intlayer. Seu IntlayerProvider inclui polyfills para a API web usada pelo Intlayer, e o pacote reexporta todos os hooks e utilitários de react-intlayer.

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

   app/_layout.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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;

5. 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.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • etc.

   Expo Router (web): mantenha os arquivos .content.* fora do diretório app/. O Expo Router trata cada arquivo JavaScript/TypeScript dentro de app/ como uma rota. Na web, a descoberta de rotas varre o sistema de arquivos diretamente e não respeita o resolver.blockList do Metro, então um *.content.ts co-localizado é registrado como uma rota. Um arquivo como app/(tabs)/_layout.content.ts é até analisado como um layout (a parte .content é lida como um sufixo de plataforma), o que entra em conflito com o verdadeiro _layout.tsx e lança o erro:

   plaintext

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.

   Coloque suas declarações em um diretório fora de app/ (por exemplo, content/ ou src/content/). O Intlayer descobre arquivos .content.* em qualquer lugar do projeto e os dicionários são referenciados por sua key, portanto, nenhuma mudança de importação é necessária. No nativo isso não é necessário (a blockList do Metro já os esconde), mas usar um diretório diferente de app/ mantém ambas as plataformas funcionando.

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

   src/app.content.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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.

   ---

6. 6

   Use o Intlayer em Seus Componentes

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

   Exemplo

   app/(tabs)/index.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Image, StyleSheet, Platform } from "react-native";
   import { useIntlayer } from "react-native-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.

   ---

7. 7

   Alterar o Locale do App

   Opcional

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

   src/components/LocaleSwitcher.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { type FC } from "react";
   import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-native-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!

Debug

React Native pode ser menos estável do que React Web, então preste atenção extra ao alinhamento de versões.

Intlayer tem como alvo principal a Web Intl API; no React Native você deve incluir os polyfills apropriados.

Checklist:

• Use as últimas versões de intlayer e react-native-intlayer.
• Ative o polyfill do Intlayer.
• Se você usar getLocaleName ou outros utilitários baseados em Intl-API, importe esses polyfills cedo (por exemplo em index.js ou App.tsx):

import "intl";import "@formatjs/intl-getcanonicallocales/polyfill";import "@formatjs/intl-locale/polyfill";import "@formatjs/intl-pluralrules/polyfill";import "@formatjs/intl-displaynames/polyfill";import "@formatjs/intl-listformat/polyfill";import "@formatjs/intl-numberformat/polyfill";import "@formatjs/intl-relativetimeformat/polyfill";import "@formatjs/intl-datetimeformat/polyfill";

• Verifique sua configuração do Metro (resolver aliases, asset plugins, caminhos de tsconfig) se os módulos falharem em resolver.