> 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.

# Localization

> Localize messages from custom file and collection validators using api.l10n and extended locales.

Localize the messages your validators return so users always see clear, familiar text in their language. This page shows how to add keys, use them from validators, and keep things maintainable.

## Quick start

1. Pick message keys you’ll use in validators (for example: `filename-no-spaces`, `collection-uniform-top-level-type`).
2. Add these keys to your locales using `UC.defineLocale`.
3. In validators, return `message: api.l10n('<your-key>')`.
4. Switch the uploader language and verify messages appear as expected.

## Add your keys to locales

Import your current locales and extend them with validator-specific keys.

```js
import { default as en } from "./locales/file-uploader/en.js";
import { default as fr } from "./locales/file-uploader/fr.js";

UC.defineLocale("en", {
  ...en,
  "filename-no-spaces": "Filenames cannot contain spaces",
  "collection-uniform-top-level-type":
    "Please select files of the same top-level type",
});

UC.defineLocale("fr", {
  ...fr,
  "filename-no-spaces":
    "Les noms de fichiers ne doivent pas contenir d’espaces",
  "collection-uniform-top-level-type":
    "Veuillez sélectionner des fichiers du même type de niveau supérieur",
});

UC.defineComponents(UC);
```

## Use keys from validators

File validator example (no spaces in filename)

```js
const noSpacesInFilename = (entry, api) => {
  if (entry.fileName?.includes(" ")) {
    return { message: api.l10n("filename-no-spaces") };
  }
};
```

Collection validator example (uniform top‑level MIME type)

```js
const uniformTopLevelMime = (collection, api) => {
  const top = (m) => m.split("/")[0];
  const types = new Set(
    collection.allEntries
      .filter((e) => !!e.mimeType)
      .map((e) => top(e.mimeType))
  );
  if (types.size > 1) {
    return { message: api.l10n("collection-uniform-top-level-type") };
  }
};
```

## See also

* [Localization](/docs/file-uploader/localization)
* [File validators](/docs/file-uploader/file-validators)
* [Collection validators](/docs/file-uploader/collection-validators)
* [Uploader API](/docs/file-uploader/api/)