Dashboard

Quick start

Quick-start guide for the generaltranslation library

Overview

This guide will take you through the basics of using the generaltranslation library. We’ll cover string translation and file translation.

Translate your first string

1. Get your environment variables

The very first step is to create a GT_PROJECT_ID and GT_API_KEY. This is completely free and gives you access to the translation services.

Navigate to the API Keys page and click Create API Key. Choose a name for your API key, then click Create.

API key page

General Translation offers very generous free rate limits to support personal projects, solo developers, and the community.

2. Initialise the GT class

Initialise the GT class and securely pass your GT_PROJECT_ID and GT_API_KEY.

src/index.ts
import { GT } from 'generaltranslation';

const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

3. Translate your first string

Call the translate method to translate your string. Pass the string you want to translate and the target locale.

src/index.ts
const { translation } = await gt.translate('Hello, world!', 'es'); // Spanish

console.log(translation); // "¡Hola, mundo!"

If you want to look up a locale code, check the supported locales page.

Translate your first file

This guide assumes you have already followed steps 1 and 2 of the Translate your first string guide and have a GT_PROJECT_ID, GT_API_KEY, and a GT class instance.

Let's say you want to translate a file called en.json into Spanish.

en.json
{
  "hello": "Hello",
  "world": "World"
}

To translate a file, follow these four steps:

  1. Upload the file
  2. Queue the file for translation
  3. Check the file’s status (optional)
  4. Download the translated file.

Why not just one call?

Typically, people will want to translate many files at once. Breaking this into four clear steps gives users much more flexibility in how they use the API.

1. Upload the file

Uploading files returns a list of file references with the uploadSourceFiles method. This allows you to later enqueue the file for translation, check the status of the file, and download the translated file.

src/index.ts
import fs from 'fs';
import path from 'path';
import { FileUpload } from 'generaltranslation';

// (i) Read the content of a file
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');

// (ii) Format the file contents
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [ { source: fileUpload } ];

// (iii) Upload the file
const { uploadedFiles } = await gt.uploadSourceFiles(
  files,
  {
    sourceLocale: 'en'
  }
);

This returns a list of file references:

Output
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]

2. Enqueue the file for translation

The next step is to select the target locales for the translation with the enqueueFiles method. In this case, we’ll translate into Spanish.

src/index.ts
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};
const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
  sourceLocale: 'en',
  targetLocales: ['es'],
});

This will return a list of file references:

Output
{
  translations: [],
  data: {
    '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e': {
      fileName: '/Users/demo/en.json',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121'
    }
  },
  locales: [ 'es' ],
  message: 'Creating 1 translation(s).'
}

3. Check the file status

Right, now that the file is uploaded, how do we know when it’s ready to download? We can use the checkFileTranslations method to check the file status.

src/index.ts
const status = await gt.checkFileTranslations([{
  versionId: uploadedFiles[0].versionId,
  fileName: uploadedFiles[0].fileName,
  locale: 'es'
}]);

If the file is still being translated, there will be no corresponding translations in the output.

Output
{
  translations: [
    {
      locale: 'es',
      metadata: {},
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileName: '/Users/demo/en.json',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      id: 'skl44z0ieuvdcomw38zb5chv',
      isReady: true,
      downloadUrl: '/v2/project/translations/files/skl44z0ieuvdcomw38zb5chv/download'
    }
  ]
}

4. Download the translated file

Finally, we can download the translated file using the downloadTranslatedFile method.

src/index.ts
const { translation } = await gt.downloadTranslatedFile({
  fileId: uploadedFiles[0].fileId,
  locale: 'es',
  versionId: uploadedFiles[0].versionId,
});

This will return the translated file content:

Output
{
  "hello": "Hola",
  "world": "Mundo"
}

How is this guide?

On this page

Overview
Translate your first string
1. Get your environment variables
2. Initialise the GT class
3. Translate your first string
Translate your first file
Why not just one call?
1. Upload the file
2. Enqueue the file for translation
3. Check the file status
4. Download the translated file
Quick start