Iniziare con l'internazionalizzazione (i18n) con Intlayer e React Native

Consulta il Template Applicazione su GitHub.

Cos'è Intlayer?

Intlayer è una libreria di internazionalizzazione (i18n) innovativa e open-source che semplifica il supporto multilingue nelle applicazioni moderne. Funziona in molti ambienti JavaScript/TypeScript, incluso React Native (tramite il pacchetto react-intlayer).

Con Intlayer, puoi:

• Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
• Garantire il supporto TypeScript con tipi generati automaticamente.
• Localizzare dinamicamente i contenuti, incluse le stringhe dell'interfaccia utente (e in React per il web, può anche localizzare i metadati HTML, ecc.).
• Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della lingua.

Passo 1: Installa le dipendenze

Dal tuo progetto React Native, installa i seguenti pacchetti:

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

Pacchetti

• intlayer
  Il toolkit i18n principale per la configurazione, il contenuto del dizionario, la generazione dei tipi e i comandi CLI.

• react-intlayer
  Integrazione React che fornisce i provider di contesto e gli hook React che utilizzerai in React Native per ottenere e cambiare le localizzazioni.

• react-native-intlayer
  Integrazione React Native che fornisce il plugin Metro per integrare Intlayer con il bundler di React Native.

Passo 2: Crea una Configurazione Intlayer

Nella root del tuo progetto (o in qualsiasi posizione conveniente), crea un file di configurazione Intlayer. Potrebbe apparire così:

/** * Se i tipi Locales non sono disponibili, prova a impostare moduleResolution su "bundler" nel tuo tsconfig.json */import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // ... Aggiungi qualsiasi altra localizzazione di cui hai bisogno    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

All'interno di questa configurazione, puoi:

• Configurare la tua lista di localizzazioni supportate.
• Impostare una localizzazione predefinita.
• Successivamente, potrai aggiungere opzioni più avanzate (ad esempio, log, directory di contenuti personalizzate, ecc.).
• Consulta la documentazione di configurazione di Intlayer per maggiori informazioni.

Passo 3: Aggiungi il plugin Metro

Metro è un bundler per React Native. È il bundler predefinito per i progetti React Native creati con il comando react-native init. Per usare Intlayer con Metro, devi aggiungere il plugin al file 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: Aggiungi il provider Intlayer

Per mantenere sincronizzata la lingua dell'utente in tutta l'applicazione, è necessario avvolgere il componente root con il componente IntlayerProvider proveniente da react-intlayer.

Inoltre, è necessario aggiungere la funzione intlayerPolyfill al file index.js per garantire che Intlayer possa funzionare correttamente.

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: Dichiarare il Tuo Contenuto

Crea file di dichiarazione del contenuto in qualsiasi punto del tuo progetto (comunemente all'interno di src/), utilizzando uno qualsiasi dei formati di estensione supportati da Intlayer:

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

Esempio (TypeScript con nodi TSX per React Native):

import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";/** * Dizionario dei contenuti per il nostro dominio "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;

Per dettagli sulle dichiarazioni di contenuto, consulta la documentazione di Intlayer.

Passo 4: Usa Intlayer nei tuoi componenti

Usa l'hook useIntlayer nei componenti figli per ottenere contenuti localizzati.

Esempio

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;

Quando si utilizza content.someKey in proprietà basate su stringhe (ad esempio, il title di un pulsante o i children di un componente Text), chiamare content.someKey.value per ottenere la stringa effettiva.

(Opzionale) Passo 5: Cambiare la Lingua dell'App

Per cambiare la lingua dall'interno dei tuoi componenti, puoi usare il metodo setLocale dell'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",  },});

Questo provoca un nuovo rendering di tutti i componenti che utilizzano contenuti Intlayer, mostrando ora le traduzioni per la nuova localizzazione.

Vedi la documentazione di useLocale per maggiori dettagli.

Configurare TypeScript (se usi TypeScript)

Intlayer genera definizioni di tipo in una cartella nascosta (di default .intlayer) per migliorare l'autocompletamento e rilevare errori di traduzione:

// tsconfig.json{  // ... la tua configurazione TS esistente  "include": [    "src", // il tuo codice sorgente    ".intlayer/types/**/*.ts", // <-- assicurati che i tipi generati automaticamente siano inclusi    // ... qualsiasi altra cosa che già includi  ],}

Questo abilita funzionalità come:

• Completamento automatico per le chiavi del tuo dizionario.
• Controllo dei tipi che avvisa se accedi a una chiave inesistente o se c'è un disallineamento di tipo.

Configurazione Git

Per evitare di commettere file generati automaticamente da Intlayer, aggiungi quanto segue al tuo .gitignore:

# Ignora i file generati da Intlayer.intlayer

Estensione VS Code

Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare la Estensione ufficiale Intlayer per VS Code.

Installa dal Marketplace di VS Code

Questa estensione offre:

• Completamento automatico per le chiavi di traduzione.
• Rilevamento errori in tempo reale per traduzioni mancanti.
• Anteprime inline del contenuto tradotto.
• Azioni rapide per creare e aggiornare facilmente le traduzioni.

Per maggiori dettagli su come utilizzare l'estensione, consulta la documentazione dell'estensione Intlayer per VS Code.

Vai oltre

• Editor Visivo: Usa il Visual Editor di Intlayer per gestire le traduzioni in modo visivo.
• Integrazione CMS: Puoi anche esternalizzare e recuperare il contenuto del tuo dizionario da un CMS.
• Comandi CLI: Esplora il CLI di Intlayer per attività come estrarre traduzioni o controllare le chiavi mancanti.

Divertiti a sviluppare le tue app React Native con un i18n completamente potenziato tramite Intlayer!

Cronologia del documento

• 5.5.10 - 2025-06-29: Storia iniziale