> This page is for version v2024-05-25 (default).
> For other versions, use one of these documentation indexes:
> - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt
> - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt
> - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# SDK localization

## Overview

Monite's [React SDK](./index) supports a localization mechanism. The React SDK defaults to the browser's locale for handling localization within SDK components. However, you can explicitly define localization using the `code` prop on the `MoniteProvider` wrapper.

Use Monite's custom localization mechanism for any of purposes:

* To define number formatting and usage of delimiters and decimal separators using the `code` property.
* To define date formats by country or region using the `code` property.
* To further customize the display format for currencies on the SDK using the `currencyNumberFormat` property.
* To customize any text labels in the widgets (for example, rename "Counterpart Name" to "Supplier Name").
* To translate the labels into one or more other languages.

The following snippet shows how to use the `locale` prop on the `MoniteProvider` wrapper:

**`React.js`**

```jsx React.js
<MoniteProvider
  monite={monite}
  locale={{
    code: "en-US",
    currencyNumberFormat: {
      display: "symbol",
      localeCode: "en-US",
    },
    messages: {
      "Counterpart Name": "Supplier Name",
      Counterpart: "Supplier",
      Sales: "Incoming transactions",
    },
  }}
>
  ...
</MoniteProvider>
```

The `code` prop is an optional property that handles the usage of delimiters and decimal separators for different countries, regions, or locales. It also handles the date formatting across various UI components. The accepted format for the `code` property must adhere to the [BCP-47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#Syntax_of_language_tags) standard.

## Currency formatting

The `currencyNumberFormat` format on the `locale` prop allows entities to define the configuration that handles the display of currencies on the SDK. This includes using either currency code or symbol and using delimiters on numbers.

**`React.js`**

```jsx React.js
<MoniteProvider
  locale={{
    code: "en-US",
    currencyNumberFormat: {
      display: "code", // formats currencies as USD 100.00
    },
  }}
>
  ...
</MoniteProvider>
```

The `currencyNumberFormat` object contains two properties—`display`, and `localeCode`.

* The `display` property handles using currency codes or symbols on currency displays in the SDK. This property has two values: `code` and `symbol`. If this property is not provided, the SDK will use currency symbols on all currency displays within the SDK.
* The `localeCode` property handles the number formatting and use of delimiters for currencies on the SDK. This property accepts the BCP-language standard for currencies, regions, and locales. This property extends the `code` prop on the `MoniteProvider` wrapper, allowing entities to provide a differrent number and currency display formatting for currencies in the SDK. If not provided, currencies will inherit the format defined in the `code` prop.

**`React.js`**

```jsx React.js
<MoniteProvider
  locale={{
    code: "en-US",
    currencyNumberFormat: {
      display: "code",
      localeCode: "en-150", // formats currencies as 100.00 USD
    },
  }}
>
  ...
</MoniteProvider>
```

## Text customization

Monite allows entities to customize texts on the React SDK. This includes changing certain SDK text labels to other English texts. This feature also allows entities to translate text to other languages according to their user-specific or locale requirements.

There are two implementation approaches you can use to handle text customization. The approach chosen depends on your requirements.

### Approach 1: Pass custom labels directly to the `MoniteProvider` component

If you need to change just a few text labels, you can specify them in the `locale` property of `MoniteProvider` component as shown below. In this example, we replace the "Counterpart Name" and "Counterpart" labels with "Supplier Name":

**`React`**

```jsx React
<MoniteProvider
  monite={monite}
  locale={{
    messages: {
      "Counterpart Name": "Supplier Name",
      Counterpart: "Supplier",
      Sales: "Incoming transactions",
    },
  }}
>
  ...
</MoniteProvider>
```

The `messages` prop is an object used to define text translations and customizations. In the `messages` object:

* The keys represent the text labels in the React SDK UI that you wish to replace. You can find all available keys on Monite's [Portable Object template](https://github.com/team-monite/monite-sdk/blob/main/packages/sdk-react/src/core/i18n/locales/en/messages.po) - look for the `msgid` strings. The keys match the exact text labels that you see in the UI.
* The values are the new text to use in place of the object's keys. Values can be of any language, and you can customize these values as required.

Any other labels not specified in the `messages` object will keep their original text.

### Approach 2: Use portable object files

**Portable Object (PO)** is the standard file format for localization. A PO file is a text file that includes the original texts and the translations.

Monite SDK includes a template PO file [here](https://github.com/team-monite/monite-sdk/blob/main/packages/sdk-react/src/core/i18n/locales/en/messages.po) that you can use or pass to your translators. This can be useful if you want to add multiple translations to your project.

The typical procedure is:

1. Copy the [template file](https://github.com/team-monite/monite-sdk/blob/main/packages/sdk-react/src/core/i18n/locales/en/messages.po) somewhere and open it in a translators' tool (such as СrowdIn or similar).

2. Create a new locale and translate the messages.

3. Save the translations to a new `messages.po` file. Put this file into the `src/locales/{locale}` directory of your project, where `{locale}` is your locale name. For example, if you use the `en` locale, the file path would be `src/locales/en/messages.po`.

4. Create the `lingui.config.js` file in the root directory of your project (next to the `package.json` file), with the following contents:

   ```js
   module.exports = {
     locales: ["en"], // your locale code, could be 'de', 'fr', etc.
     catalogs: [
       {
         path: "src/locales/{locale}/messages", // DO NOT replace "{locale}" with anything
       },
     ],
     compileNamespace: "es", // also available to build 'ts' or 'cjs' modules  format: "po"
   };
   ```

5. Run `npx @lingui/cli compile`.

6. Use the generated `messages.mjs` file to pass the translated messages to the `<MoniteProvider>`:

   ```jsx
   import { messages } from './locales/en/messages.mjs'
   ...

   <MoniteProvider monite={monite} locale={messages}>
     ...
   </MoniteProvider>
   ```