File Uploader localization

The File Uploader localization support enables the customization of UI texts and translations. It supports pluralization and provides a way to create a tailored user experience by adapting the interface to various languages and preferences.

Let’s take a look at how the locale definition is described.

Locale definition

The locale definition is described as a plain JS object like this:

1
export default {
2
  'locale-id': 'en',
3
  'social-source-lang': 'en',
4
  'upload-file': 'Upload file',
5
  'file__one': 'file',
6
  'file__other': 'files',
7
  'header-uploading': 'Uploading {{count}} {{plural:file(count)}}',
8
}

Let’s break down the properties.

Locale id and social source lang

The first two properties aren’t localized strings themselves:

• locale-id - the Unicode locale identifier string. It’s used for pluralization rules. See MDN Intl documentation for more details.
• social-source-lang - the language code for social sources. It’s used to set the language for social sources like Facebook, Instagram, etc. The social sources aren’t a part of the File Uploader; they are loaded in the iframe, so the localization strings can’t be changed. The only available languages are: 'de', 'en', 'es', 'fi', 'fr', 'he', 'it', 'nl', 'pl', 'pt', 'ru', 'tr', 'uk', 'zh-TW', 'zh'

Localization strings

The other properties are localized strings. In the example below, we have:

• upload-file - the string for the upload button with the text Upload file.
• file__one - the string for the singular form of the word file with the value file.
• file__other - the string for the plural form of the word file with the value files.
• header-uploading - the string for the header during the uploading process with the value Uploading {{count}} {{plural:file(count)}}.

Pluralization

Plural forms are described as key__category, where the key is the base key, and the category is the plural category. The plural categories could be zero, one, few, many, and other. They are used to select the appropriate variant of the string based on the count of items. The allowed categories depend on the locale. You can find the list of plural categories for each locale in the CLDR Plural Rules documentation.

Some localization strings are parameterized. The parameters are enclosed in double curly braces {{ and }}. For example, {{count}} is a parameter that will be replaced with the number of files being uploaded. The {{plural:file(count)}} syntax is used to apply plural rules to the word file.

I.e. string Uploading {{count}} {{plural:file(count)}} will be rendered as Uploading 1 file or Uploading 5 files depending on the count.

You can find a whole English locale definition on GitHub.

Let’s take a look at localization API.

Method defineLocale

The defineLocale method is used to define a new locale within the File Uploader. It accepts the locale definition object or the async function that returns the locale definition object.

The defineLocale method has the following signature:

1
type LocaleDefinition = Record<string, string>;
2
type LocaleDefinitionResolver = () => Promise<LocaleDefinition>;
3
4
function defineLocale(localeName: string, locale: LocaleDefinition | LocaleDefinitionResolver): void;

Let’s break down the arguments:

• localeName is the internal locale name. It should be unique and match the locale-name option value.
• locale is the locale definition object or the async function that returns the locale definition object.

WARNING: The defineLocale method should be called before the defineComponents method or before the File Uploader components appear in the DOM.

Option locale-name

The locale-name option is used to set the locale name for the File Uploader components. It should match the locale name passed to the defineLocale method.

The locale-name option is optional. If it’s not set, the default English locale will be used.

It could be set as an attribute or DOM property on the uc-config component:

1
<uc-config
2
  ctx-name="my-uploader"
3
  pubkey="YOUR_PUBLIC_KEY"
4
  locale-name="pt"
5
></uc-config>
6
<!-- or -->
7
<script type="module">
8
  const config = document.querySelector('uc-config');
9
  config.localeName = 'pt';
10
</script>

Get YOUR_PUBLIC_KEY from API keys.

See the File Uploader options for more details.

Option localeDefinitionOverride

The localeDefinitionOverride option is used to override the specific locale definition. It should be set as a DOM property on the uc-config component. HTML attribute is not supported.

Here is the type definition:

1
type LocaleName = string;
2
type LocaleDefinition = Record<string, string>;
3
type LocaleDefinitionOverride = Record<LocaleName, LocaleDefinition>;

Here is how to use it:

1
<script type="module">
2
  const config = document.querySelector('uc-config');
3
  config.localeDefinitionOverride = {
4
    en: {
5
      'upload-file': 'Choose your documents',
6
    }
7
  };
8
</script>
9
10
<uc-config
11
  ctx-name="my-uploader"
12
  pubkey="YOUR_PUBLIC_KEY">
13
</uc-config>

So, let’s combine all the information and see how to define a locale.

How to define a locale

By default, the File Uploader uses the English locale. To use a different locale, you must provide the locale definition object to the File Uploader component.

To do this, we have an API method called defineLocale that accepts the locale definition object itself or the async function that returns the locale definition object.

We have a set of ready-made locales that you can use out of the box. They are in the locales folder on GitHub.

To use a ready-made locale, you need to import it and pass it using the defineLocale method.

There are two ways to define a locale: sync and async. Let’s take a look at both of them.

Sync way

This way is useful when you want to use the defined locale immediately. For example, if your website is in Portuguese, you want to use the Portuguese locale in the File Uploader.

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">
2
3
<script type="module">
4
  import * as UC from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.min.js';
5
  import pt from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/locales/file-uploader/pt.js';
6
7
  // Here we define the Portuguese locale with locale name 'pt'
8
  // Method `defineLocale` should be called before the `defineComponents` method. Or before the File Uploader components are appeared in the DOM.
9
  UC.defineLocale('pt', pt);
10
  UC.defineComponents(UC);
11
</script>
12
13
<uc-file-uploader-regular
14
  ctx-name="my-uploader"
15
></uc-file-uploader-regular>
16
<!-- Here we set the locale name to 'pt' -->
17
<uc-config
18
  locale-name="pt"
19
  ctx-name="my-uploader"
20
  pubkey="YOUR_PUBLIC_KEY"
21
></uc-config>

The locale-name attribute is used to set the locale name. The locale name should match the first argument passed to the defineLocale method.

Async way

This way is useful when you want to load the locale definition asynchronously. For example, you have a language switcher on your website and want to load the locale definition only when the user changes the language.

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">
2
3
<script type="module">
4
  import * as UC from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.min.js';
5
6
  // Here we define the Portuguese locale with locale name 'pt'
7
  // Method `defineLocale` should be called before the `defineComponents` method. Or before the File Uploader components are appeared in the DOM.
8
  UC.defineLocale('pt', () => import('https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/locales/file-uploader/pt.js').then((module) => module.default));
9
  UC.defineComponents(UC);
10
11
  const config = document.querySelector('uc-config');
12
  // Set the locale name to 'pt' after 3 seconds
13
  setTimeout(() => {
14
    config.localeName = 'pt';
15
  }, 3000);
16
</script>
17
18
<uc-file-uploader-regular
19
  ctx-name="my-uploader"
20
></uc-file-uploader-regular>
21
<uc-config
22
  ctx-name="my-uploader"
23
  pubkey="YOUR_PUBLIC_KEY"
24
></uc-config>

The locale-name attribute is used to set the locale name. The locale name should match the first argument passed to the defineLocale method.

Now, we’re going to take a look at how to override the existing locale.

How to update existing localization

To do so, you need to use the localeDefinitionOverride option described below. It allows you to override the specific locale definition.

1
<script type="module">
2
  const config = document.querySelector('uc-config');
3
  config.localeDefinitionOverride = {
4
    en: {
5
      'upload-file': 'Choose your documents',
6
    }
7
  };
8
</script>
9
10
<uc-config
11
  ctx-name="my-uploader"
12
  pubkey="YOUR_PUBLIC_KEY">
13
</uc-config>

In this example, we override the upload-file string in the English locale with the value Choose your documents.

How to create a new localization

Creating a new localization is as simple as defining an existing locale. You need to provide your own locale definition object to the defineLocale method.

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">
2
3
<script type="module">
4
  import * as UC from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.min.js';
5
  import pt from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/locales/file-uploader/pt.js';
6
7
  UC.defineLocale('no', {
8
    'locale-id': 'no',
9
    'social-source-lang': 'en', // there is no Norwegian language for social sources
10
    'upload-file': 'Velg fil',
11
    'file__one': 'fil',
12
    'file__other': 'filer',
13
    'header-uploading': 'Laster opp {{count}} {{plural:file(count)}}',
14
  });
15
  UC.defineComponents(UC);
16
</script>
17
18
<uc-file-uploader-regular
19
  ctx-name="my-uploader"
20
></uc-file-uploader-regular>
21
<uc-config
22
  ctx-name="my-uploader"
23
  pubkey="YOUR_PUBLIC_KEY"
24
  locale-name="no"
25
></uc-config>

As a template, you can use the English locale definition on GitHub.

You are encouraged to create a pull request with your locale definition for the GitHub repository.