uploadTranslations

Overview

The uploadTranslations method uploads translation files that correspond to previously uploaded source files. This is useful when you have pre-existing translations that you want to upload directly rather than generating them through the translation service.

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

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en'
});

You must have previously uploaded the source files using uploadSourceFiles before uploading translations.

Reference

Parameters

Name	Type	Description
`files`	`TranslationUpload[]`	Array of source file references with their translations
`options`	`UploadFilesOptions`	Configuration options for the upload

TranslationUpload Structure

type TranslationUpload = {
  source: FileUpload;      // Reference to existing source file (no content needed)
  translations: FileUpload[]; // Array of translated files with content
}

FileUpload Structure (for source reference)

Name	Type	Description
`fileName`	`string`	File name matching the previously uploaded source file
`fileFormat`	`FileFormat`	Format of the file (JSON, MDX, MD, XML, etc.)
`fileId?`	`string`	Optional file ID of the source file
`versionId?`	`string`	Optional version ID of the source file

FileUpload Structure (for translations)

Name	Type	Description
`content`	`string`	Raw translated file content as a string
`fileName`	`string`	File name for the translation
`fileFormat`	`FileFormat`	Format of the file (JSON, MDX, MD, XML, etc.)
`locale`	`string`	Target locale of the translation
`fileId?`	`string`	Optional file ID
`versionId?`	`string`	Optional version ID

UploadFilesOptions

Name	Type	Description
`sourceLocale`	`string`	The source locale for the files
`branchId?`	`string`	Optional branch ID to upload to
`timeout?`	`number`	Request timeout in milliseconds

Returns

Promise<UploadFilesResponse> - Contains upload results and file references.

type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}

Property	Type	Description
`uploadedFiles`	`FileReference[]`	Array of uploaded file references
`count`	`number`	Number of files successfully uploaded
`message`	`string`	Status message from the API

Examples

Basic usage

Upload translations for previously uploaded source files:

import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Assume source file was previously uploaded
const files = [
  {
    source: {
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      fileId: 'source-file-id',
      versionId: 'source-version-id'
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'es'
      },
      {
        content: fs.readFileSync('./locales/fr/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'fr'
      }
    ]
  }
];

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en'
});

console.log(`Uploaded ${result.count} translation files`);

Upload after source upload

Complete workflow uploading source files then translations:

import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Step 1: Upload source files
const sourceFiles = [
  {
    source: {
      content: fs.readFileSync('./locales/en/messages.json', 'utf8'),
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      locale: 'en'
    }
  }
];

const { uploadedFiles } = await gt.uploadSourceFiles(sourceFiles, {
  sourceLocale: 'en'
});

// Step 2: Upload existing translations
const translationFiles = [
  {
    source: {
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      fileId: uploadedFiles[0].fileId,
      versionId: uploadedFiles[0].versionId
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'es'
      },
      {
        content: fs.readFileSync('./locales/de/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'de'
      }
    ]
  }
];

const translationResult = await gt.uploadTranslations(translationFiles, {
  sourceLocale: 'en'
});

console.log(`Uploaded ${translationResult.count} translations`);

Batch upload multiple files

Upload translations for multiple source files:

import { glob } from 'glob';
import path from 'path';

async function uploadAllTranslations(
  sourceRefs: FileReference[],
  targetLocales: string[]
) {
  const files = sourceRefs.map(sourceRef => ({
    source: {
      fileName: sourceRef.fileName,
      fileFormat: sourceRef.fileFormat,
      fileId: sourceRef.fileId,
      versionId: sourceRef.versionId
    },
    translations: targetLocales
      .map(locale => {
        const translationPath = `./locales/${locale}/${sourceRef.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: sourceRef.fileName,
            fileFormat: sourceRef.fileFormat,
            locale
          };
        } catch {
          // Translation file doesn't exist for this locale
          return null;
        }
      })
      .filter(Boolean)
  }));

  const result = await gt.uploadTranslations(files, {
    sourceLocale: 'en',
    timeout: 60000
  });

  return result;
}

Notes

Source files must be uploaded first using uploadSourceFiles
The source object in each file entry is a reference to an existing source file (content is not needed)
Each translation in the translations array must include content and a target locale
This method is useful for migrating existing translations or uploading human-reviewed translations
File references include branchId for proper versioning with branching support

Next steps

See uploadSourceFiles to upload source files first
See enqueueFiles to generate translations automatically
See downloadFile to download translations
See queryFileData to check translation status

Overview

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

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en'
});

You must have previously uploaded the source files using uploadSourceFiles before uploading translations.

Reference

Parameters

Name	Type	Description
`files`	`TranslationUpload[]`	Array of source file references with their translations
`options`	`UploadFilesOptions`	Configuration options for the upload

TranslationUpload Structure

type TranslationUpload = {
  source: FileUpload;      // Reference to existing source file (no content needed)
  translations: FileUpload[]; // Array of translated files with content
}

FileUpload Structure (for source reference)

Name	Type	Description
`fileName`	`string`	File name matching the previously uploaded source file
`fileFormat`	`FileFormat`	Format of the file (JSON, MDX, MD, XML, etc.)
`fileId?`	`string`	Optional file ID of the source file
`versionId?`	`string`	Optional version ID of the source file

FileUpload Structure (for translations)

Name	Type	Description
`content`	`string`	Raw translated file content as a string
`fileName`	`string`	File name for the translation
`fileFormat`	`FileFormat`	Format of the file (JSON, MDX, MD, XML, etc.)
`locale`	`string`	Target locale of the translation
`fileId?`	`string`	Optional file ID
`versionId?`	`string`	Optional version ID

UploadFilesOptions

Name	Type	Description
`sourceLocale`	`string`	The source locale for the files
`branchId?`	`string`	Optional branch ID to upload to
`timeout?`	`number`	Request timeout in milliseconds

Returns

Promise<UploadFilesResponse> - Contains upload results and file references.

type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}

Property	Type	Description
`uploadedFiles`	`FileReference[]`	Array of uploaded file references
`count`	`number`	Number of files successfully uploaded
`message`	`string`	Status message from the API

Examples

Basic usage

Upload translations for previously uploaded source files:

import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Assume source file was previously uploaded
const files = [
  {
    source: {
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      fileId: 'source-file-id',
      versionId: 'source-version-id'
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'es'
      },
      {
        content: fs.readFileSync('./locales/fr/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'fr'
      }
    ]
  }
];

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en'
});

console.log(`Uploaded ${result.count} translation files`);

Upload after source upload

Complete workflow uploading source files then translations:

import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Step 1: Upload source files
const sourceFiles = [
  {
    source: {
      content: fs.readFileSync('./locales/en/messages.json', 'utf8'),
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      locale: 'en'
    }
  }
];

const { uploadedFiles } = await gt.uploadSourceFiles(sourceFiles, {
  sourceLocale: 'en'
});

// Step 2: Upload existing translations
const translationFiles = [
  {
    source: {
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      fileId: uploadedFiles[0].fileId,
      versionId: uploadedFiles[0].versionId
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'es'
      },
      {
        content: fs.readFileSync('./locales/de/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'de'
      }
    ]
  }
];

const translationResult = await gt.uploadTranslations(translationFiles, {
  sourceLocale: 'en'
});

console.log(`Uploaded ${translationResult.count} translations`);

Batch upload multiple files

Upload translations for multiple source files:

import { glob } from 'glob';
import path from 'path';

async function uploadAllTranslations(
  sourceRefs: FileReference[],
  targetLocales: string[]
) {
  const files = sourceRefs.map(sourceRef => ({
    source: {
      fileName: sourceRef.fileName,
      fileFormat: sourceRef.fileFormat,
      fileId: sourceRef.fileId,
      versionId: sourceRef.versionId
    },
    translations: targetLocales
      .map(locale => {
        const translationPath = `./locales/${locale}/${sourceRef.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: sourceRef.fileName,
            fileFormat: sourceRef.fileFormat,
            locale
          };
        } catch {
          // Translation file doesn't exist for this locale
          return null;
        }
      })
      .filter(Boolean)
  }));

  const result = await gt.uploadTranslations(files, {
    sourceLocale: 'en',
    timeout: 60000
  });

  return result;
}

Notes

Source files must be uploaded first using uploadSourceFiles
The source object in each file entry is a reference to an existing source file (content is not needed)
Each translation in the translations array must include content and a target locale
This method is useful for migrating existing translations or uploading human-reviewed translations
File references include branchId for proper versioning with branching support

Next steps

See uploadSourceFiles to upload source files first
See enqueueFiles to generate translations automatically
See downloadFile to download translations
See queryFileData to check translation status

Overview

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

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en'
});

You must have previously uploaded the source files using uploadSourceFiles before uploading translations.

Reference

Parameters

Name	Type	Description
`files`	`TranslationUpload[]`	Array of source file references with their translations
`options`	`UploadFilesOptions`	Configuration options for the upload

TranslationUpload Structure

type TranslationUpload = {
  source: FileUpload;      // Reference to existing source file (no content needed)
  translations: FileUpload[]; // Array of translated files with content
}

FileUpload Structure (for source reference)

Name	Type	Description
`fileName`	`string`	File name matching the previously uploaded source file
`fileFormat`	`FileFormat`	Format of the file (JSON, MDX, MD, XML, etc.)
`fileId?`	`string`	Optional file ID of the source file
`versionId?`	`string`	Optional version ID of the source file

FileUpload Structure (for translations)

Name	Type	Description
`content`	`string`	Raw translated file content as a string
`fileName`	`string`	File name for the translation
`fileFormat`	`FileFormat`	Format of the file (JSON, MDX, MD, XML, etc.)
`locale`	`string`	Target locale of the translation
`fileId?`	`string`	Optional file ID
`versionId?`	`string`	Optional version ID

UploadFilesOptions

Name	Type	Description
`sourceLocale`	`string`	The source locale for the files
`branchId?`	`string`	Optional branch ID to upload to
`timeout?`	`number`	Request timeout in milliseconds

Returns

Promise<UploadFilesResponse> - Contains upload results and file references.

type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}

Property	Type	Description
`uploadedFiles`	`FileReference[]`	Array of uploaded file references
`count`	`number`	Number of files successfully uploaded
`message`	`string`	Status message from the API

Examples

Basic usage

Upload translations for previously uploaded source files:

import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Assume source file was previously uploaded
const files = [
  {
    source: {
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      fileId: 'source-file-id',
      versionId: 'source-version-id'
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'es'
      },
      {
        content: fs.readFileSync('./locales/fr/common.json', 'utf8'),
        fileName: 'common.json',
        fileFormat: 'JSON' as const,
        locale: 'fr'
      }
    ]
  }
];

const result = await gt.uploadTranslations(files, {
  sourceLocale: 'en'
});

console.log(`Uploaded ${result.count} translation files`);

Upload after source upload

Complete workflow uploading source files then translations:

import { GT } from 'generaltranslation';
import fs from 'fs';

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

// Step 1: Upload source files
const sourceFiles = [
  {
    source: {
      content: fs.readFileSync('./locales/en/messages.json', 'utf8'),
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      locale: 'en'
    }
  }
];

const { uploadedFiles } = await gt.uploadSourceFiles(sourceFiles, {
  sourceLocale: 'en'
});

// Step 2: Upload existing translations
const translationFiles = [
  {
    source: {
      fileName: uploadedFiles[0].fileName,
      fileFormat: uploadedFiles[0].fileFormat,
      fileId: uploadedFiles[0].fileId,
      versionId: uploadedFiles[0].versionId
    },
    translations: [
      {
        content: fs.readFileSync('./locales/es/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'es'
      },
      {
        content: fs.readFileSync('./locales/de/messages.json', 'utf8'),
        fileName: 'messages.json',
        fileFormat: 'JSON' as const,
        locale: 'de'
      }
    ]
  }
];

const translationResult = await gt.uploadTranslations(translationFiles, {
  sourceLocale: 'en'
});

console.log(`Uploaded ${translationResult.count} translations`);

Batch upload multiple files

Upload translations for multiple source files:

import { glob } from 'glob';
import path from 'path';

async function uploadAllTranslations(
  sourceRefs: FileReference[],
  targetLocales: string[]
) {
  const files = sourceRefs.map(sourceRef => ({
    source: {
      fileName: sourceRef.fileName,
      fileFormat: sourceRef.fileFormat,
      fileId: sourceRef.fileId,
      versionId: sourceRef.versionId
    },
    translations: targetLocales
      .map(locale => {
        const translationPath = `./locales/${locale}/${sourceRef.fileName}`;
        try {
          return {
            content: fs.readFileSync(translationPath, 'utf8'),
            fileName: sourceRef.fileName,
            fileFormat: sourceRef.fileFormat,
            locale
          };
        } catch {
          // Translation file doesn't exist for this locale
          return null;
        }
      })
      .filter(Boolean)
  }));

  const result = await gt.uploadTranslations(files, {
    sourceLocale: 'en',
    timeout: 60000
  });

  return result;
}

Notes

Source files must be uploaded first using uploadSourceFiles
The source object in each file entry is a reference to an existing source file (content is not needed)
Each translation in the translations array must include content and a target locale
This method is useful for migrating existing translations or uploading human-reviewed translations
File references include branchId for proper versioning with branching support

Next steps

See uploadSourceFiles to upload source files first
See enqueueFiles to generate translations automatically
See downloadFile to download translations
See queryFileData to check translation status

uploadTranslations

On this page

uploadTranslations

On this page

uploadTranslations

On this page