@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/user-interface/localization.md

@@ -1,633 +0,0 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
-
-**Navigation:** [Guides](./guides.md) > [User Interface](./user-interface.md) > [Localization](./user-interface/localization.md)
-
----
-
-Translate and customize the CE.SDK editor interface for different languages using the built-in I18n API.
-
-![Localization interface showing language selection](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
-> **Reading time:** 10 minutes
->
-> **Resources:**
->
-> - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
-> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-user-interface-localization-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-user-interface-localization-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-user-interface-localization-browser/)
-
-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.
-
-```typescript file=@cesdk_web_examples/guides-user-interface-localization-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-
-import {
-  BlurAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
-
-class LocalizationExample implements EditorPlugin {
-  name = packageJson.name;
-  version = packageJson.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
-
-    await cesdk.addPlugin(new DesignEditorConfig());
-
-    // Add asset source plugins
-    await cesdk.addPlugin(new BlurAssetSource());
-    await cesdk.addPlugin(new ColorPaletteAssetSource());
-    await cesdk.addPlugin(new CropPresetsAssetSource());
-    await cesdk.addPlugin(
-      new UploadAssetSources({ include: ['ly.img.image.upload'] })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: [
-          'ly.img.templates.blank.*',
-          'ly.img.templates.presentation.*',
-          'ly.img.templates.print.*',
-          'ly.img.templates.social.*',
-          'ly.img.image.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new EffectsAssetSource());
-    await cesdk.addPlugin(new FiltersAssetSource());
-    await cesdk.addPlugin(new PagePresetsAssetSource());
-    await cesdk.addPlugin(new StickerAssetSource());
-    await cesdk.addPlugin(new TextAssetSource());
-    await cesdk.addPlugin(new TextComponentAssetSource());
-    await cesdk.addPlugin(new TypefaceAssetSource());
-    await cesdk.addPlugin(new VectorShapeAssetSource());
-
-    await cesdk.actions.run('scene.create', {
-      page: { width: 800, height: 600, unit: 'Pixel' }
-    });
-
-    const engine = cesdk.engine;
-
-    // Get the currently active locale
-    const currentLocale = cesdk.i18n.getLocale();
-    console.log('Current locale:', currentLocale);
-    // Output: "en" (default fallback locale)
-
-    // 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);
-
-    // Switch to German locale
-    cesdk.i18n.setLocale('de');
-    console.log('Switched to locale:', cesdk.i18n.getLocale());
-    // The UI will now display in German
-
-    // 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');
-
-    // Override specific labels for English while keeping defaults
-    cesdk.i18n.setTranslations({
-      en: {
-        'common.save': 'Save Design',
-        'common.export': 'Download'
-      }
-    });
-
-    // 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'
-      }
-    });
-
-    // 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));
-
-    // 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);
-
-    // 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');
-
-    // 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();
-
-    // Add Italian with comprehensive translations for a fully localized UI
-    cesdk.i18n.setTranslations({
-      it: {
-        // === NAVIGATION BAR (Top Bar) ===
-
-        // Undo/Redo
-        'common.undo': 'Annulla',
-        'common.redo': 'Ripeti',
-        'component.undo.undo': 'Annulla',
-        'component.undo.redo': 'Ripeti',
-
-        // File Operations
-        'common.save': 'Salva',
-        'common.export': 'Esporta',
-        'common.download': 'Scarica',
-        'component.fileOperation.save': 'Salva',
-        'component.fileOperation.exportImage': 'Esporta Immagini',
-        'component.fileOperation.exportPDF': 'Esporta PDF',
-        'component.fileOperation.exportVideo': 'Esporta Video',
-        'component.fileOperation.exportScene': 'Esporta Design',
-        'component.fileOperation.importScene': 'Importa Design',
-        'component.fileOperation.more': 'Mostra altre opzioni',
-
-        // Zoom Controls
-        'component.zoom.in': 'Aumenta Zoom',
-        'component.zoom.out': 'Diminuisci Zoom',
-        'component.zoom.fitPage': 'Adatta Pagina',
-        'component.zoom.fitSelection': 'Adatta Selezione',
-        'component.zoom.autoFit': 'Adattamento Automatico',
-        'component.zoom.options': 'Vedi altre opzioni di zoom',
-
-        // Top Bar Controls
-        'component.topbar.back': 'Indietro',
-        'component.topbar.close': 'Chiudi',
-        'common.close': 'Chiudi',
-        'component.settings.toggle': 'Personalizza Editor',
-        'component.settings.toggle.description':
-          "Apri impostazioni per personalizzare l'editor",
-
-        // === DOCK (Left Sidebar) ===
-
-        // Library/Asset Panel
-        'component.library': 'Libreria',
-        'component.library.elements': 'Elementi',
-        'component.canvas.openLibrary': 'Aggiungi Elementi',
-        'component.library.addFile': 'Aggiungi File',
-        'component.library.searchPlaceholder': 'Cerca …',
-        'component.library.clearSearch': 'Cancella ricerca',
-        'component.library.noItems': 'Nessun Elemento',
-        'component.library.loading': 'Caricamento …',
-
-        // Library Categories
-        'libraries.ly.img.image.label': 'Immagini',
-        'libraries.ly.img.image.upload.label': 'Caricamenti Immagini',
-        'libraries.ly.img.video.label': 'Video',
-        'libraries.ly.img.video.upload.label': 'Caricamenti Video',
-        'libraries.ly.img.audio.label': 'Audio',
-        'libraries.ly.img.audio.upload.label': 'Caricamenti Audio',
-        'libraries.ly.img.text.label': 'Testo',
-        'libraries.ly.img.text.title.label': 'Titolo',
-        'libraries.ly.img.text.headline.label': 'Intestazione',
-        'libraries.ly.img.text.paragraph.label': 'Paragrafo',
-        'libraries.ly.img.vector.shape.label': 'Forme',
-        'libraries.ly.img.sticker.label': 'Adesivi',
-        'libraries.ly.img.upload.label': 'Caricamenti',
-        'libraries.ly.img.template.label': 'Modelli',
-        'libraries.unsplash.label': 'Unsplash',
-
-        // Inspector Panel
-        'component.inspectorBar': 'Barra Ispettore',
-        'action.showInspector': 'Mostra Ispettore',
-        'action.closeInspector': 'Chiudi Ispettore',
-        'component.propertyPopover.header': 'Proprietà',
-
-        // === COMMON ELEMENTS ===
-
-        // Basic Actions
-        'common.cancel': 'Annulla',
-        'common.back': 'Indietro',
-        'common.done': 'Fatto',
-        'common.apply': 'Applica',
-        'common.reset': 'Ripristina',
-        'common.delete': 'Elimina',
-        'common.duplicate': 'Duplica',
-        'common.add': 'Aggiungi',
-        'common.replace': 'Sostituisci',
-        'common.edit': 'Modifica',
-        'common.load': 'Carica',
-        'common.more': 'Altro',
-
-        // Canvas
-        'component.canvas': 'Area Editor',
-        'common.mode.design': 'Design',
-        'common.mode.preview': 'Anteprima',
-
-        // Properties & Adjustments
-        'common.properties': 'Proprietà',
-        'common.opacity': 'Opacità',
-        'common.fill': 'Riempimento',
-        'common.color': 'Colore',
-        'common.position': 'Posizione',
-        'common.size': 'Dimensione',
-        'common.rotation': 'Rotazione',
-        'common.transform': 'Trasforma',
-
-        // Adjustments
-        'input.adjustments': 'Regolazioni',
-        'property.adjustments.brightness': 'Luminosità',
-        'property.adjustments.contrast': 'Contrasto',
-        'property.adjustments.saturation': 'Saturazione',
-        'property.adjustments.exposure': 'Esposizione',
-        'property.adjustments.highlights': 'Luci',
-        'property.adjustments.shadows': 'Ombre',
-        'property.adjustments.temperature': 'Temperatura',
-        'property.adjustments.sharpness': 'Nitidezza',
-
-        // Blur & Effects
-        'input.blur': 'Sfocatura',
-        'input.effect': 'Effetto',
-        'input.filter': 'Filtro',
-        'component.assetSettings.blur': 'Sfocatura',
-        'component.assetSettings.effects': 'Effetti',
-        'component.assetSettings.filters': 'Filtri',
-        'component.assetSettings.adjustments': 'Regolazioni',
-
-        // Text Properties
-        'input.text.advanced': 'Avanzate',
-        'property.letterSpacing': 'Spaziatura Lettere',
-        'property.lineHeight': 'Altezza Riga',
-        'typography.typeface': 'Carattere',
-        'typography.size': 'Dimensione',
-        'typography.bold': 'Grassetto',
-        'typography.italic': 'Corsivo',
-
-        // Block Types
-        'block.image': 'Immagine',
-        'block.video': 'Video',
-        'block.audio': 'Audio',
-        'block.text': 'Testo',
-        'block.shape': 'Forma',
-        'block.sticker': 'Adesivo',
-        'block.group': 'Gruppo',
-        'block.page': 'Pagina',
-
-        // Actions
-        'action.align': 'Allinea',
-        'action.arrange': 'Disponi',
-        'action.group': 'Raggruppa',
-        'action.ungroup': 'Separa',
-        'common.lock': 'Blocca',
-        'common.unlock': 'Sblocca',
-
-        // Pages
-        'common.page': 'Pagina',
-        'action.page.add': 'Aggiungi Pagina',
-        'action.page.delete': 'Elimina Pagina',
-
-        // Metadata
-        'meta.currentLanguage': 'Italiano'
-      }
-    });
-
-    // Verify the new locale is available
-    console.log('Available after Italian:', cesdk.i18n.listLocales());
-
-    // Switch to Italian to display the fully translated UI
-    cesdk.i18n.setLocale('it');
-    console.log('UI now displaying in Italian');
-
-    // Add a sample image to the canvas for visual content
-    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
-    const image = await engine.block.addImage(imageUri, { x: 0, y: 0 });
-    engine.block.setWidth(image, 800);
-    engine.block.setHeight(image, 600);
-  }
-}
-
-export default LocalizationExample;
-```
-
-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.
-
-```typescript highlight-setup
-await cesdk.addPlugin(new DesignEditorConfig());
-
-// Add asset source plugins
-await cesdk.addPlugin(new BlurAssetSource());
-await cesdk.addPlugin(new ColorPaletteAssetSource());
-await cesdk.addPlugin(new CropPresetsAssetSource());
-await cesdk.addPlugin(
-  new UploadAssetSources({ include: ['ly.img.image.upload'] })
-);
-await cesdk.addPlugin(
-  new DemoAssetSources({
-    include: [
-      'ly.img.templates.blank.*',
-      'ly.img.templates.presentation.*',
-      'ly.img.templates.print.*',
-      'ly.img.templates.social.*',
-      'ly.img.image.*'
-    ]
-  })
-);
-await cesdk.addPlugin(new EffectsAssetSource());
-await cesdk.addPlugin(new FiltersAssetSource());
-await cesdk.addPlugin(new PagePresetsAssetSource());
-await cesdk.addPlugin(new StickerAssetSource());
-await cesdk.addPlugin(new TextAssetSource());
-await cesdk.addPlugin(new TextComponentAssetSource());
-await cesdk.addPlugin(new TypefaceAssetSource());
-await cesdk.addPlugin(new VectorShapeAssetSource());
-
-await cesdk.actions.run('scene.create', {
-  page: { width: 800, height: 600, unit: 'Pixel' }
-});
-```
-
-### 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.
-
-```typescript highlight-get-current-locale
-// 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.
-
-```typescript highlight-set-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.
-
-```typescript highlight-list-available-locales
-// 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.
-
-```typescript highlight-add-custom-translations
-// 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.
-
-```typescript highlight-partial-override
-// 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.
-
-```typescript highlight-get-translations
-// 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.
-
-```typescript highlight-translate-keys
-// 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.
-
-```typescript highlight-dynamic-switching
-// 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.
-
-```typescript highlight-white-labeling
-// 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.
-
-```typescript highlight-external-translations
-// 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
-
-| Method                                   | Purpose                                   |
-| ---------------------------------------- | ----------------------------------------- |
-| `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
-
-- [UI Customization](./user-interface/customization.md) — Customize editor components and layout
-- [Configuration](./configuration.md) — Explore editor configuration options
-- [Actions](./actions.md) — Handle user interactions and events
-- [Asset Library Customization](./import-media/asset-panel/customize.md) — Customize asset sources and library
-
----
-
-## More Resources
-
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
-- **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
-- **[Web Documentation](./js.md)** - Interactive documentation with examples
-- **[Support](mailto:support@img.ly)** - Contact IMG.LY support