# generaltranslation: General Translation Core SDK: Guida rapida
URL: https://generaltranslation.com/it/docs/core/quickstart.mdx
---
title: Guida rapida
description: Guida rapida alla libreria generaltranslation
---
## Panoramica
Questa guida ti accompagnerà nelle basi dell'utilizzo della libreria generaltranslation.
Vedremo la traduzione delle stringhe e dei file.
***
## Traduci la tua prima stringa
### 1. Recupera le tue variabili d'ambiente
Il primo passo è creare un `GT_PROJECT_ID` e una `GT_API_KEY`.
È completamente gratuito e ti darà accesso ai servizi di traduzione.
Vai alla pagina [`API Keys`](https://dash.generaltranslation.com/api-keys) e fai clic su `Create API Key`.
Scegli un nome per la tua chiave API e fai clic su `Create`.
General Translation offre limiti gratuiti molto elevati per supportare progetti personali, sviluppatori indipendenti e la community.
### 2. Inizializza la classe GT
Inizializza la classe [`GT`](/docs/core/class/constructor) e fornisci in modo sicuro il tuo `GT_PROJECT_ID` e `GT_API_KEY`.
```typescript title="src/index.ts"
import { GT } from 'generaltranslation';
const gt = new GT({
projectId: 'your-project-id',
apiKey: 'your-api-key',
});
```
### 3. Traduci la tua prima stringa
Chiama il metodo [`translate`](/docs/core/class/methods/translation/translate) per tradurre la tua stringa.
Passa la stringa che vuoi tradurre e l'impostazione regionale di destinazione.
```typescript title="src/index.ts"
const result = await gt.translate('Hello, world!', 'es'); // Spagnolo
if (result.success) {
console.log(result.translation); // "¡Hola, mundo!"
} else {
console.error(`Traduzione non riuscita: ${result.error}`);
}
```
Se vuoi cercare un codice locale, consulta la pagina delle [impostazioni regionali supportate](/docs/platform/supported-locales).
***
## Traduci il tuo primo file
Questa guida presuppone che tu abbia già seguito i passaggi 1 e 2 della guida [Traduci
la tua prima stringa](/docs/core/quickstart#translate-your-first-string) e che
tu disponga di `GT_PROJECT_ID`, `GT_API_KEY` e di un'istanza della classe `GT`.
Supponiamo che tu voglia tradurre in spagnolo un file chiamato `en.json`.
```json title="en.json"
{
"hello": "Hello",
"world": "World"
}
```
Per tradurre un file, segui questi quattro passaggi:
1. Carica il file
2. Metti il file in coda per la traduzione
3. Controlla lo stato del file (facoltativo)
4. Scarica il file tradotto.
#### Perché non una sola chiamata? In genere, si vuole tradurre molti
file contemporaneamente. Suddividere il processo in quattro passaggi chiari offre agli utenti
molta più flessibilità nel modo in cui possono usare l'API.
### 1. Carica il file
Il caricamento dei file restituisce un elenco di riferimenti ai file con il metodo [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files).
Questo ti consente in seguito di mettere in coda il file per la traduzione, controllarne lo stato e scaricare il file tradotto.
```typescript title="src/index.ts"
import fs from 'fs';
import path from 'path';
import { FileUpload } from 'generaltranslation';
// (i) Leggi il contenuto di un file
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');
// (ii) Formatta il contenuto del file
const fileUpload: FileUpload = {
content: fileContents,
fileName: filePath,
fileFormat: 'JSON',
locale: 'en',
};
const files = [ { source: fileUpload } ];
// (iii) Carica il file
const { uploadedFiles } = await gt.uploadSourceFiles(
files,
{
sourceLocale: 'en'
}
);
```
Questo restituirà un elenco di riferimenti ai file:
```ts title="Output"
[
{
fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
branchId: '123456789',
fileName: '/Users/demo/en.json',
fileFormat: 'JSON'
}
]
```
### 2. Metti il file in coda per la traduzione
Il passaggio successivo è selezionare le impostazioni regionali di destinazione per la traduzione con il metodo [`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files).
In questo caso, tradurremo in spagnolo.
```typescript title="src/index.ts"
const fileUploadRef = {
fileId: uploadedFiles[0].fileId,
versionId: uploadedFiles[0].versionId,
branchId: uploadedFiles[0].branchId,
fileName: uploadedFiles[0].fileName,
fileFormat: uploadedFiles[0].fileFormat,
};
const enqueueResult = await gt.enqueueFiles(
[fileUploadRef],
{
sourceLocale: 'en',
targetLocales: ['es'],
});
```
Questo restituirà un risultato contenente le informazioni sul job:
```ts title="Output"
{
jobId: 'job-123456',
locales: [ 'es' ],
message: 'Creating 1 translation(s).'
}
```
### 3. Verifica lo stato del file
Ok, ora che il file è stato caricato, come facciamo a sapere quando è pronto per il download?
Possiamo usare il metodo [`queryFileData`](/docs/core/class/methods/translation/query-file-data) per verificare lo stato del file.
```typescript title="src/index.ts"
const { fileId, versionId, branchId } = uploadedFiles[0];
const status = await gt.queryFileData({
translatedFiles: [{
fileId,
versionId,
branchId,
locale: 'es'
}]
});
```
Se il file è ancora in fase di traduzione, `completedAt` sarà `null`. Una volta completata la traduzione, conterrà un timestamp.
```ts title="Output"
{
translatedFiles: [
{
fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
branchId: '123456789',
locale: 'es',
completedAt: '2024-01-15T12:00:00Z',
...
}
]
}
```
### 4. Scarica il file tradotto
Infine, puoi scaricare il file tradotto con il metodo [`downloadFile`](/docs/core/class/methods/translation/download-file).
```typescript title="src/index.ts"
const { fileId, branchId } = uploadedFiles[0];
const content = await gt.downloadFile({
fileId,
branchId,
locale: 'es',
});
```
Questo restituirà il contenuto tradotto del file:
```ts title="Output"
{
"hello": "Hola",
"world": "Mundo"
}
```