GT ClassMethodsTranslation

uploadSourceFiles

API Reference für die Methode uploadSourceFiles zum Hochladen von Quelldateien für die Übersetzung

Übersicht

Die Methode uploadSourceFiles lädt Quelldateien zur Übersetzungsverarbeitung auf die General Translation Plattform hoch. Dies ist in der Regel der erste Schritt in einem Übersetzungsworkflow, bevor Projekte eingerichtet oder Übersetzungsaufträge in die Warteschlange gestellt werden.

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

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

Referenzen

Parameter

NameTypBeschreibung
filesFileUpload[]Array von Quelldateien zum Hochladen
optionsUploadFilesOptionsKonfigurationsoptionen für den Upload

FileUpload-Struktur

NameTypBeschreibung
contentstringRohdateiinhalt als Zeichenfolge
fileNamestringEindeutige Dateikennung (in der Regel Dateipfad + Name)
fileFormatFileFormatFormat der Datei (JSON, MDX, MD, XML usw.)
dataFormat?DataFormatOptionales Format der Daten innerhalb der Datei (ICU, i18next, JSX)
localestringLocale des Quelldateiinhalts
versionId?stringOptionale Versions-ID für erweiterte Anwendungsfälle
fileId?stringOptionale Datei-ID für erweiterte Anwendungsfälle

UploadFilesOptions

NameTypeBeschreibung
sourceLocalestringDie Quell-locale für alle hochgeladenen files
modelProvider?stringOptionale bevorzugte KI-Modellanbieter
timeout?numberAnforderungs-Zeitüberschreitung in Millisekunden

Rückgabewerte

Promise<UploadFilesResponse> – enthält Upload-Ergebnisse und Dateiverweise.

type UploadFilesResponse = {
  uploadedFiles: FileUploadRef[];
  count: number;
  message: string; // Statusmeldung
}
EigenschaftTypBeschreibung
uploadedFilesFileUploadRef[]Array von Referenzen auf hochgeladene files für nachfolgende Vorgänge
countnumberAnzahl der erfolgreich hochgeladenen files
messagestringStatusmeldung der API

Struktur von FileUploadRef

type FileUploadRef = {
  fileId: string;
  versionId: string;
  fileName: string;
  fileFormat: FileFormat;
  dataFormat?: DataFormat;
  locale?: string;
}

Beispiele

Grundlegende Verwendung

Laden Sie JSON-Übersetzungsdateien hoch:

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

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

const files = [
  {
    content: fs.readFileSync('./locales/en/common.json', 'utf8'),
    fileName: 'common.json',
    fileFormat: 'JSON' as const,
    locale: 'en'
  },
  {
    content: fs.readFileSync('./locales/en/navigation.json', 'utf8'),
    fileName: 'navigation.json', 
    fileFormat: 'JSON' as const,
    locale: 'en'
  }
];

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

console.log(`Hochgeladen: ${result.count} files`);
result.uploadedFiles.forEach(file => {
  console.log(`  ${file.fileName}: ${file.fileId}`);
});

Mit Datenformatspezifikation

Laden Sie files mit expliziter Angabe des Datenformats hoch:

const files = [
  {
    content: '{"welcome": "Willkommen, {name}!"}',
    fileName: 'messages.json',
    fileFormat: 'JSON' as const,
    dataFormat: 'ICU' as const, // ICU message format
    locale: 'en'
  },
  {
    content: '{"greeting": "Hallo, {{name}}"}',
    fileName: 'i18next.json',
    fileFormat: 'JSON' as const,
    dataFormat: 'I18NEXT' as const,
    locale: 'en'
  }
];

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
  modelProvider: 'gpt-4',
  timeout: 30000
});

Stapel-Upload mit Fehlerbehandlung

Laden Sie mehrere files mit umfassender Fehlerbehandlung hoch:

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

async function uploadAllJsonFiles() {
  try {
    // Alle JSON-Dateien finden
    const jsonPaths = await glob('./locales/en/**/*.json');
    
    const files = jsonPaths.map(filePath => ({
      content: fs.readFileSync(filePath, 'utf8'),
      fileName: path.relative('./locales/en', filePath),
      fileFormat: 'JSON' as const,
      locale: 'en'
    }));

    console.log(`Lade ${files.length} files hoch...`);
    
    const result = await gt.uploadSourceFiles(files, {
      sourceLocale: 'en',
      timeout: 60000 // Zeitüberschreitung von 60 Sekunden für große Uploads
    });

    if (result.count !== files.length) {
      console.warn(`Es wurden ${files.length} files erwartet, aber nur ${result.count} hochgeladen`);
    }

    return result.uploadedFiles;
    
  } catch (error) {
    console.error('Upload fehlgeschlagen:', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();

Hinweise

  • Dateiinhalte werden für die sichere Übertragung automatisch Base64-codiert
  • Dateinamen sollten eindeutige Bezeichner sein und typischerweise den Dateipfad enthalten
  • Das Feld locale in jeder Datei sollte der Option sourceLocale entsprechen
  • Große Dateien oder viele Dateien können höhere Werte für die Zeitüberschreitung erfordern
  • Von dieser Methode zurückgegebene Dateireferenzen werden für nachfolgende Vorgänge benötigt
  • Unterstützte Dateiformate umfassen JSON, MD, MDX, XML und andere – siehe den Typ FileFormat für die vollständige Liste

Nächste Schritte

  • Siehe setupProject, um hochgeladene files für die Übersetzung vorzubereiten
  • Siehe enqueueFiles, um Übersetzungsaufträge zu starten
  • Siehe uploadTranslations, um bereits vorhandene Übersetzungen hochzuladen
  • Siehe FileUpload für die detaillierte Dateistruktur

Wie ist diese Anleitung?