Skip to main content
defineLocale allows you to add custom language translations or override existing locale definitions for File Uploader. It supports both synchronous and asynchronous (lazy-loaded) locale definitions.

​
Signature

function defineLocale(
  localeName: string,
  definitionOrResolver: LocaleDefinition | LocaleDefinitionResolver
): void
​
localeName
string
required
The locale identifier (e.g., ‘en’, ‘fr’, ‘es’, ‘de’)
​
definitionOrResolver
LocaleDefinition | LocaleDefinitionResolver
required
Either a locale definition object or a function that returns a Promise resolving to a locale definition

​
Types

type LocaleDefinition = {
  'locale-id': string;
  'upload-file': string;
  'choose-file': string;
  'drop-files-here': string;
  // ... and many more translation keys
};

type LocaleDefinitionResolver = () => Promise<LocaleDefinition>;

​
Usage

​
Synchronous Definition

Define a locale with an immediate object: 
import * as UC from '@uploadcare/file-uploader';

UC.defineLocale('es', {
  'locale-id': 'es',
  'upload-file': 'Subir archivo',
  'upload-files': 'Subir archivos',
  'choose-file': 'Elegir archivo',
  'choose-files': 'Elegir archivos',
  'drop-files-here': 'Suelta los archivos aquí',
  'select-file-source': 'Selecciona la fuente del archivo',
  upload: 'Subir',
  cancel: 'Cancelar',
  // ... more translations
});

​
Asynchronous Definition (Lazy Loading)

Define a locale with a function that loads translations on demand: 
import * as UC from '@uploadcare/file-uploader';

// Define locale with lazy loading
UC.defineLocale('fr', async () => {
  const translations = await import('./locales/fr.js');
  return translations.default;
});
This approach is useful for:
  • Code splitting - Load translations only when needed
  • Reducing bundle size - Don’t include all locales upfront
  • Dynamic loading - Fetch translations from a CDN or API

​
Using Built-in Locales

File Uploader includes 34 built-in locales. Import and define them as needed: 
import * as UC from '@uploadcare/file-uploader';
import fr from '@uploadcare/file-uploader/locales/fr';

UC.defineLocale('fr', fr);

​
Available Built-in Locales

File Uploader includes the following locale files in the src/locales/file-uploader/ directory:ar, az, ca, cs, da, de, el, en, 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, zh-TW

​
Activating a Locale

After defining a locale, activate it using the locale-name configuration option: 
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  locale-name="es"
></uc-config>
Or programmatically: 
const ctx = UC.PubSub.getCtx('my-uploader');
ctx.cfg.localeName = 'es';

​
Partial Overrides

You don’t need to provide all translation keys. The locale definition is merged with the English locale as a fallback: 
import * as UC from '@uploadcare/file-uploader';

// Only override specific keys
UC.defineLocale('en-custom', {
  'locale-id': 'en-custom',
  'upload-file': 'Upload Your File',
  'upload-files': 'Upload Your Files',
  // All other keys will use English defaults
});

​
Implementation Details

From the source code: 
import { default as en } from '../locales/file-uploader/en';

const localeRegistry: Map<string, LocaleDefinition> = new Map();
const localeResolvers: Map<string, LocaleDefinitionResolver> = new Map();

const defineLocaleSync = (localeName: string, definition: LocaleDefinition): LocaleDefinition => {
  if (localeRegistry.has(localeName)) {
    console.log(`Locale ${localeName} is already defined. Overwriting...`);
  }

  // Merge with English locale as fallback
  const locale: LocaleDefinition = { ...en, ...definition };
  localeRegistry.set(localeName, locale);

  return locale;
};

const defineLocaleAsync = (localeName: string, definitionResolver: LocaleDefinitionResolver): void => {
  localeResolvers.set(localeName, definitionResolver);
};

export const defineLocale = (
  localeName: string,
  definitionOrResolver: LocaleDefinition | LocaleDefinitionResolver,
): void => {
  if (typeof definitionOrResolver === 'function') {
    defineLocaleAsync(localeName, definitionOrResolver);
  } else {
    defineLocaleSync(localeName, definitionOrResolver);
  }
};

​
Complete Example

Here’s a complete example showing locale definition and usage: 
<!DOCTYPE html>
<html lang="es">
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@1/web/uc-file-uploader-regular.min.css" />
</head>
<body>
  <uc-config
    ctx-name="my-uploader"
    pubkey="YOUR_PUBLIC_KEY"
    locale-name="es"
  ></uc-config>
  
  <uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>

  <script type="module">
    import * as UC from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@1/web/file-uploader.min.js';

    UC.defineComponents(UC);

    // Define Spanish locale
    UC.defineLocale('es', {
      'locale-id': 'es',
      'upload-file': 'Subir archivo',
      'upload-files': 'Subir archivos',
      'choose-file': 'Elegir archivo',
      'choose-files': 'Elegir archivos',
      'drop-files-here': 'Suelta los archivos aquí',
      'select-file-source': 'Selecciona la fuente del archivo',
      'upload': 'Subir',
      'cancel': 'Cancelar',
      'clear': 'Limpiar',
      'done': 'Hecho',
      'remove-from-list': 'Eliminar',
      // Add more translations as needed
    });
  </script>
</body>
</html>

​
Dynamic Locale Switching

You can switch locales at runtime: 
import * as UC from '@uploadcare/file-uploader';

// Define multiple locales
UC.defineLocale('en', enLocale);
UC.defineLocale('es', esLocale);
UC.defineLocale('fr', frLocale);

// Switch locale dynamically
const ctx = UC.PubSub.getCtx('my-uploader');

// Change to Spanish
ctx.cfg.localeName = 'es';

// Change to French
ctx.cfg.localeName = 'fr';

​
Locale Override via Configuration

For quick overrides without defining a new locale, use locale-definition-override: 
const ctx = UC.PubSub.getCtx('my-uploader');

ctx.cfg.localeDefinitionOverride = {
  en: {
    'upload-file': 'Custom Upload Text',
    'choose-file': 'Pick a File'
  }
};

​
Common Translation Keys

Here are some of the most commonly used translation keys:
KeyPurposeExample (English)
upload-fileSingle file upload button”Upload file”
upload-filesMultiple files upload button”Upload files”
choose-fileSingle file chooser”Choose file”
choose-filesMultiple files chooser”Choose files”
drop-files-hereDrop zone text”Drop files here”
uploadUpload action”Upload”
cancelCancel action”Cancel”
doneCompletion action”Done”
remove-from-listRemove file action”Remove”
src-type-localLocal file source”From device”
src-type-cameraCamera source”Camera”
src-type-from-urlURL source”From link”
For a complete list of translation keys, refer to the English locale file in the source code.

​
Best Practices

  1. Use lazy loading for locales to reduce initial bundle size
  2. Include locale-id in your locale definition
  3. Test all user flows after adding translations
  4. Maintain consistency in terminology across your locale
  5. Consider pluralization - some keys include plural forms (e.g., file__one, file__other)
  6. Watch for updates - New File Uploader versions may add new translation keys

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us