Widget UI Translations

  • This is for the version 3.x of the widget. If you're looking for the widget v2 docs, check here
  • Here’s how you migrate from v2 to v3.

Uploadcare Widget is highly customizable and implements UI translations and custom pluralization rules. With 30 locales, you can make your app instantly adapt to user languages.

There currently are: ar az ca cs da de el en es et fr he it ja ko lv nb nl pl pt ro ru sk sr sv tr uk vi zhTW zh

You can either set an existing locale or add a custom one along with its pluralization rules.

Adding a locale

There is a chance the locale you need is not available in the widget yet. In the case, it is worth contributing a new one. That is done by forking the main widget repo and adding a new localization file to this list.

Another option is overriding specific locale items by altering your global widget configuration,

  buttons: {
    cancel: 'Cancel',
    remove: 'Remove',
    choose: {
      files: {
        one: 'Choose a file',
        other: 'Pick files'
      images: {
        one: 'Choose an image',
        other: 'Load images'

Compare the structure above with the default English locale and you will notice we used the snippet above to override two items in the default localization.

If a string item is missing in a locale you selected, and there is no override for it, English is a fallback. In fact, our English locale usually contains the most extensive set of items for latest widget versions.

Pluralization rules

Pluralization rules deal with enumerabilty, it is when something can be counted. Widget locale items hold some quantitative values, and you might want to override how those work. In the English locale, for instance, you can find things like "1 file" and "3 files". Such behavior will require a special structure. You can find one of those under the file: key in the locale file.

Strings holding quantitative values are based on the output of a pluralization function. You pass an input number into a function, and it outputs a proper subkey related to your input.

function pluralize(number) {
  // do something
  return 'some_subkey';

There are two subkeys for the English localization: one and other. However, it can get more complex with other languages. For example, take a look at file: subkeys for the Russian locale. We use the %1 sequence to format numbers into pluralized strings.

Each locale we provide with the widget is supplied with its Unicode-based pluralization rules. If you wish to override those, you can define a custom pluralization function and assign it to the UPLOADCARE_LOCALE_PLURALIZE variable.

The following setting makes the widget use the message under the some subkey for input numbers from 2 to 10.

  file: {
    one: 'Only one file! :(',
    some: 'Only %1 files. Upload more.',
    many: '%1 files!! That\'s a lot.'
  if (n === 1) return 'one';
  if (n > 1 && n <= 10) return 'some';
  return 'many';