@intlayer/docs 7.0.4-canary.0 → 7.0.5

package/blog/it/intlayer_with_react-i18next.md

@@ -1,346 +1,124 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer e react-i18next
-description: Confronta Intlayer con react-i18next per un'app React
+updatedAt: 2025-10-29
+title: Come automatizzare le traduzioni JSON di react-i18next usando Intlayer
+description: Automatizza le tue traduzioni JSON con Intlayer e react-i18next per una migliore internazionalizzazione nelle applicazioni React.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - Internazionalizzazione
-  - Blogumentazione
-  - Next.js
-  - JavaScript
+  - i18n
+  - Blog
   - React
+  - JavaScript
+  - TypeScript
+  - Gestione Contenuti
 slugs:
   - blog
   - intlayer-with-react-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Modifica al plugin syncJSON
 ---
 
-# 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
-```
+# Come automatizzare le traduzioni JSON di react-i18next usando Intlayer
 
-### Cosa Sono Questi Pacchetti?
+## Cos'è Intlayer?
 
-- **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.
+**Intlayer** è una libreria di internazionalizzazione innovativa e open-source progettata per superare le limitazioni delle soluzioni i18n tradizionali. Offre un approccio moderno alla gestione dei contenuti nelle applicazioni React.
 
-## 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"],
+Consulta un confronto concreto con react-i18next nel nostro post del blog [react-i18next vs. react-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/react-i18next_vs_react-intl_vs_intlayer.md).
 
-    // Scegli una directory di output per le risorse generate
-    // Questa cartella verrà creata se non esiste ancora.
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+## Perché combinare Intlayer con react-i18next?
 
-export default config;
-```
+Sebbene Intlayer offra una soluzione i18n autonoma eccellente (vedi la nostra [guida all'integrazione con React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_with_vite+react.md)), potresti volerlo combinare con react-i18next per diversi motivi:
 
-> **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).
+1. **Codice esistente**: Hai un’implementazione consolidata di react-i18next e desideri migrare gradualmente alla migliore esperienza sviluppatore offerta da Intlayer.
+2. **Requisiti legacy**: Il tuo progetto richiede la compatibilità con plugin o flussi di lavoro esistenti di react-i18next.
+3. **Familiarità del team**: Il tuo team è abituato a react-i18next ma desidera una migliore gestione dei contenuti.
 
-## Costruire le Risorse i18next
+**Per questo, Intlayer può essere implementato come un adattatore per react-i18next per aiutarti ad automatizzare le tue traduzioni JSON in CLI o pipeline CI/CD, testare le traduzioni e altro ancora.**
 
-Una volta che le tue dichiarazioni di contenuto sono pronte (sezione successiva), esegui il **comando di build di Intlayer**:
+Questa guida ti mostra come sfruttare il sistema superiore di dichiarazione dei contenuti di Intlayer mantenendo la compatibilità con react-i18next.
 
-```bash
-# Con npm
-npx run intlayer build
-```
+## Indice
 
-```bash
-# Con yarn
-yarn intlayer build
-```
+<TOC/>
 
-```bash
-# Con pnpm
-pnpm intlayer build
-```
+## Guida passo-passo per configurare Intlayer con react-i18next
 
-> Questo genererà le tue risorse i18next all'interno della directory `./i18next/resources` per impostazione predefinita.
+### Passo 1: Installare le dipendenze
 
-Un output tipico potrebbe apparire così:
+Installa i pacchetti necessari:
 
-```bash
-.
-└── i18next
-    └── resources
-       ├── en
-       │   └── my-content.json
-       ├── fr
-       │   └── my-content.json
-       └── es
-           └── my-content.json
+```bash packageManager="npm"
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-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;
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```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;
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-Poi, nel tuo file **root** o **index** (ad esempio, `src/index.tsx`), importa questa configurazione `i18n` **prima** di rendere l'`App`:
+**Descrizione dei pacchetti:**
 
-```typescript
-import React from "react";
-import ReactDOM from "react-dom/client";
-// Inizializza i18n prima di qualsiasi altra cosa
-import "./i18n";
-import App from "./App";
+- **intlayer**: Libreria principale per la gestione dell'internazionalizzazione, dichiarazione dei contenuti e build
+- **@intlayer/sync-json-plugin**: Plugin per esportare le dichiarazioni di contenuto di Intlayer in formato JSON compatibile con react-i18next
 
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
+### Passo 2: Implementare il plugin Intlayer per incapsulare il JSON
 
-## Creare e Gestire le Tue Dichiarazioni di Contenuto
+Crea un file di configurazione Intlayer per definire le tue localizzazioni supportate:
 
-Intlayer estrae le traduzioni dai “file di dichiarazione del contenuto” situati ovunque sotto `./src` (per impostazione predefinita).  
-Ecco un esempio minimale in TypeScript:
+**Se vuoi anche esportare i dizionari JSON per react-i18next**, aggiungi il plugin `syncJSON`:
 
-```typescript title="src/components/MyComponent/MyComponent.content.ts"
-import { t, type Dictionary } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-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",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-    description: t({
-      en: "My i18n description text...",
-      fr: "Ma description en i18n...",
-      es: "Mi descripción en i18n...",
-    }),
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
   },
-} 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>
-  );
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
-export default MyComponent;
+export default config;
 ```
 
-> 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")`.
+Il plugin `syncJSON` avvolgerà automaticamente il JSON. Leggerà e scriverà i file JSON senza modificare l'architettura del contenuto.
 
-## Opzionale: Integrare con gli Script di Create React App (CRACO)
+Se vuoi far coesistere quel JSON con i file di dichiarazione dei contenuti di intlayer (file `.content`), Intlayer procederà in questo modo:
 
-**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. caricare sia i file JSON che i file di dichiarazione dei contenuti e trasformarli in un dizionario intlayer.
+    2. se ci sono conflitti tra i file JSON e i file di dichiarazione dei contenuti, Intlayer procederà alla fusione di tutti questi dizionari. A seconda della priorità dei plugin e di quella del file di dichiarazione dei contenuti (tutti configurabili).
 
-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`:
+Se vengono apportate modifiche utilizzando la CLI per tradurre il JSON, o utilizzando il CMS, Intlayer aggiornerà il file JSON con le nuove traduzioni.
 
-   ```jsonc
-   "scripts": {
-     "start": "react-intlayer start",
-     "build": "react-intlayer build",
-     "transpile": "intlayer build"
-   }
-   ```
+Per maggiori dettagli sul plugin `syncJSON`, si prega di fare riferimento alla [documentazione del plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md).
 
-   > 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
+## Configurazione Git
 
-**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`:
+È consigliato ignorare i file Intlayer generati automaticamente:
 
-```json5 title="tsconfig.json"
-{
-  "compilerOptions": {
-    // ...
-  },
-  "include": ["src", "types"],
-}
+```plaintext fileName=".gitignore"
+# Ignorare i file generati da Intlayer
+.intlayer
 ```
 
-> Questo consentirà a TypeScript di dedurre la struttura delle tue traduzioni per migliori autocompletamenti e detection degli errori.
-
-## Configurazione Git
+Questi file possono essere rigenerati durante il processo di build e non è necessario includerli nel controllo di versione.
 
-Si consiglia di **ignorare** file e cartelle autogenerati da Intlayer. Aggiungi questa riga al tuo `.gitignore`:
+### Estensione VS Code
 
-```plaintext
-# Ignora i file generati da Intlayer
-.intlayer
-i18next
-```
+Per migliorare l'esperienza dello sviluppatore, installa l'**Estensione ufficiale Intlayer per VS Code**:
 
-In genere non committi queste risorse o artefatti di build interni `.intlayer`, poiché possono essere rigenerati ad ogni build.
+[Installa dal Marketplace di VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)