Widget locales

  • This documentation is for the version 3.6.0 of the widget. If you're looking for the widget v2 docs, check here.

Uploadcare Widget supports a good number of locales.

There currently are:

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

Adding a locale

There is a chance your locale 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,

UPLOADCARE_LOCALE = 'en';
UPLOADCARE_LOCALE_TRANSLATIONS = {
  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. Notice, we used the snippet above to override two items in the original 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 widget locale is provided with its [pluralization rules] 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.

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

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.