Search
Loading...
Skip to content

Localization

Translate and customize the CE.SDK editor interface for different languages using the built-in I18n API.

Localization interface showing language selection

10 mins
estimated time
Download
StackBlitz
GitHub

CE.SDK includes a localization system that lets you translate the editor interface, add custom languages, and white-label UI text. The I18n API manages translations programmatically at runtime, enabling you to switch languages dynamically and customize terminology for your brand.

This guide covers setting locales, adding translations, discovering available languages, white-labeling with custom terminology, and loading external translation files.

Default Languages and System Overview#

CE.SDK ships with English (en) and German (de) translations. The system falls back to English when translations are missing, ensuring the UI always displays text. When you add custom translations using setTranslations(), they override the built-in defaults for the same keys, while all other keys continue using CE.SDK’s standard translations.

During development, missing translation keys are logged to the console to help identify gaps in your translations.

Programmatic Localization#

We manage all localization using the cesdk.i18n API after initializing CreativeEditorSDK. The I18n API provides methods for setting languages, adding translations, and managing locales at runtime.

    // Load default and demo asset sources
    await cesdk.addDefaultAssetSources();
    await cesdk.addDemoAssetSources({
      sceneMode: 'Design',
      withUploadAssetSources: true
    });


    // Create a design scene
    await cesdk.createDesignScene();

Getting the Current Locale#

We use cesdk.i18n.getLocale() to retrieve the currently active locale. The method returns the locale code (e.g., 'en', 'de') or the fallback locale if none is explicitly set.

// Get the currently active locale
const currentLocale = cesdk.i18n.getLocale();
console.log('Current locale:', currentLocale);
// Output: "en" (default fallback locale)

Setting the Initial Locale#

We use cesdk.i18n.setLocale() to switch the active language. The UI updates immediately to display text in the specified locale.

// Switch to German locale
cesdk.i18n.setLocale('de');
console.log('Switched to locale:', cesdk.i18n.getLocale());
// The UI will now display in German

Discovering Available Locales#

We use cesdk.i18n.listLocales() to get an array of all loaded locales. The method supports optional wildcard matching using the matcher parameter to find locale variants.

    // List all available locales
    const allLocales = cesdk.i18n.listLocales();
    console.log('Available locales:', allLocales);
    // Output: ["en", "de"] (default English and German)


    // Find English variants using wildcard
    const englishLocales = cesdk.i18n.listLocales({ matcher: 'en*' });
    console.log('English locales:', englishLocales);

Adding Custom Translations#

We use cesdk.i18n.setTranslations() to add new languages or override existing translations. The structure requires the locale as the key with a nested translation object. We only need to provide keys we want to change—the rest fall back to defaults.

    // Add French translations
    cesdk.i18n.setTranslations({
      fr: {
        'common.save': 'Enregistrer',
        'common.cancel': 'Annuler',
        'common.back': 'Retour',
        'meta.currentLanguage': 'Français'
      }
    });


    // Switch to French
    cesdk.i18n.setLocale('fr');
    console.log('Switched to French locale');

Overriding Specific Labels#

We can override individual UI labels while keeping the rest of the default translations. This is useful for adjusting specific terminology without replacing entire translation sets.

// Override specific labels for English while keeping defaults
cesdk.i18n.setTranslations({
  en: {
    'common.save': 'Save Design',
    'common.export': 'Download'
  }
});

Retrieving Translations#

We use cesdk.i18n.getTranslations() to retrieve loaded translations for specific locales or all available translations. This is useful for debugging or exporting translation data.

    // Retrieve translations for specific locales
    const frenchTranslations = cesdk.i18n.getTranslations(['fr']);
    console.log('French translations:', frenchTranslations);


    // Get all translations
    const allTranslations = cesdk.i18n.getTranslations();
    console.log('All translations loaded:', Object.keys(allTranslations));

Translating Keys Programmatically#

We use cesdk.i18n.translate() to translate custom keys in our own UI elements. The method accepts a single key string or array of keys for fallback behavior. When an array is provided, the first key with a translation is used.

    // Translate custom keys programmatically
    const saveLabel = cesdk.i18n.translate('common.save');
    console.log('Save label:', saveLabel);


    // Use fallback keys
    const actionLabel = cesdk.i18n.translate(['custom.action', 'common.save']);
    console.log('Action label with fallback:', actionLabel);

Dynamic Language Switching#

We can build user-facing language selectors and switch languages at runtime without reloading the editor. We use cesdk.i18n.listLocales() to populate selector options and cesdk.i18n.setLocale() to switch languages.

    // Build language selector data
    const availableLocales = cesdk.i18n.listLocales();
    console.log('Building language selector with locales:', availableLocales);


    // Simulate dynamic language switching
    const switchLanguage = (locale: string) => {
      cesdk.i18n.setLocale(locale);
      console.log(`Switched to ${locale}`);
    };


    // Example: Switch between languages
    switchLanguage('en');
    switchLanguage('de');
    switchLanguage('fr');

White-labeling and Custom Terminology#

We can override specific UI labels for brand consistency while maintaining default translations for everything else. We use partial translation objects to change only targeted labels across multiple locales.

// White-label with custom terminology across multiple locales
cesdk.i18n.setTranslations({
  en: {
    'action.save': 'Publish Design',
    'action.export': 'Download Design',
    'panel.adjustments.title': 'Enhance'
  },
  de: {
    'action.save': 'Design Veröffentlichen',
    'action.export': 'Design Herunterladen',
    'panel.adjustments.title': 'Verbessern'
  }
});

Complete Language Addition#

We add support for new languages by providing translation objects with UI keys. We can provide a complete translation set or accept English fallbacks for missing keys. The example project demonstrates adding Italian with 100+ translations covering the navigation bar, dock, properties, and adjustments—see browser.ts for the complete implementation.

Loading External Translation Files#

We can load translation JSON files from external sources at runtime using fetch() and cesdk.i18n.setTranslations(). This is useful for loading translations from CDN or backend services.

    // Simulate loading translations from external source
    const loadExternalTranslations = async () => {
      // In a real application, you would fetch from a server:
      // const response = await fetch('/api/translations/es.json');
      // const translations = await response.json();


      // Simulate external Spanish translations
      const externalTranslations = {
        es: {
          'common.save': 'Guardar',
          'common.cancel': 'Cancelar',
          'common.back': 'Volver',
          'meta.currentLanguage': 'Español'
        }
      };


      cesdk.i18n.setTranslations(externalTranslations);
      console.log('Loaded external Spanish translations');
    };


    await loadExternalTranslations();

Troubleshooting#

Missing Translation Keys#

In development mode, missing keys are logged to the console with trace information. Missing keys fall back to the key string itself or English translation. Check window.missingKeys set for debugging.

Locale Not Loading#

Verify translations are correctly added with cesdk.i18n.setTranslations() before calling cesdk.i18n.setLocale(). Use cesdk.i18n.listLocales() to confirm the locale is loaded.

Fallback Behavior#

The system falls back to English (en) for missing translations. The fallback locale cannot be changed. Ensure critical UI elements have English translations as a safety net.

API Reference#

MethodPurpose
cesdk.i18n.getLocale()Get currently active locale string
cesdk.i18n.setLocale(locale)Set active locale for UI
cesdk.i18n.listLocales(options?)List all loaded locales with filtering
cesdk.i18n.setTranslations(definition)Add or override translations for locales
cesdk.i18n.getTranslations(locales?)Retrieve translations for specific locals
cesdk.i18n.translate(key)Translate a key to current locale

Next Steps#