Localisation

Add text in any language in the Spreadsheet

CanvasGrid renders what you pass it as a formattedValue of CellData object.

RTL layout is not currently supported

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.

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:

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.

Locale switching only affects the display format (formattedValue). The underlying numeric values (effectiveValue.nv) are always preserved.