# Localisation

CanvasGrid renders what you pass it as a `formattedValue` of `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 (`formattedValue`). The underlying numeric values (`effectiveValue.nv`) are always preserved.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rowsncolumns.app/configuration/features/localisation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.