# 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'`.

```tsx title="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](/docs/components.md).

## 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>`.

```tsx title="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`.

```tsx title="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>;
}
```
