AI Image Editor localization

The editor ships English eagerly and lazy-loads 34 other locales. Set the active language with localeName; the editor loads that locale’s built-in strings on demand. Customize individual strings with localeDefinitionOverride, which is keyed by locale name and takes the same shape as the File Uploader’s config. As a plugin, both follow the uploader’s localeName / localeDefinitionOverride automatically.

1 // Standalone: pick the language and override specific strings per locale.
2 editor.localeName = 'de';
3 editor.localeDefinitionOverride = {
4   en: { 'ai-image-editor-cancel': 'Dismiss' },
5   de: { 'ai-image-editor-generate-btn': 'Los!' },
6 };

Supported locales: en ar az ca cs da de el es et fi fr he hy is it ja ka kk ko lv nb nl pl pt ro ru sk sr sv tr uk vi zh (and zh-TW). Browse the translations on GitHub: the base en.ts and the other locales.

Available strings

These are the keys you can override, shown with their English defaults (the base locale, enLocale). Every locale provides this core set:

1 {
2   'ai-image-editor-source-label': 'Generate image',       // uploader source button
3   'ai-image-editor-file-action-label': 'AI Edit',         // uploader file action
4   'ai-image-editor-generate-title': 'Generate image',     // header, generate mode
5   'ai-image-editor-edit-title': 'Edit image',             // header, edit mode
6   'ai-image-editor-generate-placeholder': 'Create image...',
7   'ai-image-editor-edit-placeholder': 'Edit image...',
8   'ai-image-editor-cancel': 'Cancel',
9   'ai-image-editor-generate-btn': 'Generate',
10   'ai-image-editor-done-btn': 'Done',
11   'ai-image-editor-start-over': 'Start over',
12   'ai-image-editor-history-title': 'Recent prompts',
13   'ai-image-editor-busy': 'Generating…',                  // progress label
14   'ai-image-editor-error': 'Something went wrong. Try again.', // generic error
15   'ai-image-editor-fullscreen': 'View fullscreen',
16   'ai-image-editor-exit-fullscreen': 'Exit fullscreen',
17   'ai-image-editor-aspect-ratio-aria': 'Pick aspect ratio',
18   'ai-image-editor-aspect-original': 'Original',
19   'ai-image-editor-aspect-square': 'Square',
20   'ai-image-editor-aspect-tall': 'Tall',
21   'ai-image-editor-aspect-wide': 'Wide',
22   'ai-image-editor-aspect-portrait': 'Portrait',
23   'ai-image-editor-aspect-landscape': 'Landscape',
24   'ai-image-editor-aspect-vertical': 'Vertical',
25   'ai-image-editor-aspect-widescreen': 'Widescreen',
26 }

enLocale is exported if you need to look strings up outside the element:

1 import { enLocale } from '@uploadcare/ai-image-editor';
2 
3 enLocale['ai-image-editor-generate-btn']; // 'Generate'

Error messages

When a generation or edit fails, the editor maps the backend error_code to an ai-image-editor-error-<code> key and shows that message. If no key matches the code (or you haven’t translated it), it falls back to the generic ai-image-editor-error. These per-code keys are optional in every locale, so translate only the ones you care about and the rest fall back gracefully:

1 editor.localeDefinitionOverride = {
2   de: {
3     'ai-image-editor-error': 'Etwas ist schiefgelaufen. Bitte erneut versuchen.',
4     'ai-image-editor-error-content_moderated': 'Diese Anfrage wurde blockiert.',
5   },
6 };

Platform validation. The request was rejected before generation started.

Key	When it fires
`ai-image-editor-error-invalid_request`	The request was malformed or rejected.
`ai-image-editor-error-invalid_source`	The source image couldn’t be read or decoded.
`ai-image-editor-error-source_not_found`	The source image (by UUID) doesn’t exist.
`ai-image-editor-error-source_not_image`	The source file isn’t an image.
`ai-image-editor-error-source_url_unavailable`	The source image couldn’t be downloaded.
`ai-image-editor-error-invalid_aspect_ratio`	The requested aspect ratio isn’t supported.
`ai-image-editor-error-canvas_too_large`	The result exceeds the 4-megapixel limit.
`ai-image-editor-error-canvas_dimension_too_small`	A side is under the 256px minimum.
`ai-image-editor-error-source_extends_beyond_canvas`	The source doesn’t fit the target canvas.
`ai-image-editor-error-derivative_disabled`	AI generation isn’t enabled for the account.
`ai-image-editor-error-job_id_required`	A job id was missing (internal).
`ai-image-editor-error-job_not_found`	The generation job expired or doesn’t exist.
`ai-image-editor-error-ProjectPublicKeyInvalidError`	The `pubkey` isn’t a valid project key.

AI gateway. The job failed while the model ran.

Key	When it fires
`ai-image-editor-error-content_moderated`	Blocked by content moderation.
`ai-image-editor-error-provider_unavailable`	The upstream image service is overloaded.
`ai-image-editor-error-generation_timeout`	The job took too long and timed out.
`ai-image-editor-error-invalid_input`	The model rejected the inputs or settings.
`ai-image-editor-error-RequestThrottledError`	Too many requests: rate limited.

Upload pipeline. The result couldn’t be saved.

Key	When it fires
`ai-image-editor-error-DownloadFileHTTPClientError`	Couldn’t retrieve the generated image.
`ai-image-editor-error-DownloadFileNotFoundError`	The generated image wasn’t found.
`ai-image-editor-error-DownloadFileTaskFailedError`	Couldn’t save the generated image.