@intlayer/docs 5.5.10 → 5.5.11

package/blog/it/intlayer_with_react-i18next.md

@@ -0,0 +1,346 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer e react-i18next
+description: Confronta Intlayer con react-i18next per un'app React
+keywords:
+  - react-i18next
+  - i18next
+  - Intlayer
+  - Internazionalizzazione
+  - Blogumentazione
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-i18next
+---
+
+# React Internazionalizzazione (i18n) con react-i18next e Intlayer
+
+## Panoramica
+
+- **Intlayer** ti aiuta a gestire le traduzioni tramite **file di dichiarazione del contenuto** a livello di componente.
+- **react-i18next** è un'integrazione popolare di React per **i18next** che fornisce hook come `useTranslation` per recuperare stringhe localizzate nei tuoi componenti.
+
+Quando combinati, Intlayer può **esportare** dizionari in **JSON compatibile con i18next** in modo che react-i18next possa **consumare** questi dizionari in fase di esecuzione.
+
+## Perché Usare Intlayer con react-i18next?
+
+I file di dichiarazione del contenuto di **Intlayer** offrono una migliore esperienza per gli sviluppatori perché sono:
+
+1. **Flessibili nella Posizione dei File**  
+   Metti ogni file di dichiarazione del contenuto accanto al componente che ne ha bisogno. Questa struttura ti consente di mantenere le traduzioni co-locate, impedendo traduzioni orfane quando i componenti si spostano o vengono eliminati.
+
+   ```bash codeFormat="typescript"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.ts # File di dichiarazione del contenuto
+               └── index.tsx
+   ```
+
+   ```bash codeFormat="esm"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.mjs # File di dichiarazione del contenuto
+               └── index.mjx
+   ```
+
+   ```bash codeFormat="cjs"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.cjs # File di dichiarazione del contenuto
+               └── index.cjx
+   ```
+
+   ```bash codeFormat="json"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.json # File di dichiarazione del contenuto
+               └── index.jsx
+   ```
+
+2. **Traduzioni Centralizzate**  
+   Un singolo file di dichiarazione del contenuto raccoglie tutte le traduzioni necessarie per un componente, rendendo più facile rilevare traduzioni mancanti.  
+   Con TypeScript, ricevi anche errori di compilazione se le traduzioni sono mancanti.
+
+## Installazione
+
+In un progetto Create React App, installa queste dipendenze:
+
+```bash
+# Con npm
+npm install intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+```bash
+# Con yarn
+yarn add intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+```bash
+# Con pnpm
+pnpm add intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+### Cosa Sono Questi Pacchetti?
+
+- **intlayer** – La CLI e la libreria principale per gestire le configurazioni i18n, le dichiarazioni di contenuto e costruire output di dizionari.
+- **react-intlayer** – Integrazione specifica di React per Intlayer, che fornisce notevolmente qualche script per automatizzare la costruzione dei dizionari.
+- **react-i18next** – Libreria di integrazione specifica di React per i18next, incluso l'hook `useTranslation`.
+- **i18next** – Il framework sottostante per la gestione delle traduzioni.
+- **i18next-resources-to-backend** – Un backend i18next che importa dinamicamente risorse JSON.
+
+## Configurare Intlayer per Esportare Dizionari i18next
+
+Crea (o aggiorna) il tuo `intlayer.config.ts` nella radice del tuo progetto:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Aggiungi quante più lingue desideri
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Dì a Intlayer di creare JSON compatibile con i18next
+    dictionaryOutput: ["i18next"],
+
+    // Scegli una directory di output per le risorse generate
+    // Questa cartella verrà creata se non esiste ancora.
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+export default config;
+```
+
+> **Nota**: Se non stai usando TypeScript, puoi creare questo file di configurazione come `.cjs`, `.mjs` o `.js` (vedi la [documentazione di Intlayer](https://intlayer.org/en/doc/concept/configuration) per dettagli).
+
+## Costruire le Risorse i18next
+
+Una volta che le tue dichiarazioni di contenuto sono pronte (sezione successiva), esegui il **comando di build di Intlayer**:
+
+```bash
+# Con npm
+npx run intlayer build
+```
+
+```bash
+# Con yarn
+yarn intlayer build
+```
+
+```bash
+# Con pnpm
+pnpm intlayer build
+```
+
+> Questo genererà le tue risorse i18next all'interno della directory `./i18next/resources` per impostazione predefinita.
+
+Un output tipico potrebbe apparire così:
+
+```bash
+.
+└── i18next
+    └── resources
+       ├── en
+       │   └── my-content.json
+       ├── fr
+       │   └── my-content.json
+       └── es
+           └── my-content.json
+```
+
+Dove ogni chiave di dichiarazione di **Intlayer** viene utilizzata come un **namespace di i18next** (ad esempio, `my-content.json`).
+
+## Importare Dizionari nella Tua Configurazione react-i18next
+
+Per caricare dinamicamente queste risorse in fase di esecuzione, usa [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend). Ad esempio, crea un file `i18n.ts` (o `.js`) nel tuo progetto:
+
+```typescript title="i18n.ts"
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import resourcesToBackend from "i18next-resources-to-backend";
+
+i18next
+  // plugin react-i18next
+  .use(initReactI18next)
+  // carica dinamicamente le risorse
+  .use(
+    resourcesToBackend((language: string, namespace: string) => {
+      // Regola il percorso di importazione alla tua directory delle risorse
+      return import(`../i18next/resources/${language}/${namespace}.json`);
+    })
+  )
+  // Inizializza i18next
+  .init({
+    // Lingua di fallback
+    fallbackLng: "en",
+
+    // Puoi aggiungere altre opzioni di configurazione di i18next qui, vedere:
+    // https://www.i18next.com/overview/configuration-options
+  });
+
+export default i18next;
+```
+
+```javascript title="i18n.js"
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import resourcesToBackend from "i18next-resources-to-backend";
+
+i18next
+  .use(initReactI18next)
+  .use(
+    resourcesToBackend(
+      (language, namespace) =>
+        import(`../i18next/resources/${language}/${namespace}.json`)
+    )
+  )
+  .init({
+    fallbackLng: "en",
+  });
+
+export default i18next;
+```
+
+Poi, nel tuo file **root** o **index** (ad esempio, `src/index.tsx`), importa questa configurazione `i18n` **prima** di rendere l'`App`:
+
+```typescript
+import React from "react";
+import ReactDOM from "react-dom/client";
+// Inizializza i18n prima di qualsiasi altra cosa
+import "./i18n";
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## Creare e Gestire le Tue Dichiarazioni di Contenuto
+
+Intlayer estrae le traduzioni dai “file di dichiarazione del contenuto” situati ovunque sotto `./src` (per impostazione predefinita).  
+Ecco un esempio minimale in TypeScript:
+
+```typescript title="src/components/MyComponent/MyComponent.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  // La "chiave" sarà il tuo namespace i18next (ad esempio, "my-component")
+  key: "my-component",
+  content: {
+    // Ogni chiamata "t" è un nodo di traduzione separato
+    heading: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "My i18n description text...",
+      fr: "Ma description en i18n...",
+      es: "Mi descripción en i18n...",
+    }),
+  },
+} satisfies Dictionary;
+
+export default content;
+```
+
+Se preferisci JSON, `.cjs`, o `.mjs`, fai riferimento alla [documentazione di Intlayer](https://intlayer.org/en/doc/concept/content).
+
+> Per impostazione predefinita, le dichiarazioni di contenuto valide corrispondono al modello di estensione del file:
+
+> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
+
+## Usare le Traduzioni nei Componenti React
+
+Dopo aver **costruito** le tue risorse Intlayer e configurato react-i18next, puoi usare direttamente l'hook `useTranslation` di **react-i18next**.  
+Ad esempio:
+
+```tsx title="src/components/MyComponent/MyComponent.tsx"
+import type { FC } from "react";
+import { useTranslation } from "react-i18next";
+
+/**
+ * Il "namespace" di i18next è la `chiave` di Intlayer da "MyComponent.content.ts"
+ * quindi passeremo "my-component" a useTranslation().
+ */
+const MyComponent: FC = () => {
+  const { t } = useTranslation("my-component");
+
+  return (
+    <div>
+      <h1>{t("heading")}</h1>
+      <p>{t("description")}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+> Nota che la funzione `t` fa riferimento a **chiavi** nel tuo JSON generato. Per un'inserzione di contenuto di Intlayer chiamata `heading`, utilizzerai `t("heading")`.
+
+## Opzionale: Integrare con gli Script di Create React App (CRACO)
+
+**react-intlayer** fornisce un approccio basato su CRACO per build personalizzate e configurazione del server di sviluppo. Se desideri che il passaggio di build di Intlayer sia integrato senza problemi, puoi:
+
+1. **Installare react-intlayer** (se non lo hai già fatto):
+   ```bash
+   npm install react-intlayer --save-dev
+   ```
+2. **Regolare i tuoi script di `package.json`** per utilizzare gli script di `react-intlayer`:
+
+   ```jsonc
+   "scripts": {
+     "start": "react-intlayer start",
+     "build": "react-intlayer build",
+     "transpile": "intlayer build"
+   }
+   ```
+
+   > Gli script di `react-intlayer` sono basati su [CRACO](https://craco.js.org/). Puoi anche implementare il tuo setup basato sul plugin craco di intlayer. [Vedi esempio qui](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+
+Ora, eseguendo `npm run build`, `yarn build`, o `pnpm build` attiva sia le build di Intlayer che quelle di CRA.
+
+## Configurazione di TypeScript
+
+**Intlayer** fornisce **definizioni di tipo autogenerate** per il tuo contenuto. Per assicurarti che TypeScript le riconosca, aggiungi **`types`** (o `types` se hai configurato diversamente) all'array **include** del tuo `tsconfig.json`:
+
+```json5 title="tsconfig.json"
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+> Questo consentirà a TypeScript di dedurre la struttura delle tue traduzioni per migliori autocompletamenti e detection degli errori.
+
+## Configurazione Git
+
+Si consiglia di **ignorare** file e cartelle autogenerati da Intlayer. Aggiungi questa riga al tuo `.gitignore`:
+
+```plaintext
+# Ignora i file generati da Intlayer
+.intlayer
+i18next
+```
+
+In genere non committi queste risorse o artefatti di build interni `.intlayer`, poiché possono essere rigenerati ad ogni build.

package/blog/it/intlayer_with_react-intl.md

@@ -0,0 +1,325 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer e react-intl
+description: Integra Intlayer con react-intl per un'app React
+keywords:
+  - react-intl
+  - Intlayer
+  - Internazionalizzazione
+  - Blogumentazione
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-intl
+---
+
+# React Internationalization (i18n) con **react-intl** e Intlayer
+
+Questa guida mostra come integrare **Intlayer** con **react-intl** per gestire le traduzioni in un'applicazione React. Dichiari i tuoi contenuti traducibili con Intlayer e poi consuma quei messaggi con **react-intl**, una popolare libreria dell'ecosistema [FormatJS](https://formatjs.io/docs/react-intl).
+
+## Panoramica
+
+- **Intlayer** ti consente di memorizzare le traduzioni nei file di dichiarazione dei contenuti a **livello di componente** (JSON, JS, TS, ecc.) all'interno del tuo progetto.
+- **react-intl** fornisce componenti React e hook (come `<FormattedMessage>` e `useIntl()`) per visualizzare stringhe localizzate.
+
+Configurando Intlayer per **esportare** le traduzioni in un formato **compatibile con react-intl**, puoi automaticamente **generare** e **aggiornare** i file di messaggi di cui `<IntlProvider>` (da react-intl) ha bisogno.
+
+---
+
+## Perché usare Intlayer con react-intl?
+
+1. **Dichiarazioni di contenuto per componente**  
+   I file di dichiarazione dei contenuti di Intlayer possono vivere accanto ai tuoi componenti React, evitando traduzioni “orfane” se i componenti vengono spostati o rimossi. Ad esempio:
+
+   ```bash
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.ts   # Dichiarazione contenuti Intlayer
+               └── index.tsx          # Componente React
+   ```
+
+2. **Traduzioni centralizzate**  
+   Ogni file di dichiarazione dei contenuti raccoglie tutte le traduzioni necessarie a un componente. Questo è particolarmente utile nei progetti TypeScript: le traduzioni mancanti possono essere catturate al **momento della compilazione**.
+
+3. **Build e rigenerazione automatiche**  
+   Ogni volta che aggiungi o aggiorni le traduzioni, Intlayer rigenera file JSON di messaggio. Puoi quindi passarli a `<IntlProvider>` di react-intl.
+
+---
+
+## Installazione
+
+In un tipico progetto React, installa i seguenti:
+
+```bash
+# con npm
+npm install intlayer react-intl
+
+# con yarn
+yarn add intlayer react-intl
+
+# con pnpm
+pnpm add intlayer react-intl
+```
+
+### Perché questi pacchetti?
+
+- **intlayer**: CLI core e libreria che scansiona le dichiarazioni di contenuto, le unisce e genera output di dizionario.
+- **react-intl**: La libreria principale di FormatJS che fornisce `<IntlProvider>`, `<FormattedMessage>`, `useIntl()` e altre primitives di internazionalizzazione.
+
+> Se non hai già installato React, avrai bisogno anche di esso (`react` e `react-dom`).
+
+## Configurare Intlayer per esportare i messaggi react-intl
+
+Nella radice del tuo progetto, crea **`intlayer.config.ts`** (o `.js`, `.mjs`, `.cjs`) in questo modo:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Aggiungi quanti più locali desideri
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Indica a Intlayer di generare file di messaggi per react-intl
+    dictionaryOutput: ["react-intl"],
+
+    // La directory in cui Intlayer scriverà i tuoi file JSON di messaggi
+    reactIntlMessagesDir: "./react-intl/messages",
+  },
+};
+
+export default config;
+```
+
+> **Nota**: Per altri tipi di file (`.mjs`, `.cjs`, `.js`), consulta la [documentazione di Intlayer](https://intlayer.org/it/doc/concept/configuration) per i dettagli sull'uso.
+
+---
+
+## Creazione delle dichiarazioni di contenuto di Intlayer
+
+Intlayer scansiona il tuo codice sorgente (per impostazione predefinita, sotto `./src`) per file che corrispondono a `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`.  
+Ecco un esempio in **TypeScript**:
+
+```typescript title="src/components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  // "chiave" diventa la chiave di messaggio di primo livello nel tuo file JSON react-intl
+  key: "my-component",
+
+  content: {
+    // Ogni chiamata a t() dichiara un campo traducibile
+    helloWorld: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "This is a description",
+      fr: "Ceci est une description",
+      es: "Esta es una descripción",
+    }),
+  },
+} satisfies Dictionary;
+
+export default content;
+```
+
+Se preferisci JSON o diversi tipi di JS (`.cjs`, `.mjs`), la struttura è essenzialmente la stessa, vedi [documentazione di Intlayer sulla dichiarazione dei contenuti](https://intlayer.org/it/doc/concept/content).
+
+---
+
+## Costruzione dei messaggi react-intl
+
+Per generare i file JSON di messaggi effettivi per **react-intl**, esegui:
+
+```bash
+# con npm
+npx intlayer dictionaries build
+
+# con yarn
+yarn intlayer build
+
+# con pnpm
+pnpm intlayer build
+```
+
+Questo scansiona tutti i file `*.content.*`, li compila e scrive i risultati nella directory specificata nel tuo **`intlayer.config.ts`** , in questo esempio, `./react-intl/messages`.  
+Un output tipico potrebbe apparire così:
+
+```bash
+.
+└── react-intl
+    └── messages
+        ├── en.json
+        ├── fr.json
+        └── es.json
+```
+
+Ogni file è un oggetto JSON i cui **chiavi di primo livello** corrispondono a ciascuna **`content.key`** dalle tue dichiarazioni. Le **sotto-chiavi** (come `helloWorld`) riflettono le traduzioni dichiarate all'interno di quell'elemento di contenuto.
+
+Ad esempio, il **en.json** potrebbe apparire così:
+
+```json fileName="react-intl/messages/en/my-component.json"
+{
+  "helloWorld": "Hello World",
+  "description": "This is a description"
+}
+```
+
+---
+
+## Inizializzare react-intl nella tua app React
+
+### 1. Carica i messaggi generati
+
+Dove configuri il componente radice della tua app (ad esempio, `src/main.tsx` o `src/index.tsx`), dovrai:
+
+1. **Importare** i file di messaggi generati (staticamente o dinamicamente).
+2. **Fornirli** a `<IntlProvider>` da `react-intl`.
+
+Un approccio semplice è importare staticamente:
+
+```typescript title="src/index.tsx"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { IntlProvider } from "react-intl";
+import App from "./App";
+
+// Importa i file JSON dall'output della build.
+// In alternativa, puoi importare dinamicamente in base alla lingua scelta dall'utente.
+import en from "../react-intl/messages/en.json";
+import fr from "../react-intl/messages/fr.json";
+import es from "../react-intl/messages/es.json";
+
+// Se hai un meccanismo per rilevare la lingua dell'utente, impostalo qui.
+// Per semplicità, scegliamo l'inglese.
+const locale = "en";
+
+// Raccogli i messaggi in un oggetto (o scegli in modo dinamico)
+const messagesRecord: Record<string, Record<string, any>> = {
+  en,
+  fr,
+  es,
+};
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+      <App />
+    </IntlProvider>
+  </React.StrictMode>
+);
+```
+
+> **Suggerimento**: Per progetti reali, potresti:
+>
+> - Caricare dinamicamente i messaggi JSON a runtime.
+> - Utilizzare rilevamenti di locale basati su ambiente, browser o account utente.
+
+### 2. Usa `<FormattedMessage>` o `useIntl()`
+
+Una volta che i tuoi messaggi sono stati caricati in `<IntlProvider>`, qualsiasi componente figlio può utilizzare react-intl per accedere a stringhe localizzate. Ci sono due approcci principali:
+
+- **Componente `<FormattedMessage>`**
+- **Hook `useIntl()`**
+
+---
+
+## Utilizzo delle traduzioni nei componenti React
+
+### Approccio A: `<FormattedMessage>`
+
+Per un utilizzo rapido in linea:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { FormattedMessage } from "react-intl";
+
+export default function MyComponent() {
+  return (
+    <div>
+      <h1>
+        {/* “my-component.helloWorld” fa riferimento alla chiave da en.json, fr.json, ecc. */}
+        <FormattedMessage id="my-component.helloWorld" />
+      </h1>
+
+      <p>
+        <FormattedMessage id="my-component.description" />
+      </p>
+    </div>
+  );
+}
+```
+
+> La prop **`id`** in `<FormattedMessage>` deve corrispondere alla **chiave di primo livello** (`my-component`) più eventuali sotto-chiavi (`helloWorld`).
+
+### Approccio B: `useIntl()`
+
+Per un utilizzo più dinamico:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { useIntl } from "react-intl";
+
+export default function MyComponent() {
+  const intl = useIntl();
+
+  return (
+    <div>
+      <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
+      <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+    </div>
+  );
+}
+```
+
+Entrambi gli approcci sono validi: scegli quello che meglio si adatta alla tua app.
+
+---
+
+## Aggiornamento o aggiunta di nuove traduzioni
+
+1. **Aggiungi o modifica** contenuti in qualsiasi file `*.content.*`.
+2. Riesegui `intlayer build` per rigenerare i file JSON sotto `./react-intl/messages`.
+3. React (e react-intl) rileveranno gli aggiornamenti la prossima volta che ricompili o ricarichi la tua applicazione.
+
+---
+
+## Integrazione TypeScript (Opzionale)
+
+Se stai usando TypeScript, Intlayer può **generare definizioni di tipo** per le tue traduzioni.
+
+- Assicurati che `tsconfig.json` includa la tua cartella `types` (o qualsiasi altra cartella di output generata da Intlayer) nell'array `"include"`.
+
+```json5
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+I tipi generati possono aiutare a rilevare traduzioni mancanti o chiavi non valide nei tuoi componenti React al momento della compilazione.
+
+---
+
+## Configurazione Git
+
+È comune **escludere** gli artefatti di build interni di Intlayer dal controllo versione. Nel tuo `.gitignore`, aggiungi:
+
+```plaintext
+# Ignora gli artefatti di build di intlayer
+.intlayer
+react-intl
+```
+
+A seconda del tuo flusso di lavoro, potresti anche voler ignorare o impegnare i dizionari finali in `./react-intl/messages`. Se la tua pipeline CI/CD li rigenera, puoi ignorarli in sicurezza; altrimenti, impegnali se hai bisogno di loro per le distribuzioni in produzione.