intlayer_with_create_react_app.md

createdAt

2024-08-11

updatedAt

2026-05-31

title

Create React App i18n - Guida completa per tradurre la tua applicazione

description

Niente più i18next. La guida 2026 per creare un'applicazione Create React App multilingue (i18n). Traduci con agenti AI e ottimizza la dimensione del bundle, SEO e prestazioni.

keywords

Internazionalizzazione

Documentazione

Intlayer

Create React App

CRA

JavaScript

React

slugs

doc

environment

create-react-app

applicationTemplate

https://github.com/aymericzip/intlayer-react-cra-template

history

version	date	changes
8.9.0	2026-05-04	Aggiornare l'uso dell'API useIntlayer di Solid all'accesso diretto alle proprietà

version	date	changes
7.5.9	2025-12-30	Aggiungi comando init

version	date	changes
5.5.10	2025-06-29	Cronologia iniziale

Traduci la tua Create React App con Intlayer | Internazionalizzazione (i18n)

Consulta Application Template su GitHub.

Cos'è Intlayer?

Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle applicazioni web moderne.

Con Intlayer, puoi:

Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
Localizzare dinamicamente metadati, percorsi e contenuti.
Garantire il supporto TypeScript con tipi autogenerati, migliorando l'autocompletamento e il rilevamento degli errori.
Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della lingua.

Guida passo-passo per configurare Intlayer in un'applicazione React

Installa i pacchetti necessari utilizzando npm:

npm install intlayer react-intlayer react-scripts-intlayer
npx intlayer init

pnpm add intlayer react-intlayer react-scripts-intlayer
pnpm intlayer init

yarn add intlayer react-intlayer react-scripts-intlayer
yarn intlayer init

bun add intlayer react-intlayer react-scripts-intlayer
bun x intlayer init

intlayer

Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione delle configurazioni, traduzioni, dichiarazione dei contenuti, transpilation e comandi CLI.
react-intlayer

Il pacchetto che integra Intlayer con l'applicazione React. Fornisce provider di contesto e hook per l'internazionalizzazione in React.
react-scripts-intlayer Include i comandi e i plugin react-scripts-intlayer per integrare Intlayer con l'applicazione basata su Create React App. Questi plugin sono basati su craco e includono configurazioni aggiuntive per il bundler Webpack.

Crea un file di configurazione per configurare le lingue della tua applicazione:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Altre lingue
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Tramite questo file di configurazione, puoi configurare URL localizzati, reindirizzamenti middleware, nomi dei cookie, la posizione e l'estensione delle dichiarazioni dei contenuti, disabilitare i log di Intlayer nella console e altro. Per un elenco completo dei parametri disponibili, consulta la documentazione di configurazione.

Modifica i tuoi script per utilizzare react-intlayer

  "scripts": {
    "build": "react-scripts-intlayer build",
    "start": "react-scripts-intlayer start",
    "transpile": "intlayer build"
  },

Gli script react-scripts-intlayer sono basati su CRACO. Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. Vedi esempio qui.

Crea e gestisci le dichiarazioni dei tuoi contenuti per memorizzare le traduzioni:

Gli script react-scripts-intlayer sono basati su CRACO. Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. Vedi esempio qui.

Crea e gestisci le dichiarazioni dei tuoi contenuti per memorizzare le traduzioni:

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

const appContent = {
  key: "app",
  content: {
    getStarted: t<ReactNode>({
      en: (
        <>
          Edit <code>src/App.tsx</code> and save to reload
        </>
      ),
      fr: (
        <>
          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
        </>
      ),
      es: (
        <>
          Edita <code>src/App.tsx</code> y guarda para recargar
        </>
      ),
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} satisfies Dictionary;

export default appContent;

const { t } = require("intlayer");

/** @type {import('intlayer').Dictionary} */
const appContent = {
  key: "app",
  content: {
    getStarted: t({
      en: "Get started by editing",
      fr: "Commencez par éditer",
      es: "Comience por editar",
      it: "Inizia modificando",
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
        it: "Impara React",
      }),
    },
  },
};

module.exports = appContent;

Le dichiarazioni dei tuoi contenuti possono essere definite ovunque nella tua applicazione purché siano incluse nella directory contentDir (di default, ./src). E corrispondano all'estensione del file di dichiarazione dei contenuti (di default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Per maggiori dettagli, consulta la documentazione sulla dichiarazione dei contenuti.

Se il tuo file di contenuti include codice TSX, considera di importare import React from "react"; nel tuo file di contenuti.

Accedi ai tuoi dizionari di contenuti in tutta l'applicazione:

import logo from "./logo.svg";
import "./App.css";
import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const content = useIntlayer("app");

  return (
    <div className="App">
      <img src={logo} className="App-logo" alt="logo" />

      {content.getStarted}
      <a
        className="App-link"
        href={content.reactLink.href.value}
        target="_blank"
        rel="noopener noreferrer"
      >
        {content.reactLink.content}
      </a>
    </div>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

Nota: se vuoi usare i tuoi contenuti in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare il valore della funzione, ad esempio:

<img src="{content.image.src.value}" alt="{content.image.value}" />
<img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
<img src="{String(content.image.src)}" alt="{String(content.image)}" />

Per saperne di più sull'hook useIntlayer, consulta la documentazione.

Per cambiare la lingua dei tuoi contenuti, puoi utilizzare la funzione setLocale fornita dall'hook useLocale. Questa funzione ti consente di impostare la lingua dell'applicazione e aggiornare i contenuti di conseguenza.

import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.English)}>
      Change Language to English
    </button>
  );
};

Per saperne di più sull'hook useLocale, consulta la documentazione.

Lo scopo di questo passaggio è creare percorsi univoci per ogni lingua. Questo è utile per la SEO e per URL SEO-friendly. Esempio:

- https://example.com/about
- https://example.com/es/about
- https://example.com/fr/about

Di default, i percorsi non sono prefissati per la lingua predefinita. Se desideri prefissare la lingua predefinita, puoi impostare l'opzione middleware.prefixDefault su true nella tua configurazione. Consulta la documentazione di configurazione per maggiori informazioni.

Per aggiungere il routing localizzato alla tua applicazione, puoi creare un componente LocaleRouter che avvolge i percorsi della tua applicazione e gestisce il routing basato sulla lingua. Ecco un esempio che utilizza React Router:

// Importing necessary dependencies and functions
import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Funzioni di utilità e tipi da 'intlayer'
// Funzioni di utilità e tipi da 'intlayer'
import type { FC, PropsWithChildren } from "react"; // Tipi React per componenti funzionali e props
import { IntlayerProvider } from "react-intlayer"; // Provider per il contesto di internazionalizzazione
import {
  BrowserRouter,
  Routes,
  Route,
  Navigate,
  useLocation,
} from "react-router-dom"; // Componenti router per la gestione della navigazione

// Destrutturazione della configurazione da Intlayer
const { internationalization, middleware } = configuration;
const { locales, defaultLocale } = internationalization;

/**
 * Un componente che gestisce la localizzazione e avvolge i figli con il contesto locale appropriato.
 * Gestisce il rilevamento e la validazione della localizzazione basata sull'URL.
 */
const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
  children,
  locale,
}) => {
  const { pathname, search } = useLocation(); // Ottieni il percorso URL corrente

  // Determina la localizzazione corrente, usando quella di default se non fornita
  const currentLocale = locale ?? defaultLocale;

  // Rimuove il prefisso della localizzazione dal percorso per costruire un percorso base
  const pathWithoutLocale = getPathWithoutLocale(
    pathname // Percorso URL corrente
  );

  /**
   * Se middleware.prefixDefault è true, la localizzazione di default deve essere sempre prefissata.
   */
  if (middleware.prefixDefault) {
    // Valida la localizzazione
    if (!locale || !locales.includes(locale)) {
      // Reindirizza alla localizzazione di default con il percorso aggiornato
      return (
        <Navigate
          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
          replace // Sostituisce la voce corrente nella cronologia con quella nuova
        />
      );
    }

    // Avvolge i figli con IntlayerProvider e imposta la locale corrente
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  } else {
    /**
     * Quando middleware.prefixDefault è false, la locale predefinita non è prefissata.
     * Assicurarsi che la locale corrente sia valida e non la locale predefinita.
     */
    if (
      currentLocale.toString() !== defaultLocale.toString() &&
      !locales
        .filter(
          (locale) => locale.toString() !== defaultLocale.toString() // Esclude la locale predefinita
        )
        .includes(currentLocale) // Verifica se la locale corrente è nella lista delle locale valide
    ) {
      // Reindirizza al percorso senza prefisso della locale
      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
    }

    // Avvolge i figli con IntlayerProvider e imposta la locale corrente
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  }
};

/**
 * Un componente router che configura rotte specifiche per la locale.
 * Usa React Router per gestire la navigazione e rendere componenti localizzati.
 */
export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
  <BrowserRouter>
    <Routes>
      {locales
        .filter(
          (locale) => middleware.prefixDefault || locale !== defaultLocale
        )
        .map((locale) => (
          <Route
            // Pattern di percorso per catturare la locale (es. /en/, /fr/) e corrispondere a tutti i percorsi successivi
            path={`/${locale}/*`}
            key={locale}
            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Avvolge i figli con la gestione della locale
          />
        ))}

      {
        // Se il prefisso per la locale predefinita è disabilitato, renderizza i figli direttamente al percorso root
        !middleware.prefixDefault && (
          <Route
            path="*"
            element={
              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
            } // Avvolge i figli con la gestione della locale
          />
        )
      }
    </Routes>
  </BrowserRouter>
);

Then, you can use the LocaleRouter component in your application:

import { LocaleRouter } from "./components/LocaleRouter";
import type { FC } from "react";

// ... Il tuo componente AppContent

const App: FC = () => (
  <LocaleRouter>
    <AppContent />
  </LocaleRouter>
);

Per cambiare l'URL quando la lingua cambia, puoi usare la proprietà onLocaleChange fornita dall'hook useLocale. Parallelamente, puoi usare gli hook useLocation e useNavigate di react-router-dom per aggiornare il percorso URL.

Per modificare l'URL quando cambia la lingua, puoi usare la proprietà onLocaleChange fornita dall'hook useLocale. Parallelamente, puoi utilizzare gli hook useLocation e useNavigate di react-router-dom per aggiornare il percorso URL.

import { useLocation, useNavigate } from "react-router-dom";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "react-intlayer";
import { type FC } from "react";

const LocaleSwitcher: FC = () => {
  const { pathname, search } = useLocation(); // Ottieni il percorso URL corrente. Esempio: /fr/about?foo=bar
  const navigate = useNavigate();

  const { locale, availableLocales, setLocale } = useLocale({
    onLocaleChange: (locale) => {
      // Costruisci l'URL con la lingua aggiornata
      // Esempio: /es/about?foo=bar
      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);

      // Aggiorna il percorso URL
      navigate(pathWithLocale);
    },
  });

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <a
            href={getLocalizedUrl(location.pathname, localeItem)}
            hrefLang={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={(e) => {
              e.preventDefault();
              setLocale(localeItem);
            }}
            key={localeItem}
          >
            <span>
              {/* Località - es. FR */}
              {localeItem}
            </span>
            <span>
              {/* Lingua nella sua stessa località - es. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Lingua nella località corrente - es. Francés con la località corrente impostata su Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Lingua in inglese - es. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </a>
        ))}
      </div>
    </div>
  );
};

Riferimenti alla documentazione:

useLocale hook

getLocaleName hook

getLocalizedUrl hook

getHTMLTextDir hook

hrefLang attribute

lang attribute

dir attribute

aria-current attribute

Quando la tua applicazione supporta più lingue, è fondamentale aggiornare gli attributi lang e dir del tag <html> per farli corrispondere alla locale corrente. Questo garantisce:

Accessibilità: I lettori di schermo e le tecnologie assistive si basano sull'attributo lang corretto per pronunciare e interpretare accuratamente i contenuti.
Rendering del testo: L'attributo dir (direzione) garantisce che il testo venga visualizzato nell'ordine corretto (ad esempio, da sinistra a destra per l'inglese, da destra a sinistra per l'arabo o l'ebraico), essenziale per la leggibilità.
SEO: I motori di ricerca utilizzano l'attributo lang per determinare la lingua della pagina, aiutando a mostrare il contenuto localizzato corretto nei risultati di ricerca.

Aggiornando dinamicamente questi attributi quando la lingua cambia, garantisci un'esperienza coerente e accessibile per gli utenti in tutte le lingue supportate.

Implementazione del Hook

Crea un hook personalizzato per gestire gli attributi HTML. L’hook ascolta i cambiamenti di locale e aggiorna gli attributi di conseguenza:

import { useEffect } from "react";
import { useLocale } from "react-intlayer";
import { getHTMLTextDir } from "intlayer";

/**
 * Aggiorna gli attributi `lang` e `dir` dell’elemento HTML <html> in base al locale corrente.
 * - `lang`: informa browser e motori di ricerca sulla lingua della pagina.
 * - `dir`: garantisce l’ordine di lettura corretto (es. 'ltr' per inglese, 'rtl' per arabo).
 *
 * Questo aggiornamento dinamico è essenziale per una corretta resa del testo, accessibilità e SEO.
 */
export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    // Aggiorna l'attributo della lingua alla locale corrente.
    document.documentElement.lang = locale;

    // Imposta la direzione del testo in base alla locale corrente.
    document.documentElement.dir = getHTMLTextDir(locale);
  }, [locale]);
};

Utilizzo del Hook nella tua Applicazione

Integra il hook nel tuo componente principale in modo che gli attributi HTML si aggiornino ogni volta che la locale cambia:

import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";
import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
import "./App.css";

const AppContent: FC = () => {
  // Applica l'hook per aggiornare gli attributi lang e dir del tag <html> in base alla locale.
  useI18nHTMLAttributes();

  // ... Resto del tuo componente
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

Applicando queste modifiche, la tua applicazione:

Garantirà che l'attributo language (lang) rifletta correttamente la locale corrente, cosa importante per la SEO e il comportamento del browser.
Adatterà la direzione del testo (dir) in base alla locale, migliorando la leggibilità e l'usabilità per le lingue con ordini di lettura diversi.
Fornirà un'esperienza più accessibile, poiché le tecnologie assistive dipendono da questi attributi per funzionare al meglio.

Configurare TypeScript

Intlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.

Assicurati che la tua configurazione TypeScript includa i tipi generati automaticamente.

{
  // ... Le tue configurazioni TypeScript esistenti
  "include": [
    // ... Le tue configurazioni TypeScript esistenti
    ".intlayer/**/*.ts", // Includi i tipi generati automaticamente
  ],
}

Configurazione Git

Si consiglia di ignorare i file generati da Intlayer. Questo ti permette di evitare di committarli nel tuo repository Git.

Per farlo, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

# Ignora i file generati da Intlayer
.intlayer

Estensione VS Code

Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare la Intlayer VS Code Extension ufficiale. 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

Per andare oltre, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS. 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.

Approfondimenti

Per approfondire, puoi implementare l’editor visuale o esternalizzare i tuoi contenuti usando il CMS.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Traduci la tua Create React App con Intlayer | Internazionalizzazione (i18n)

Cos'è Intlayer?

Guida passo-passo per configurare Intlayer in un'applicazione React

Implementazione del Hook

Utilizzo del Hook nella tua Applicazione

Configurare TypeScript

Configurazione Git

Estensione VS Code

Vai oltre

Approfondimenti

Uh oh!

FilesExpand file tree

intlayer_with_create_react_app.md

Latest commit

History

intlayer_with_create_react_app.md

File metadata and controls

Traduci la tua Create React App con Intlayer | Internazionalizzazione (i18n)

Cos'è Intlayer?

Guida passo-passo per configurare Intlayer in un'applicazione React

Implementazione del Hook

Utilizzo del Hook nella tua Applicazione

Configurare TypeScript

Configurazione Git

Estensione VS Code

Vai oltre

Approfondimenti