Traduci la tua app Expo e React Native | Internazionalizzazione (i18n)

Indice

Perché Intlayer rispetto alle alternative?

Rispetto alle soluzioni principali come react-native-localize o i18next, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

1. 1

   Installare le dipendenze

   Vedere il Modello di applicazione su GitHub.

   Dal tuo progetto React Native, installa i seguenti pacchetti:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   npx intlayer init --interactive
   

   Il flag --interactive è opzionale. Usa intlayer-cli init se sei un agente IA.

   Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   npm install intlayer 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-native-intlayer
     Integrazione React Native che fornisce i provider di contesto e gli hook React che utilizzerai per ottenere e cambiare le localizzazioni, i polyfill React Native e il plugin Metro per integrare Intlayer con il bundler di React Native. Riesporta tutto da react-intlayer, quindi hai bisogno solo di questo singolo pacchetto in un'app React Native.

2. 2

   Crea una Configurazione Intlayer

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

   intlayer.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

   metro.config.js

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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 è una funzione promise. Usa configMetroIntlayerSync se vuoi usarla in modo sincrono, o evita l'IFFE (Immediately Invoked Function Expression). Nota: configMetroIntlayerSync non consente di costruire dizionari intlayer all'avvio del server

4. 4

   Aggiungi il provider Intlayer

   Per mantenere sincronizzata la lingua dell'utente in tutta l'applicazione, devi avvolgere il componente radice con il componente IntlayerProvider da react-native-intlayer.

   Importa sempre da react-native-intlayer. Il suo IntlayerProvider include polyfill per le API web usate da Intlayer, e il pacchetto riesporta tutti gli hook e le utilità da react-intlayer.

   Inoltre, devi aggiungere la funzione intlayerPolyfill al tuo file index.js per assicurarti che Intlayer possa funzionare correttamente.

   app/_layout.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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

   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.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
   • ecc.

   Expo Router (web): tieni i file .content.* fuori dalla directory app/. Expo Router tratta ogni file JavaScript/TypeScript all'interno di app/ come una rotta. Sul web, la sua scoperta delle rotte scansiona direttamente il file system e non rispetta il resolver.blockList di Metro, quindi un *.content.ts co-localizzato viene registrato come una rotta. Un file come app/(tabs)/_layout.content.ts viene persino analizzato come un layout (la parte .content viene letta come suffisso della piattaforma), il che entra in conflitto con il vero _layout.tsx e genera l'errore:

   plaintext

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

   Posiziona le tue dichiarazioni in una directory al di fuori di app/ (ad esempio content/ o src/content/). Intlayer scopre i file .content.* ovunque nel progetto e i dizionari sono referenziati tramite la loro key, quindi non sono necessarie modifiche agli import. Su nativo questo non è richiesto (la blockList di Metro li nasconde già), ma utilizzare una directory diversa da app/ mantiene entrambe le piattaforme funzionanti.

   Esempio (TypeScript con nodi TSX per React Native):

   src/app.content.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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.

6. 6

   Usa Intlayer nei tuoi componenti

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

   Esempio

   app/(tabs)/index.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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;
   

   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.

   Se la tua app esiste già, puoi utilizzare l' Intlayer Compiler in combinazione con il comando extract per convertire migliaia di componenti in un secondo.

7. 7

   Cambiare la Lingua dell'App

   Opzionale

   Per cambiare la lingua dall'interno dei tuoi componenti, puoi usare il metodo setLocale dell'hook useLocale:

   src/components/LocaleSwitcher.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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",
     },
   });
   

   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!

Debug

React Native può essere meno stabile di React Web, quindi presta particolare attenzione all'allineamento delle versioni.

Intlayer è principalmente orientato all'API Web Intl; su React Native è necessario includere i polyfill appropriati.

Checklist:

• Utilizza le versioni più recenti di intlayer e react-native-intlayer.
• Abilita il polyfill di Intlayer.
• Se utilizzi getLocaleName o altre utility basate su Intl-API, importa questi polyfill all'inizio (ad esempio in index.js o 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";

• Verifica la configurazione di Metro (resolver aliases, asset plugins, percorsi tsconfig) se i moduli non vengono risolti.

Domande frequenti