> For the complete documentation index, see [llms.txt](https://docs.rowsncolumns.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rowsncolumns.app/configuration/features/localisation.md).

# Localisation

CanvasGrid renders what you pass it as a `fv` (formatted value) of the `CellData` object.

{% hint style="info" %}
RTL layout is not currently supported
{% endhint %}

## Setting the Locale

If you are using `useSpreadsheetState` for state management of Spreadsheet, you can pass in a `locale` prop to configure date and number formatting for different regions.

Locale is auto-detected from `Intl` JavaScript object if not provided.

```tsx
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state"

const Spreadsheet = () => {
  const { } = useSpreadsheetState({
    locale: 'en-US'
  })
}

export const App = () => {
  <SpreadsheetProvider>
    <Spreadsheet />
  <SpreadsheetProvider>
}
```

## Switching Locale at Runtime

When users switch locales (e.g., from `de-DE` to `en-US`), all formatted values in the spreadsheet need to be regenerated to reflect the new locale's formatting rules.

The `onChangeLocale` function handles this automatically:

```tsx
import { useState } from "react";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

const Spreadsheet = () => {
  const [locale, setLocale] = useState("en-US");

  const { onChangeLocale } = useSpreadsheetState({
    locale,
    // ... other props
  });

  const handleLocaleChange = (newLocale: string) => {
    // Update the locale state
    setLocale(newLocale);
    // Regenerate all formatted values with the new locale
    onChangeLocale(newLocale);
  };

  return (
    <>
      <select
        value={locale}
        onChange={(e) => handleLocaleChange(e.target.value)}
      >
        <option value="en-US">English (US)</option>
        <option value="de-DE">German (Germany)</option>
        <option value="fr-FR">French (France)</option>
        <option value="es-ES">Spanish (Spain)</option>
        <option value="pt-BR">Portuguese (Brazil)</option>
      </select>
      {/* ... spreadsheet components */}
    </>
  );
};
```

### What Changes When Locale Switches

| Aspect                  | Behavior                                         |
| ----------------------- | ------------------------------------------------ |
| **Decimal separator**   | Changes (e.g., `.` in en-US, `,` in de-DE)       |
| **Thousands separator** | Changes (e.g., `,` in en-US, `.` in de-DE)       |
| **Currency symbol**     | Preserved (e.g., `$` stays `$`, `€` stays `€`)   |
| **Currency position**   | Preserved (encoded in the number format pattern) |
| **Numeric values**      | Preserved (only display formatting changes)      |
| **Date formats**        | Re-formatted according to locale conventions     |

### Example: Number Formatting Across Locales

The same numeric value `1234567.89` displays differently based on locale:

| Locale  | Formatted Value |
| ------- | --------------- |
| `en-US` | `1,234,567.89`  |
| `de-DE` | `1.234.567,89`  |
| `fr-FR` | `1 234 567,89`  |
| `es-ES` | `1.234.567,89`  |
| `pt-BR` | `1.234.567,89`  |

### Currency Formatting

When switching locales, currency symbols are preserved. Only the number formatting changes:

```
// USD currency cell with value 1234.56
en-US: $1,234.56
de-DE: $1.234,56  // Same symbol, different separators
fr-FR: $1 234,56  // Same symbol, French formatting
```

This matches the behavior of Google Sheets and Microsoft Excel.

### Supported Locales

The spreadsheet supports any valid BCP 47 locale identifier. Common examples include:

**European:**

* `de-DE` (German - Germany)
* `fr-FR` (French - France)
* `es-ES` (Spanish - Spain)
* `it-IT` (Italian - Italy)
* `nl-NL` (Dutch - Netherlands)
* `pl-PL` (Polish - Poland)
* `pt-PT` (Portuguese - Portugal)
* `sv-SE` (Swedish - Sweden)
* `da-DK` (Danish - Denmark)
* `fi-FI` (Finnish - Finland)
* `nb-NO` (Norwegian - Norway)

**Americas:**

* `en-US` (English - United States)
* `en-CA` (English - Canada)
* `fr-CA` (French - Canada)
* `es-MX` (Spanish - Mexico)
* `es-AR` (Spanish - Argentina)
* `pt-BR` (Portuguese - Brazil)

**Asia-Pacific:**

* `ja-JP` (Japanese - Japan)
* `zh-CN` (Chinese - China)
* `ko-KR` (Korean - Korea)
* `hi-IN` (Hindi - India)
* `th-TH` (Thai - Thailand)

### Undo/Redo Support

Locale changes are recorded in the undo history. Users can undo a locale change to restore the previous formatted values.

{% hint style="info" %}
Locale switching only affects the display format (`fv`). The underlying numeric values (`ev.nv`) are always preserved.
{% endhint %}