Translations (i18n)

Add multi-language support and customize all text labels in the editor.

Setting the Active Language

Imigi supports full internationalization out of the box. To change the editor's display language, set the activeLanguage option during initialization. The default language is English ('en').

import { Imigi } from 'imigi';

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  activeLanguage: 'es',
});

Providing Custom Translations

To supply your own translations, pass a languages object in the configuration. Each key in the object is a language code, and its value is an object mapping translation keys to translated strings.

const editor = await Imigi.init({
  selector: '#editor',
  activeLanguage: 'es',
  languages: {
    es: {
      // Navigation
      'nav.filter': 'Filtros',
      'nav.crop': 'Recortar',
      'nav.draw': 'Dibujar',
      'nav.text': 'Texto',
      'nav.shapes': 'Formas',
      'nav.stickers': 'Stickers',
      'nav.frame': 'Marco',
      'nav.resize': 'Redimensionar',
      'nav.finetune': 'Ajustes',
      'nav.fill': 'Relleno',
      'nav.corners': 'Esquinas',
      'nav.redact': 'Censurar',

      // Toolbar
      'toolbar.save': 'Guardar',
      'toolbar.close': 'Cerrar',
      'toolbar.undo': 'Deshacer',
      'toolbar.redo': 'Rehacer',
      'toolbar.apply': 'Aplicar',
      'toolbar.cancel': 'Cancelar',

      // Messages
      'msg.loading': 'Cargando...',
      'msg.saving': 'Guardando...',
      'msg.error': 'Ocurrió un error',
      'msg.unsavedChanges': 'Tienes cambios sin guardar',
      // ... more keys
    },
  },
});

Translation Keys Reference

Below is the complete table of all available translation keys organized by category. Use these keys in your languages object to translate every label, button, tooltip, and message in the editor.

Navigation Keys

These keys control the labels shown in the main tool navigation bar.

Key	Default (English)	Description
nav.filter	Filters	Filter tool nav label
nav.crop	Crop	Crop tool nav label
nav.draw	Draw	Draw tool nav label
nav.text	Text	Text tool nav label
nav.shapes	Shapes	Shapes tool nav label
nav.stickers	Stickers	Stickers tool nav label
nav.frame	Frame	Frame tool nav label
nav.resize	Resize	Resize tool nav label
nav.finetune	Adjust	Finetune tool nav label
nav.fill	Fill	Fill tool nav label
nav.corners	Corners	Corners tool nav label
nav.redact	Redact	Redact tool nav label

Toolbar Keys

These keys control the labels and tooltips for the main toolbar buttons.

Key	Default	Description
toolbar.save	Save	Save button label
toolbar.close	Close	Close button label
toolbar.undo	Undo	Undo button tooltip
toolbar.redo	Redo	Redo button tooltip
toolbar.apply	Apply	Apply changes button
toolbar.cancel	Cancel	Cancel changes button
toolbar.zoomIn	Zoom In	Zoom in tooltip
toolbar.zoomOut	Zoom Out	Zoom out tooltip
toolbar.resetZoom	Reset Zoom	Reset zoom tooltip

Tool-specific Keys

Each tool has its own set of translation keys for labels, options, and presets displayed within the tool panel.

Filter Keys

Key	Default	Description
filter.none	None	No filter option
filter.grayscale	Grayscale	Grayscale filter label
filter.sepia	Sepia	Sepia filter label
filter.invert	Invert	Invert filter label
filter.vintage	Vintage	Vintage filter label
filter.polaroid	Polaroid	Polaroid filter label
filter.blackWhite	Black & White	B&W filter label
filter.sharpen	Sharpen	Sharpen filter label
filter.blur	Blur	Blur filter label
filter.emboss	Emboss	Emboss filter label

Crop Keys

Key	Default	Description
crop.original	Original	Original ratio preset
crop.free	Free	Free-form crop
crop.square	Square	1:1 aspect ratio
crop.landscape	Landscape	16:9 aspect ratio
crop.portrait	Portrait	9:16 aspect ratio
crop.flipX	Flip X	Horizontal flip label
crop.flipY	Flip Y	Vertical flip label
crop.rotate	Rotate	Rotation label

Draw Keys

Key	Default	Description
draw.pen	Pen	Pen brush type
draw.pencil	Pencil	Pencil brush type
draw.eraser	Eraser	Eraser tool
draw.size	Size	Brush size label
draw.color	Color	Brush color label
draw.opacity	Opacity	Brush opacity label

Text Keys

Key	Default	Description
text.addText	Add Text	Add text button
text.font	Font	Font selector label
text.size	Size	Font size label
text.color	Color	Text color label
text.bold	Bold	Bold toggle label
text.italic	Italic	Italic toggle label
text.underline	Underline	Underline toggle label
text.align	Align	Text alignment label
text.lineHeight	Line Height	Line height label
text.letterSpacing	Spacing	Letter spacing label

Finetune Keys

Key	Default	Description
finetune.brightness	Brightness	Brightness slider
finetune.contrast	Contrast	Contrast slider
finetune.saturation	Saturation	Saturation slider
finetune.exposure	Exposure	Exposure slider
finetune.temperature	Temperature	Temperature slider
finetune.hue	Hue	Hue slider
finetune.vibrance	Vibrance	Vibrance slider

Dialog Keys

These keys are used in dialog windows and modal prompts throughout the editor.

Key	Default	Description
dialog.newImage	New Image	New image dialog title
dialog.openImage	Open Image	Open image label
dialog.blankCanvas	Blank Canvas	Blank canvas option
dialog.width	Width	Width label
dialog.height	Height	Height label

Message Keys

These keys control status messages, loading indicators, and user-facing notifications.

Key	Default	Description
msg.loading	Loading...	Loading indicator
msg.saving	Saving...	Saving indicator
msg.error	An error occurred	Generic error message
msg.unsavedChanges	You have unsaved changes	Unsaved changes warning

Adding a Complete Language

For production use, it is recommended to define all translation keys for a language in a dedicated file. Below is a full example of adding Spanish translations.

Spanish (es)

export const spanishTranslations = {
  // Navigation
  'nav.filter': 'Filtros',
  'nav.crop': 'Recortar',
  'nav.draw': 'Dibujar',
  'nav.text': 'Texto',
  'nav.shapes': 'Formas',
  'nav.stickers': 'Stickers',
  'nav.frame': 'Marco',
  'nav.resize': 'Redimensionar',
  'nav.finetune': 'Ajustes',
  'nav.fill': 'Relleno',
  'nav.corners': 'Esquinas',
  'nav.redact': 'Censurar',

  // Toolbar
  'toolbar.save': 'Guardar',
  'toolbar.close': 'Cerrar',
  'toolbar.undo': 'Deshacer',
  'toolbar.redo': 'Rehacer',
  'toolbar.apply': 'Aplicar',
  'toolbar.cancel': 'Cancelar',
  'toolbar.zoomIn': 'Acercar',
  'toolbar.zoomOut': 'Alejar',
  'toolbar.resetZoom': 'Restablecer zoom',

  // Dialogs
  'dialog.newImage': 'Nueva imagen',
  'dialog.openImage': 'Abrir imagen',
  'dialog.blankCanvas': 'Lienzo en blanco',
  'dialog.width': 'Ancho',
  'dialog.height': 'Alto',

  // Messages
  'msg.loading': 'Cargando...',
  'msg.saving': 'Guardando...',
  'msg.error': 'Ocurrió un error',
  'msg.unsavedChanges': 'Tienes cambios sin guardar',
};

import { Imigi } from 'imigi';
import { spanishTranslations } from './translations/es';

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  activeLanguage: 'es',
  languages: {
    es: spanishTranslations,
  },
});

French (fr)

export const frenchTranslations = {
  // Navigation
  'nav.filter': 'Filtres',
  'nav.crop': 'Recadrer',
  'nav.draw': 'Dessiner',
  'nav.text': 'Texte',
  'nav.shapes': 'Formes',
  'nav.stickers': 'Autocollants',
  'nav.frame': 'Cadre',
  'nav.resize': 'Redimensionner',
  'nav.finetune': 'Réglages',
  'nav.fill': 'Remplissage',
  'nav.corners': 'Coins',
  'nav.redact': 'Censurer',

  // Toolbar
  'toolbar.save': 'Enregistrer',
  'toolbar.close': 'Fermer',
  'toolbar.undo': 'Annuler',
  'toolbar.redo': 'Rétablir',
  'toolbar.apply': 'Appliquer',
  'toolbar.cancel': 'Annuler',
  'toolbar.zoomIn': 'Zoom avant',
  'toolbar.zoomOut': 'Zoom arrière',
  'toolbar.resetZoom': 'Réinitialiser le zoom',

  // Messages
  'msg.loading': 'Chargement...',
  'msg.saving': 'Enregistrement...',
  'msg.error': 'Une erreur est survenue',
  'msg.unsavedChanges': 'Vous avez des modifications non enregistrées',
};

German (de)

export const germanTranslations = {
  // Navigation
  'nav.filter': 'Filter',
  'nav.crop': 'Zuschneiden',
  'nav.draw': 'Zeichnen',
  'nav.text': 'Text',
  'nav.shapes': 'Formen',
  'nav.stickers': 'Aufkleber',
  'nav.frame': 'Rahmen',
  'nav.resize': 'Größe ändern',
  'nav.finetune': 'Feineinstellung',
  'nav.fill': 'Füllung',
  'nav.corners': 'Ecken',
  'nav.redact': 'Schwärzen',

  // Toolbar
  'toolbar.save': 'Speichern',
  'toolbar.close': 'Schließen',
  'toolbar.undo': 'Rückgängig',
  'toolbar.redo': 'Wiederholen',
  'toolbar.apply': 'Anwenden',
  'toolbar.cancel': 'Abbrechen',
  'toolbar.zoomIn': 'Vergrößern',
  'toolbar.zoomOut': 'Verkleinern',
  'toolbar.resetZoom': 'Zoom zurücksetzen',

  // Messages
  'msg.loading': 'Laden...',
  'msg.saving': 'Speichern...',
  'msg.error': 'Ein Fehler ist aufgetreten',
  'msg.unsavedChanges': 'Sie haben ungespeicherte Änderungen',
};

RTL (Right-to-Left) Support

Imigi supports right-to-left (RTL) languages such as Arabic and Hebrew. When you set the active language to an RTL locale, the editor automatically mirrors the layout, including the toolbar, navigation, and panel positions.

To enable RTL, set the dir property in your language configuration:

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  activeLanguage: 'ar',
  languages: {
    ar: {
      dir: 'rtl',
      'nav.filter': '\u0641\u0644\u0627\u062a\u0631',
      'nav.crop': '\u0642\u0635',
      'nav.draw': '\u0631\u0633\u0645',
      'nav.text': '\u0646\u0635',
      'toolbar.save': '\u062d\u0641\u0638',
      'toolbar.close': '\u0625\u063a\u0644\u0627\u0642',
      'toolbar.undo': '\u062a\u0631\u0627\u062c\u0639',
      'toolbar.redo': '\u0625\u0639\u0627\u062f\u0629',
      // ... more Arabic translations
    },
  },
});

The following elements are automatically mirrored in RTL mode:

• Navigation bar item order
• Toolbar button alignment (save/close swap sides)
• Panel slide direction
• Text alignment defaults (right-aligned instead of left)
• Slider and range input direction

Dynamic Language Switching

You can change the editor's language at runtime without reinitializing the editor. Use the setConfig() method to update the activeLanguage and provide the corresponding translations.

import { frenchTranslations } from './translations/fr';
import { germanTranslations } from './translations/de';

// Switch to French at runtime
editor.setConfig({
  activeLanguage: 'fr',
  languages: {
    fr: frenchTranslations,
  },
});

// Switch to German at runtime
editor.setConfig({
  activeLanguage: 'de',
  languages: {
    de: germanTranslations,
  },
});

// Switch back to English (built-in)
editor.setConfig({
  activeLanguage: 'en',
});

A common pattern is to build a language selector dropdown that triggers the switch:

const languageMap = {
  en: null,           // Built-in default
  es: spanishTranslations,
  fr: frenchTranslations,
  de: germanTranslations,
};

function switchLanguage(langCode) {
  const config = { activeLanguage: langCode };
  if (languageMap[langCode]) {
    config.languages = { [langCode]: languageMap[langCode] };
  }
  editor.setConfig(config);
}

// Wire up a <select> element
document.getElementById('lang-select')
  .addEventListener('change', (e) => switchLanguage(e.target.value));

Partial Translations

You do not need to translate every single key. Imigi supports partial translations -- any key that is not found in your custom language object will automatically fall back to the built-in English default.

This is useful when you want to quickly localize only the most visible parts of the editor (such as navigation and toolbar labels) while leaving less common strings in English.

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  activeLanguage: 'pt',
  languages: {
    pt: {
      // Only translate the most visible labels
      'toolbar.save': 'Salvar',
      'toolbar.close': 'Fechar',
      'toolbar.undo': 'Desfazer',
      'toolbar.redo': 'Refazer',
      'nav.filter': 'Filtros',
      'nav.crop': 'Cortar',
      // All other keys fall back to English
    },
  },
});

Extracting Translation Keys

Imigi provides a built-in CLI command to extract all translation keys used in the editor source code. This is useful for generating a template file that translators can fill in.

npm run extract-i18n

This command scans the Imigi source code and outputs a JSON file containing every translation key with its default English value:

{
  "nav.filter": "Filters",
  "nav.crop": "Crop",
  "nav.draw": "Draw",
  "nav.text": "Text",
  "toolbar.save": "Save",
  "toolbar.close": "Close",
  // ... all keys
}

Community Translations

The Imigi community maintains translations for several popular languages. You can find community-contributed translation files in the translations directory of the GitHub repository.

Available community translations include:

• Spanish (es) -- maintained by contributors
• French (fr) -- maintained by contributors
• German (de) -- maintained by contributors
• Portuguese (pt, pt-BR) -- maintained by contributors
• Japanese (ja) -- maintained by contributors
• Chinese Simplified (zh-CN) -- maintained by contributors
• Korean (ko) -- maintained by contributors
• Arabic (ar) -- maintained by contributors