1. Spreadsheet docs
  2. Developers

Languages and regions

Set the interface language and the region (number and date formats, separators) of an embedded workbook, switch them at run time, and how formula languages work.

Three settings are often confused, and 8sheets keeps them apart, as desktop spreadsheets do:

SettingWhat it changesWho sets it
Interface languageThe words of the ribbon, menus, dialogs, messages and the status bar: English (en) or Polish (pl)Your code, with the language option, or the user
RegionHow numbers and dates show and are typed: decimal, group and list separators, date order, month and day names, the system currencyYour code, with wb.region, or the user, under File > Region
Formula languageWhether function names show and are typed in English or in a localized form, such as SUMA for SUM in PolishThe user, under Formulas > Formula Language

Files always store formulas in English with commas, as Excel stores them, so a workbook calculates the same whatever the settings, and formulas written from code are always in English.

Set the interface language

JavaScript

import { mountWorkbook } from '@8sheets/core';

// Left out, the language is the user's choice from Preferences, else the browser's.
const wb = await mountWorkbook(document.querySelector('#sheet'), { language: 'pl' });

document.querySelector('#lang').addEventListener('change', async (e) => {
  const used = await wb.setLanguage(e.target.value);   // resolves once the app shows it
  console.log('Interface language:', used);
});

React

import { useState } from 'react';
import { Sheet } from '@8sheets/react';

export function Workbook() {
  const [language, setLanguage] = useState('pl');
  return (
    <>
      <select value={language} onChange={(e) => setLanguage(e.target.value)}>
        <option value="en">English</option>
        <option value="pl">Polski</option>
      </select>
      <div style={{ height: 520 }}>
        <Sheet options={{ language }} />
      </div>
    </>
  );
}

Vue

<script setup>
import { reactive } from 'vue';
import { Sheet } from '@8sheets/vue';

const options = reactive({ language: 'pl' });
</script>

<template>
  <select v-model="options.language">
    <option value="en">English</option>
    <option value="pl">Polski</option>
  </select>
  <Sheet :options="options" style="height: 520px" />
</template>

Angular

import { Component, signal } from '@angular/core';
import { SheetComponent, SheetOptions } from '@8sheets/angular';

@Component({
  selector: 'app-workbook',
  imports: [SheetComponent],
  template: `
    <select [value]="options().language" (change)="setLanguage($any($event.target).value)">
      <option value="en">English</option>
      <option value="pl">Polski</option>
    </select>
    <eight-sheet class="grid" [options]="options()" />
  `,
  styles: `.grid { height: 520px; }`,
})
export class Workbook {
  options = signal<SheetOptions>({ language: 'pl' });

  setLanguage(language: string) {
    this.options.update((o) => ({ ...o, language }));
  }
}
  • wb.language = 'en' switches at once: the ribbon, menus and status bar follow immediately, and dialogs that are open keep their language until they are opened again.
  • await wb.setLanguage('pl') does the same and resolves to the code in use once the app shows it. An unknown code changes nothing.
  • The language belongs to the page, so all workbooks on a page share it.
  • Giving language: undefined to setOptions goes back to the user's choice, else the browser's.

Set the region

wb.region is a BCP 47 tag such as en-US, en-GB, de-DE or pl-PL. It changes what cells show (decimal and group separators, month and day names, the short and long date and the currency of the built-in formats) and what users type and see in the formula bar: in pl-PL, 1,5 and =SUMA(A1;B1) with the Polish formula language, or =SUM(A1;B1) with English names. Files and the API stay in the invariant form: values, formulas and input take 1.5 and =SUM(A1,B1) in every region.

JavaScript

import { mountWorkbook } from '@8sheets/core';

const wb = await mountWorkbook(document.querySelector('#sheet'), { language: 'en' });
wb.region = 'de-DE';                       // 1.234,50 and 05.01.2027 on screen

wb.activeSheet.range('A1').values = 1234.5;   // the API stays invariant
console.log(wb.regionInfo.decimalSeparator, wb.regionInfo.listSeparator);   // ',' ';'
console.log(wb.regions.map((r) => r.tag));     // the regions the Region dialog offers

React

import { Sheet } from '@8sheets/react';

export function Workbook({ locale }) {   // e.g. the user's profile setting, 'de-DE'
  return (
    <div style={{ height: 520 }}>
      <Sheet key={locale} onReady={(wb) => { wb.region = locale; }} />
    </div>
  );
}

Vue

<script setup>
import { watch } from 'vue';
import { Sheet, useSheet } from '@8sheets/vue';

const props = defineProps({ locale: String });
const { sheet, workbook } = useSheet();
watch([workbook, () => props.locale], ([wb, locale]) => { if (wb && locale) wb.region = locale; });
</script>

<template>
  <Sheet ref="sheet" style="height: 520px" />
</template>

Angular

import { Component, Input } from '@angular/core';
import { SheetComponent, SheetsWorkbook } from '@8sheets/angular';

@Component({
  selector: 'app-workbook',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" (ready)="wb = $event; apply()" />`,
  styles: `.grid { height: 520px; }`,
})
export class Workbook {
  wb?: SheetsWorkbook;
  private locale = 'de-DE';

  @Input() set region(tag: string) {
    this.locale = tag;
    this.apply();
  }

  apply() {
    if (this.wb) this.wb.region = this.locale;
  }
}
  • The region belongs to the page, as the interface language does: setting it changes every workbook on the page at once.
  • A tag the browser doesn't know throws a RangeError. wb.regions lists the regions the Region dialog offers ({ tag, name }); any other tag the browser's Intl knows works too.
  • wb.regionInfo tells what the region decides (separators, date patterns, currency), so your own labels next to the grid can show numbers the same way.
  • The region isn't saved, in the workbook or in the browser: set it after each mount.
  • CSV and text files follow the region, as in Excel. Opening one reads numbers and dates in the region's forms (1,5 and 05.01.2024 in pl-PL), and a file whose lines all hold the region's list separator splits on it. File > Export Sheet as CSV separates fields with the list separator: ; where numbers show 1,5. The Text Import and Text to Columns wizards start with the region's date order and separators, and their Decimal separator and Thousands separator read text written in another one.

What is translated

The interface: ribbon tabs and commands, menus, dialogs, task panes, messages and tooltips. Spelling and the thesaurus have English and Polish dictionaries; the user chooses the proofing language under Review > Language.

The workbook's contents are never translated: sheet names, cell text, number formats and table names are part of the document.

Formula languages

Users can see and type formulas with localized function names in Chinese, Czech, Danish, Dutch, Finnish, French, German, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese (Brazil and Portugal), Russian, Spanish, Swedish and Turkish. Polish has the most complete list; where a localized name hasn't been confirmed from Microsoft's published lists, the English name is used. See Formulas and functions.

This is a display setting only. range.formulas reads and writes English names in every case.

Limits

  • The interface comes in English and Polish. Other interface languages are not available yet.
  • The formula language is a user preference of the app; the API has no option for it.
  • The region isn't saved; set wb.region after each mount.