Dashboard

Quickstart

Quick Start guide for the generaltranslation library

Overview

This guide will walk you through the basics of using the generaltranslation library. We will 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 will give you access to the translation services.

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

API key page

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

2. Initialize the GT class

Initialize 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 out the supported locales page.

Translate your first file

This guide assumes you already have 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 wanted to translate a file called en.json to Spanish.

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

In order to translate a file, you need to follow these four steps:

  1. Upload the file
  2. Enqueue the file for translation
  3. Check on the file status (optional)
  4. Download the translated file.

Why not just one call?

Typically, people will want to translate many files at once. By breaking these into four clear steps, it gives users much more flexibility in how they can use the API.

1. Upload the file

Uploading files returns a list of file references with the uploadSourceFiles method. This allows you to later check the 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 will return 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 will translate to 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 on the file status

Okay, now that the file is uploaded, when do we know it's ready for download? We can use the checkFileTranslations method to check on 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 with 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?

Overview

Overview of the generaltranslation library

GT Constructor

API Reference for the GT class constructor

On this page

Overview
Translate your first string
1. Get your environment variables
2. Initialize 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 on the file status
4. Download the translated file
Quickstart