Migration guide for @uploadcare/blocks v0.38.0

BREAKING CHANGES

• CSS configuration deprecated in v0.25.0 is removed.
  See the migration guide for v0.25.0 for more details.
• Localizations are removed from CSS.
  Now we have a special API defineLocale, and locale-name and locale-definition-override options.
  See below for more details.

New localization API

Previously, we had localizations in CSS, but now we have a special JS API for that:

• defineLocale method to define a locale.
• locale-name option to set a defined locale.
• locale-definition-override option to override a locale definition.

Detailed information about the new localization API can be found on the localization page.

Migration steps

Case 1. You were using a default English locale without any customizations

This is the simplest case. You don’t need to do anything. The default English locale is still used by default, so no changes are required.

Case 2. You were using a default English locale with customizations

You were using the default English locale with some custom translations. For example, you were using the following CSS that overrides the upload button text:

1
.my-locale-override {
2
  --l10n-upload-files: 'Choose your documents';
3
}

Now you need to use locale-definition-override option to override the upload-files key:

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

Get YOUR_PUBLIC_KEY from API keys.

See the localization page for more details.

Case 3. You were using a custom non-English locale

You were using a custom non-English locale. For example, you were using the following CSS that defines a custom locale:

1
.l10n-pt-PT {
2
  --l10n-locale-name: 'pt-PT';
3
4
  --l10n-upload-file: 'Carregar ficheiro';
5
  --l10n-upload-files: 'Carregar ficheiros';
6
  --l10n-choose-file: 'Escolher ficheiro';
7
  /* etc */
8
}

To achieve the same result, you need to define a custom locale using the defineLocale method and then set the locale-name option:

1
<script type="module">
2
  import * as LR from 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.38.0/web/blocks.min.js';
3
4
  LR.defineLocale('pt', {
5
    'locale-id': 'pt',
6
    'social-source-lang': 'pt',
7
8
    'upload-file': 'Carregar ficheiro',
9
    'upload-files': 'Carregar ficheiros',
10
    'choose-file': 'Escolher ficheiro',
11
    // etc
12
  });
13
  LR.registerBlocks(LR);
14
</script>
15
16
<lr-file-uploader-regular
17
  ctx-name="my-uploader"
18
  css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.38.0/web/lr-file-uploader-regular.min.css"
19
></lr-file-uploader-regular>
20
21
<!-- Here we set the locale name to 'pt' -->
22
<lr-config
23
  locale-name="pt"
24
  ctx-name="my-uploader"
25
  pubkey="YOUR_PUBLIC_KEY"
26
></lr-config>

See the localization page for more details.

Also check the our ready-to-use locales in the @uploadcare/blocks GitHub repository.

We will be happy if you contribute your custom locales to the repository.