# sanity: Guida rapida a Sanity
URL: https://generaltranslation.com/it/docs/sanity/guides/quickstart.mdx
---
title: Guida rapida a Sanity
description: Integra General Translation con Sanity CMS usando gt-sanity
---

**Prerequisiti:** Sanity Studio v5+, React 19+, progetto Sanity esistente

<Callout type="warn">
  **Sono richieste modifiche agli schemi e al frontend.** Ogni tipo di documento che traduci deve includere un campo `language` nel proprio schema — per i dettagli, vedi il [setup del campo language](/docs/sanity#language-field).
  Le traduzioni vengono archiviate come documenti separati, quindi dovrai anche aggiornare le query del frontend per recuperare la versione corretta nella lingua desiderata.
  Per alcuni esempi, vedi [eseguire query sul contenuto tradotto](#querying-translated-content) qui sotto.
</Callout>

## Installazione

Installa il pacchetto `gt-sanity` nella directory del tuo progetto Sanity Studio:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-sanity
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-sanity
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-sanity
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-sanity
    ```
  </Tab>
</Tabs>

## Configurazione

<Steps>
  <Step title="Aggiungi il plugin alla configurazione di Sanity">
    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { gtPlugin } from 'gt-sanity'

    export default defineConfig({
      // ... la tua configurazione esistente
      plugins: [
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja'], // Sostituisci con le tue impostazioni regionali di destinazione
          translateDocuments: [{ type: 'article' }, { type: 'page' }], // Tipi di documento per cui abilitare le traduzioni
        })
      ]
    })
    ```

    Quando viene specificato `translateDocuments`, il plugin aggiunge automaticamente le funzionalità di @sanity/document-internationalization: badge della lingua, un menu di traduzione nella barra degli strumenti del documento e template di documento per lingua. Imposta `showDocumentInternationalization: false` per disattivarlo.
  </Step>

  <Step title="Aggiungi un campo language ai tuoi schemi">
    Ogni tipo di documento che traduci deve avere un campo `language`:

    ```typescript title="schema/article.ts"
    import { defineField, defineType } from 'sanity'

    export const articleType = defineType({
      name: 'article',
      title: 'Article',
      type: 'document',
      fields: [
        // ... i tuoi campi esistenti
        defineField({
          name: 'language',
          type: 'string',
          readOnly: true,
          hidden: true,
        }),
      ],
    })
    ```

    Se hai configurato un `languageField` personalizzato nelle opzioni del plugin, usa quel nome invece di `'language'`.
  </Step>

  <Step title="Configura le credenziali API">
    Nella cartella del tuo Studio, crea un file chiamato `populateSecrets.js` con il seguente contenuto:

    ```javascript title="populateSecrets.js"
    import { getCliClient } from 'sanity/cli';

    const client = getCliClient({ apiVersion: '2026-04-06' });

    client.createOrReplace({
      // Il `.` in questo _id farà sì che il documento sia privato
      // anche in un dataset pubblico!
      _id: 'generaltranslation.secrets',
      _type: 'generaltranslationSettings',
      secret: process.env.GT_API_KEY,
      project: process.env.GT_PROJECT_ID,
    });
    ```

    Quindi, ottieni una chiave API di produzione da [dash.generaltranslation.com](https://dash.generaltranslation.com).

    Esegui lo script con le tue credenziali:

    ```bash
    GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token
    ```

    Verifica che il documento sia stato creato usando Vision Tool nello Studio ed eseguendo la query `*[_id == 'generaltranslation.secrets']`.

    Nota: se hai più dataset, dovrai farlo in tutti.

    Se il documento è stato trovato nel tuo dataset o nei tuoi dataset, elimina `populateSecrets.js`.

    <Callout type="warn">
      Queste credenziali verranno archiviate nel database di Sanity. Per impostazione predefinita, sono archiviate nel documento `generaltranslation.secrets`, che è privato per impostazione predefinita, anche in un dataset pubblico.
      Tuttavia, se temi che possano essere esposte agli utenti autenticati del tuo Studio, puoi controllare l&#39;accesso a questo percorso con il [controllo degli accessi basato sui ruoli](https://www.sanity.io/docs/access-control).
    </Callout>
  </Step>

  <Step title="(Facoltativo) Aggiungi una scheda Translations dedicata">
    Il plugin aggiunge automaticamente un&#39;azione **Traduci** a ogni documento che apre una finestra di dialogo. Se vuoi anche una vista in una scheda dedicata, aggiungi il componente `TranslationsTab` alle viste del documento:

    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { structureTool } from 'sanity/structure'
    import { gtPlugin, TranslationsTab } from 'gt-sanity'

    export default defineConfig({
      // ... la tua configurazione
      plugins: [
        structureTool({
          structure: (S) =>
            S.list()
              .title('Contenuto')
              .items(S.documentTypeListItems()),
          defaultDocumentNode: (S, { schemaType }) => {
            return S.document().views([
              S.view.form(),
              S.view
                .component(TranslationsTab)
                .title('General Translation')
            ])
          }
        }),
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja']
        })
      ]
    })
    ```
  </Step>
</Steps>

## Utilizzo

Una volta configurato, puoi tradurre i documenti direttamente da Sanity Studio:

1. Apri un documento qualsiasi nello Studio
2. Fai clic sul pulsante **Traduci** nella barra delle azioni del documento — si aprirà una finestra di dialogo
3. Seleziona le lingue di destinazione
4. Fai clic su **Generate Translations** per inviare i contenuti alla traduzione
5. Per impostazione predefinita, il plugin importerà automaticamente le traduzioni nel documento non appena saranno pronte.
6. Inoltre, i documenti importati verranno analizzati automaticamente per individuare eventuali riferimenti ad altri documenti e aggiornati in modo che puntino alle traduzioni corrette di tali documenti.

## Eseguire query sul contenuto tradotto

Il plugin archivia le traduzioni come documenti separati con un campo `language` (configurabile tramite [`languageField`](/docs/sanity/api/plugin-config)). Le query GROQ esistenti per il contenuto di origine continuano a funzionare senza alcuna modifica.

Per recuperare il contenuto tradotto, filtra per il campo `language`:

<Tabs items={["Query di base", "Query localizzata"]}>
  <Tab value="Base Query">
    Le query esistenti restano invariate — non devi modificare nulla:

    ```plaintext
    // Recupera tutti gli articoli (restituisce i documenti nella lingua di origine)
    *[_type == "article"]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Localized Query">
    Per recuperare i documenti tradotti, aggiungi un filtro `language`:

    ```plaintext
    // Recupera gli articoli in spagnolo
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }

    // Recupera un articolo specifico in una lingua specifica
    *[_type == "article" && slug.current == "hello-world" && language == "es"][0]{
      title,
      body
    }

    // Recupera gli articoli in qualsiasi lingua
    *[_type == "article"]{
      title,
      slug,
      body,
      language
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Per impostazione predefinita, nei documenti di origine il campo `language` non è impostato. Per interrogare il contenuto di origine insieme alle traduzioni, puoi filtrare i documenti in cui `language` corrisponde alla tua impostazione regionale di origine oppure non è impostato: `language == "en" || !defined(language)`.
</Callout>

## Passaggi successivi

* [Guida alla configurazione](/docs/sanity/guides/configuration) - Personalizza il comportamento del plugin
* [Guida alla serializzazione](/docs/sanity/guides/serialization) - Regole di serializzazione personalizzate
* [Riferimento API](/docs/sanity/api/plugin-config) - Opzioni di configurazione complete