# General Translation Integrations: Guida rapida
URL: https://generaltranslation.com/it/docs/integrations/sanity/quickstart.mdx
---
title: Guida rapida
description: Installa gt-sanity, aggiungi il plugin di General Translation a Sanity Studio e traduci il tuo primo documento.
related:
links:
- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/managing-translations
- /docs/integrations/sanity/guides/querying-translations
- /docs/integrations/sanity/guides/configuring-sanity
---
Il plugin `gt-sanity` di General Translation traduce i documenti di Sanity direttamente da Sanity Studio.
Il plugin usa la localizzazione a livello di documento: ogni traduzione viene archiviata come documento Sanity separato con un campo `language`, ad esempio `language: "es"`. Le traduzioni sono collegate al documento sorgente tramite un documento `translation.metadata` gestito da `@sanity/document-internationalization`.
## Prima di iniziare [#before-start]
Ti servono:
* Sanity Studio 5.0.0 o successivo.
* React 19.2.0 o successivo.
* Un progetto Sanity esistente.
* Un [ID progetto](/docs/platform/dashboard/get-started) di General Translation e una [chiave API](/docs/platform/dashboard/reference/api-keys) per la produzione.
## Guida rapida [#quickstart]
### 1. Installa `gt-sanity` [#install]
Installa il plugin nel progetto Sanity Studio.
```bash
npm install gt-sanity
```
```bash
yarn add gt-sanity
```
```bash
bun add gt-sanity
```
```bash
pnpm add gt-sanity
```
### 2. Aggiungi il plugin [#add-plugin]
Aggiungi `gtPlugin` a `sanity.config.ts`. Imposta l'impostazione regionale sorgente, le impostazioni regionali di destinazione e i tipi di documento da tradurre.
```ts 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'],
translateDocuments: [{ type: 'article' }, { type: 'page' }],
}),
],
});
```
Quando `translateDocuments` include tipi di documento, il plugin aggiunge automaticamente il plugin `@sanity/document-internationalization`: badge di lingua, un menu di traduzione nella barra degli strumenti del documento e modelli di documento per ogni lingua. Imposta `showDocumentInternationalization: false` per disattivarlo.
### 3. Aggiungi un language field [#language-field]
Ogni tipo di documento che traduci deve avere un language field. Per impostazione predefinita si chiama `language`.
```ts 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 imposti un [`languageField`](/docs/integrations/sanity/reference/plugin-configuration#language-field) personalizzato nelle opzioni del plugin, usa quel nome nel tuo schema anziché `language`.
### 4. Salva le credenziali [#credentials]
Il plugin legge la tua chiave API di General Translation e l'ID progetto da un documento privato di Sanity. Crea un file temporaneo `populateSecrets.js` nella cartella del tuo Studio.
```js title="populateSecrets.js"
import { getCliClient } from 'sanity/cli';
const client = getCliClient({ apiVersion: '2026-04-06' });
client.createOrReplace({
// Il `.` iniziale in questo _id mantiene il documento privato,
// anche in un dataset pubblico.
_id: 'generaltranslation.secrets',
_type: 'generaltranslation.secrets',
secret: process.env.GT_API_KEY,
project: process.env.GT_PROJECT_ID,
});
```
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
```
Il documento `_id` deve corrispondere al `secretsNamespace` del plugin (impostazione predefinita: `generaltranslation.secrets`). Il plugin legge il campo `secret` come chiave API e il campo `project` come ID progetto.
Verifica che il documento esista con lo strumento Vision nel tuo Studio:
```text
*[_id == 'generaltranslation.secrets']
```
Se utilizzi più dataset, ripeti questa operazione per ognuno di essi. Dopo aver verificato, elimina `populateSecrets.js`.
### 5. Tradurre un documento [#translate-document]
1. Apri un documento nella lingua sorgente in Sanity Studio.
2. Fai clic su **Traduci** nella barra delle azioni del documento.
3. Seleziona le impostazioni regionali di destinazione.
4. Fai clic su **Genera traduzioni**.
Nella finestra di dialogo del documento, il plugin controlla periodicamente se le traduzioni sono state completate e le importa automaticamente. Dopo l'importazione, aggiorna i riferimenti del documento e pubblica i documenti tradotti, poiché in questa finestra di dialogo l'importazione automatica, l'aggiornamento automatico dei riferimenti e la pubblicazione automatica sono attivi per impostazione predefinita.
Consulta le guide complete per [tradurre i contenuti](/docs/integrations/sanity/guides/translating-content) e [gestire le traduzioni](/docs/integrations/sanity/guides/managing-translations).
### 6. Esegui query sui contenuti tradotti [#query-content]
Le traduzioni sono archiviate come documenti separati con un language field. Per recuperare i contenuti tradotti, filtra in base al language field.
```text
// Per impostazione predefinita, i documenti nella lingua sorgente non impostano il language field
*[_type == "article" && !defined(language)]{
title,
slug,
body
}
```
```text
// Recupera gli articoli in spagnolo
*[_type == "article" && language == "es"]{
title,
slug,
body
}
```
Per altri pattern di query, vedi [Interrogare le traduzioni](/docs/integrations/sanity/guides/querying-translations).
## Next steps
- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/managing-translations
- /docs/integrations/sanity/guides/querying-translations
- /docs/integrations/sanity/guides/configuring-sanity