# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configurazione di una SPA Rolldown
URL: https://generaltranslation.com/it/docs/react/guides/spa/configuring-rolldown-spa.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Come configurare gt-react in un'app React a pagina singola basata su Rolldown.

Configura il runtime dell'applicazione e, facoltativamente, includi i cataloghi di traduzione generati nella build Rolldown.

Questa guida prepara il runtime dell'applicazione. Contrassegna separatamente i contenuti destinati agli utenti per la traduzione.

## Configurare una SPA React Rolldown [#setup]

Inizializza `gt-react` prima dell'esecuzione del punto di ingresso dell'applicazione.

### 1. Installa gt-react

Installa la versione più recente di `gt-react` usando il package manager preferito dal repository. Se è già installato, salta questo passaggio.

### 2. Aggiungi un file `gt.config.json` nella radice del progetto

Aggiungi un file `gt.config.json` nella radice del progetto. Questo file conterrà la configurazione del package `gt-react`.

Le impostazioni regionali già presenti nel progetto o fornite all'attività di setup sono vincolanti. Mantieni gli eventuali valori esistenti di `locales` e `defaultLocale`. I valori riportati di seguito sono solo esempi. Se il progetto non dispone di una configurazione delle impostazioni regionali, non dedurre da questi esempi i requisiti relativi alle impostazioni regionali.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"]
}
```

Il campo facoltativo [`src`](/docs/cli/reference/config#src) specifica i file sorgente in cui GT cerca contenuto inline; se omesso, vengono usati per impostazione predefinita questi glob JavaScript e TypeScript nelle directory `src`, `app`, `pages` e `components`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"],
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

### 3. Inizializza la libreria

Inizializza la libreria con [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) prima che l'applicazione venga renderizzata o che vengano importati moduli che usano funzioni di traduzione a livello di modulo.

Crea un file bootstrap accanto all'entry file esistente dell'applicazione. In questo esempio, l'entry originale è `src/main.tsx` e il nuovo file bootstrap è `src/index.ts`. Configura l'`input` esistente di Rolldown affinché punti al file bootstrap. Mantieni invariate tutte le altre impostazioni di build.

```js title="rolldown.config.mjs"
export default {
  // ...le opzioni esistenti del progetto
  input: 'src/index.ts',
};
```

Se l'HTML di sviluppo fa direttamente riferimento alla voce sorgente originale, aggiorna anche quello:

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

Quindi inizializza GT e importa dinamicamente l&#39;entry originale solo al termine dell&#39;inizializzazione. L&#39;applicazione di riferimento Rolldown genera ESM e supporta `await` a livello superiore:

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

await initializeGTSPA(gtConfig);

await import('./main'); // renderizza l'app solo dopo che GT è pronto
```

Se il formato di output o il target Rolldown esistente non supportano top-level await, non modificarli solo per questa configurazione. Usa invece una funzione bootstrap async:

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

async function bootstrap() {
  await initializeGTSPA(gtConfig);
  await import('./main');
}

void bootstrap();
```

## Caricamento delle traduzioni [#translations]

Quando [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) viene chiamato senza una funzione [`loadTranslations`](/docs/react/reference/functions/load-translations), il runtime carica le traduzioni dalla CDN di General Translation solo quando è disponibile un [`projectId`](/docs/react/reference/config#project-id). Per includere i cataloghi nel bundle dell&#39;applicazione, configura un percorso di output e il loader corrispondente. I passaggi seguenti usano `src/_gt/[locale].json`.

### 1. Aggiorna la configurazione

Imposta `files.gt.output` sulla posizione in cui la CLI deve scrivere i file di traduzione generati.

Aggiungi o unisci solo l&#39;impostazione `files.gt.output`. Mantieni i valori `locales` e `defaultLocale` già configurati nel progetto; i valori mostrati di seguito sono solo esempi e non devono sostituirli.

In genere, in un&#39;applicazione basata su Rolldown, le traduzioni vengono archiviate nella directory `src/_gt`. In questo modo Rolldown può includere i moduli di traduzione nel bundle dell&#39;applicazione.

```json title="gt.config.json"
{
  "locales": ["fr", "zh"],
  "defaultLocale": "en",
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

### 2. Aggiungi gli stub

Crea un file JSON vuoto per ogni impostazione regionale di destinazione già configurata in `gt.config.json`, escludendo l&#39;impostazione regionale predefinita. Questi stub consentono di risolvere gli import prima che esistano i bundle di traduzione. I file `fr` e `zh` riportati di seguito illustrano la configurazione di esempio di questa guida; crea invece i file corrispondenti alle effettive impostazioni regionali di destinazione configurate per il progetto. Se non sono configurate impostazioni regionali di destinazione, non inventarne né creare file placeholder.

<Files>
  <Folder name="src">
    <Folder name="_gt">
      <File name="fr.json" />

      <File name="zh.json" />
    </Folder>
  </Folder>
</Files>

```json title="src/_gt/fr.json"
{}
```

```json title="src/_gt/zh.json"
{}
```

### 3. Aggiungi il loader

Crea `src/loadTranslations.ts` per caricare le traduzioni. Deve risolvere lo stesso percorso di output configurato in `files.gt.output`.

Elenca esplicitamente tutte le impostazioni regionali di destinazione configurate in `translationLoaders`. Ogni loader deve usare un percorso di importazione letterale affinché Rolldown possa rilevare e generare ogni file di traduzione in fase di build. Le voci `fr` e `zh` riportate di seguito corrispondono alla configurazione di esempio di questa guida; usa invece le impostazioni regionali di destinazione effettivamente configurate nel progetto.

```ts title="src/loadTranslations.ts"
const translationLoaders = {
  fr: () => import('./_gt/fr.json'),
  zh: () => import('./_gt/zh.json'),
};

export default async function loadTranslations(locale: string) {
  try {
    const loader =
      translationLoaders[locale as keyof typeof translationLoaders];
    if (!loader) {
      console.warn(`No translations found for locale "${locale}"`);
      return {};
    }
    const translations = await loader();
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for locale "${locale}"`, error);
    return {};
  }
}
```

### 4. Aggiorna l’inizializzatore

Aggiorna l’inizializzatore in modo che utilizzi la nuova funzione loader. Mantieni la forma di bootstrap con top-level await o funzione async già utilizzata dall’applicazione.

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({ ...gtConfig, loadTranslations });

await import('./main');
```

## Next steps

- /docs/react/guides/spa/internationalizing-react-spa
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/storing-translations
- /docs/react/guides/managing-locales

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.