Guides

Localisation

Language, number and date formats, time zone and your own translations.

Three settings, each set on its own: the language of the built-in text, the locale for numbers and dates, and the time zone for date ranges. German labels with Swiss number formats is language: 'de' with locale: 'de-CH'.

GermanCharts.tsx
import type { ReactNode } from 'react';
import { ChartsProvider } from 'em-kit';

const theme = {
  i18n: { language: 'de' }, // built-in text: 'en', 'de' or 'fr'
  formatter: { locale: 'de-DE' }, // numbers, currencies and dates
};

export function GermanCharts({ children }: { children: ReactNode }) {
  return (
    <ChartsProvider theme={theme} timezone="Europe/Berlin">
      {children}
    </ChartsProvider>
  );
}

Without formatter.locale, numbers and dates follow the browser’s language. To see every chart switch language, use the EN, DE and FR buttons above the preview on any component page.

Translate your own titles and values

Write a title or description as key|fallback. Field titles are looked up at measure.<name> and dimension.<name>, and dimension values at dimension.<name>.<value>.

TranslatedChart.tsx
import { BarChart, ChartsProvider, dimension, measure, results } from 'em-kit';

const region = dimension({ name: 'region', title: 'Region' });
const revenue = measure({ name: 'revenue', title: 'Revenue', inputs: { currency: 'EUR' } });

const rows = [
  { region: 'North America', revenue: 527900 },
  { region: 'Europe', revenue: 391500 },
];

const theme = {
  i18n: {
    language: 'de',
    translations: {
      de: {
        translation: {
          dashboard: { revenue: 'Umsatz nach Region' }, // your own key, used by the title
          measure: { revenue: 'Umsatz' }, // field titles
          dimension: {
            region: 'Region',
            'region.North America': 'Nordamerika', // dimension values
            'region.Europe': 'Europa',
          },
        },
      },
    },
  },
  formatter: { locale: 'de-DE' },
};

export function TranslatedChart() {
  return (
    <ChartsProvider theme={theme}>
      <div style={{ height: 320 }}>
        <BarChart
          title="dashboard.revenue|Revenue by region" // key|fallback
          dimension={region}
          measures={[revenue]}
          results={results(rows)}
        />
      </div>
    </ChartsProvider>
  );
}

Add a language

Add a bundle under a new language code. Any key you leave out falls back to English, so you can translate in stages. The built-in keys are in defaultTheme.i18n.translations.en.

SpanishCharts.tsx
import type { ReactNode } from 'react';
import { ChartsProvider } from 'em-kit';

const theme = {
  i18n: {
    language: 'es',
    translations: {
      es: {
        translation: {
          charts: {
            emptyTitle: 'Sin resultados.',
            emptyMessage: 'No hay datos para mostrar.',
            errorTitle: 'Algo ha fallado.',
            'menuOptions.downloadCSV': 'Descargar CSV',
          },
        },
      },
    },
  },
  formatter: { locale: 'es-ES' },
};

export function SpanishCharts({ children }: { children: ReactNode }) {
  return <ChartsProvider theme={theme}>{children}</ChartsProvider>;
}