Class: InternationalizationAPI

Returns#

string

The currently set locale as a string, or the fallback locale if none is set.

Signature#

getLocale(): string

Parameters#

Returns#

string[]

An array of locale strings that have translations available.

Example#

const allLocales = cesdk.i18n.listLocales();
console.log('Available locales:', allLocales);
// Output: ['en', 'de', 'fr', ...]

// Find all English variants using wildcard
const englishLocales = cesdk.i18n.listLocales({ matcher: 'en*' });
console.log('English locales:', englishLocales);
// Output: ['en', 'en-US', 'en-GB', ...]

Signature#

listLocales(options?: object): string[]

This will not check whether translations for the given locale are available.

Parameters#

Returns#

void

This method allows you to provide custom translations that will be used by the editor interface. Translations are organized by locale and can override or extend the default editor translations.

Parameters#

Returns#

void

Example#

setTranslations({
 en: {
   presets: {
     scene: ...
   }
 }
})

Signature#

setTranslations(definition: Partial<Record<LocaleKey, Partial<Translations>>>): void

This method returns the translations for the given locales, or all available translations if no specific locales are provided.

Parameters#

Returns#

Partial<Record<LocaleKey, Partial<Translations>>>

An object mapping locale strings to their respective translations.

Signature#

getTranslations(locales?: string[]): Partial<Record<LocaleKey, Partial<Translations>>>

This method retrieves the translation for the given key(s) in the currently active locale. When an array of keys is provided, the first key that has a translation will be used. If no translation is found for any of the provided keys, the last key in the array (or the single key if a string is provided) will be returned as the fallback value.

Parameters#

Returns#

string

The translated string for the key in the current locale, or the key itself if no translation is found.

Example#

// Single key
const translation = cesdk.i18n.translate('common.save');
// Returns: "Save" (if translation exists) or "common.save" (if not found)

// Array of keys (fallback)
const translation = cesdk.i18n.translate(['specific.save', 'common.save']);
// Tries 'specific.save' first, then 'common.save'
// Returns the first found translation or "common.save" if neither exists

// With interpolation values
const translation = cesdk.i18n.translate('error.fileTooLarge', { maxSize: '10MB' });

Signature#

translate(key: string | string[], options?: Record<string, unknown>): string

Use this in your own error handling—a custom onError, a toast, or a headless flow—to show the same localized text without reimplementing the lookup. For a @cesdk/engine#EngineError with a catalog code it returns your authored error.<code> / error.<code>.description override (registered via setTranslations), falling back to the engine’s English message and hint when no copy is authored—so the result is never blank or a raw code. Plain Errors return only a description (their message); branch on the structured code rather than the message string for stable handling.

Parameters#

Returns#

The resolved { message, description } copy, or undefined when there is nothing to show.

Example#

try {
  await cesdk.engine.scene.loadFromURL(sceneUrl);
} catch (error) {
  const copy = cesdk.i18n.localizedEngineErrorMessage(error);
  showToast(copy?.message ?? copy?.description ?? 'Something went wrong.');
}

Signature#

localizedEngineErrorMessage(error: unknown): EngineErrorMessage