Einführung

Die Bibliothek generaltranslation ist die zentrale i18n-Bibliothek von GT und stellt Hilfsfunktionen und -klassen für Übersetzung und Formatierung bereit. Sie wird am häufigsten mit Framework-Paketen wie gt-next und gt-react verwendet, kann aber auch als eigenständige Bibliothek genutzt werden.

import { GT } from 'generaltranslation';

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

// Inhalte übersetzen
const result = await gt.translate('Hello, world!', 'es');
// "¡Hola, mundo!"

// Zahlen, Daten und Währungen formatieren
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/2025"

// Mit Locales arbeiten
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true

Installation

npm install generaltranslation

yarn add generaltranslation

bun add generaltranslation

pnpm add generaltranslation

Beispiele

Es gibt zwei Hauptarten der Übersetzung: Übersetzung von Zeichenketten und Übersetzung von Dateien.

Einrichtung

Um Übersetzungen zu aktivieren, müssen Sie eine Projekt-ID und einen API-Schlüssel bereitstellen. Weitere Informationen finden Sie in der Methode constructor.

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

Stringübersetzung

Weitere Informationen finden Sie in der Methode translate.

try {
  const result = await gt.translate('Hallo, Welt!');
  console.log(result); // "¡Hola, mundo!"
} catch (error) {
  console.error('Übersetzung fehlgeschlagen:', error.message);
}

Dateiübersetzung

Dateien werden als Jobs übersetzt. Sie starten einen Job, indem Sie eine Datei hochladen. Wenn Sie viele Dateien hochladen, werden entsprechend viele Jobs gestartet.

Weitere Informationen finden Sie in den Methoden uploadSourceFiles und checkFileTranslations.

// Dateien zum Hochladen
const files = [
  {
    source: {
      fileName: 'src/components/Button.tsx',
      fileFormat: 'TSX',
      locale: 'en',
      content: '...',
    },
  },
];

// Quelldateien hochladen
await gt.uploadSourceFiles(files);

Inhaltsverzeichnis

GT-Klasse

Hauptklasse für Übersetzungs- und Locale-Funktionen:

• Constructor - GT-Instanz mit Konfiguration initialisieren
• setConfig - Konfiguration der GT-Instanz aktualisieren

Übersetzungsmethoden

• translate - Zentrale Übersetzungsfunktion
• translateMany - Übersetzung im Batch
• setupProject - Projekt einrichten
• shouldSetupProject - Prüfen, ob die Projekteinrichtung erforderlich ist
• checkSetupStatus - Projekteinrichtung prüfen
• getProjectData - Projektinformationen abrufen
• uploadSourceFiles - Quelldateien hochladen
• enqueueFiles - Dateien zur Verarbeitung in die Warteschlange stellen
• checkFileTranslations - Übersetzungsstatus prüfen
• downloadTranslatedFile - Übersetzte Datei herunterladen
• downloadFileBatch - Mehrere übersetzte Dateien herunterladen
• querySourceFile - Quelldatei abfragen

Formatierungsmethoden

• formatMessage - Internationalisierte Textformatierung
• formatNum - Zahlenformatierung
• formatDateTime - Datums- und Zeitformatierung

Locale-Methoden

• getLocaleName - Anzeigename der locale
• getLocaleProperties - Umfassende Informationen zur locale
• getLocaleDirection - Textrichtung der locale
• getLocaleEmoji - Flaggen-Emoji der locale
• getRegionProperties - Regionsinformationen und ‑eigenschaften
• isValidLocale - locale code validieren
• resolveAliasLocale - Kanonische locales in Aliasse umwandeln
• resolveCanonicalLocale - Alias-locales in kanonische Form umwandeln
• standardizeLocale - Formatierung des locale code standardisieren
• isSameDialect - Prüfen, ob locales denselben Dialekt darstellen
• isSameLanguage - Prüfen, ob locales dieselbe Sprache darstellen
• isSupersetLocale - Hierarchische Beziehungen zwischen locales prüfen
• determineLocale - Am besten passende locale aus Präferenzen ermitteln
• requiresTranslation - Ermitteln, ob eine Übersetzung erforderlich ist

Hilfsfunktionen

Formatierungsfunktionen

• formatMessage - Unabhängige Textformatierung
• formatNum - Unabhängige Zahlenformatierung
• formatDateTime - Unabhängige Datums-/Uhrzeitformatierung

Locale-Funktionen

• getLocaleName - Eigenständiges Tool für Locale-Namen
• getLocaleProperties - Eigenständige Locale-Eigenschaften
• getLocaleDirection - Eigenständiges Tool für Textrichtung
• getLocaleEmoji - Eigenständiges Emoji-Tool
• getRegionProperties - Eigenständiges Tool für Regions­eigenschaften
• isValidLocale - Eigenständige Locale-Validierung
• resolveAliasLocale - Eigenständige Auflösung von Alias-Locales
• standardizeLocale - Eigenständige Locale-Standardisierung
• isSameDialect - Eigenständiger Dialektvergleich
• isSameLanguage - Eigenständiger Sprachvergleich
• isSupersetLocale - Eigenständige Prüfung der Locale-Hierarchie
• determineLocale - Eigenständige Locale-Aushandlung
• requiresTranslation - Eigenständige Prüfung des Übersetzungsbedarfs

Typen und Schnittstellen

TypeScript-Definitionen:

• GTConstructorParams - Konfigurationsoptionen
• LocaleProperties - Umfassende Informationen zur Locale
• TranslationResult - Typen für Übersetzungsergebnisse
• TranslateManyResult - Ergebnis für Batch-Übersetzungen
• FileToTranslate - Konfiguration für Datei-Übersetzungen
• EnqueueFilesOptions - Optionen für die Dateiwarteschlange
• Entry - Struktur eines Translation-Entry
• EntryMetadata - Informationen zu Entry-Metadaten
• Content - Definitionen von Inhaltstypen
• Variable - Struktur von Variable
• VariableType - Definitionen von VariableType
• JsxElement - JSX-Element-Typ
• JsxChild - JSX-Kind-Typ
• JsxChildren - JSX-Children-Typ
• DataFormat - Spezifikationen für DataFormat
• CustomMapping - Konfiguration für CustomMapping

Nächste Schritte

• Einstieg in die GT-Klasse
• Übersetzungsmethoden entdecken
• Mehr über Locale-Utilities erfahren
• Formatierungsoptionen ansehen
• Eigenständige Funktionen durchsuchen

Für framework-spezifische Verwendung siehe die Dokumentation zu Next.js oder React.