> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://uploadcare.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server. # File Uploader localization > Localize your Uploadcare File Uploader by translating UI elements to match your app’s language and provide a better user experience globally. 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. > **Note** > > **Note:** Before the v0.38.0, the localization API was working through the CSS. See the [migration guide](/docs/file-uploader/migration-to-0.38.0/) for more details. ## Locale definition The locale definition is described as a plain JS object like this: ```js export default { 'locale-id': 'en', 'social-source-lang': 'en', 'upload-file': 'Upload file', 'file__one': 'file', 'file__other': 'files', 'header-uploading': 'Uploading {{count}} {{plural:file(count)}}', } ``` 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) for more details. * `social-source-lang`: the language code for social sources. It's used to set the language for social sources like Facebook. 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. Available languages: \ `'de', 'en', 'es', 'fi', 'fr', 'he', 'it', 'nl', 'pl', 'pt', 'ru', 'tr', 'uk', 'zh-TW', 'zh'` \ For more details check out the [list of locales](https://github.com/uploadcare/file-uploader/tree/main/src/locales/file-uploader). ### 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](https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html) 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](https://github.com/uploadcare/file-uploader/blob/main/src/locales/file-uploader/en.ts) on GitHub. Plugins can extend the locale with their own keys using [`registerL10n`](/docs/file-uploader/plugins/#registerl10n): these keys are merged with the built-in locale and accessible via `uploaderApi.l10n()`. Let's take a look at localization API. ## Method `defineLocale` \[#locale-locale] 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: ```ts type LocaleDefinition = Record; type LocaleDefinitionResolver = () => Promise; 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** > > **Warning:** The `defineLocale` method should be called before the `defineComponents` > method or before the File Uploader components appear in the DOM. ## Option `locale-name` \[#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: ```html ``` Get `YOUR_PUBLIC_KEY` from [API keys](https://app.uploadcare.com/projects/-/api-keys/). See the [File Uploader options](/docs/file-uploader/options/#locale-name) for more details. ## Option `localeDefinitionOverride` \[#locale-definition-override] 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: ```ts type LocaleName = string; type LocaleDefinition = Record; type LocaleDefinitionOverride = Record; ``` Here is how to use it: ```html ``` 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](https://github.com/uploadcare/file-uploader/tree/main/src/locales/file-uploader) 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. ```html ``` 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. ```html ``` 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. ```html ``` 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. ```html ``` As a template, you can use the [English locale definition](https://github.com/uploadcare/file-uploader/blob/main/src/locales/file-uploader/en.ts) on GitHub. You are encouraged to create a pull request with your locale definition for the [GitHub repository](https://github.com/uploadcare/file-uploader).