The localization package provides methods to format dates, times, numbers, and prices according to the rules of a specific locale. For typography rules, see Microtypography.

#Dates

By default, we always display the date short with abbreviation. We never use other date formats, outside of the defined ones.

• The year is not abbreviated.
• The year is displayed when, the date spans across a year change or it's stored for a longer period (timestamp).
• We always remove the leading "0" from the date numbers
• For the short with abbreviation format, the abbreviations dot is removed.
• In EU countries the date format is always in the format of the main language of the country (e.g. all languages in France are formatted the way fr-FR is).

#Short with abbreviation

The default date format is short with abbreviation including the abbrevated da of the week.

#Medium date

In some cases we use the date medium, for example if a date range is spaning over new year's eve.

• The abbreviated weekday is removed if the year is displayed
• The year is displayed when the two dates in a range span a change of year

Note: There is a shorthand method for medium dates called formatMediumDate(). It works exactly the same as formatDate() but with a hardcoded variant: medium in the options.

#Dates in React components

In react components, the useLocalization() hook provides formatDate, by using the hook, there is no need to provide a locale.

import { useLocalization } from "@segments/localization";

const MediumDate = () => {
  const { formatDate } = useLocalization();
  return `Date: ${formatDate(date, { variant: "medium" })}`;
};

#Dates outside of React components

Outside of React components, the formatDate() method requires a locale.

import { formatDate, formatMediumDate } from "@segments/localization";

// usage with shorthand method
formatMediumDate(new Date(), "de-CH", "Europe/Zurich");

// regular usage
formatDate("2023-05-26", "de-CH", "Europe/Zurich");

#Chart-specific date formatting

For data visualizations (charts, graphs, infographics) where space is constrained, use formatDateForChart. This function provides abbreviated month formats optimized for chart axes and labels.

#Chart-specific dates outside of React components

Outside of React components, the formatDateForChart() method can be used directly, by providing a locale and timezone.

import { formatDateForChart } from "@segments/localization";

formatDateForChart(date, locale, timeZone, "month-short");
formatDateForChart(date, locale, timeZone, "day-month-short");

#Chart-specific dates in React components

In React components, the useLocalization() hook provides formatDateForChart, by using the hook, there is no need to provide a locale or timezone.

import { useLocalization } from "@segments/localization";

const ChartAxisLabel = ({ date }: { date: Date }) => {
  const { formatDateForChart } = useLocalization();
  return formatDateForChart(date, "month-short");
};

#Time

Currently all locales use the same time format.

#Time format

#Time ranges

Time ranges are connected by the en-dash character \u2013 without any spaces, example 01:00–02:35

#Time range format

#Time in React components

In React components, the useLocalization() hook provides formatTime, formatTimeRange, by using the hook, there is no need to provide a locale.

import { useLocalization } from "@segments/localization";

const TimeRange = () => {
  const { formatTimeRange } = useLocalization();
  return `Time range: ${formatTimeRange(startDate, endDate)}`;
};

#Time outside of React components

Outside of React components, the formatTime() or formatTimeRange() method can be used directly, by providing a locale and a time zone.

formatTime(new Date(), "de-CH", "Europe/Zurich");

#Relative time

Describes the timespan between now and a past date, in a human-readable format.

• The relative time is always translated, into the current locale.
• Examples: "2 hours ago" or "10 years ago".

#Examples by locale

#Numbers

Numbers refer to general numerical values such as quantities, sizes, or measurements.

• Grouping numbers starts at 10 000, meaning 9999 and lower, are not grouped.
• Grouping separator is the narrow no-break space character U+202F, example: 15 500
• Inches, degrees and percentages hav no space between the number and the unit.
• All locales use the same grouping separator.

#Number format

#Number format with units

#Number format with spaceless units

#Number ranges

#Number range format

#Numbers in React components

In React components, the useLocalization() hook provides formatNumber, by using the hook, there is no need to provide a locale.

import { useLocalization } from "@segments/localization";

const MyNumberComponent: FunctionComponent<{ sum: number }> = ({ sum }) => {
  const { formatNumber } = useLocalization();
  return `Number: ${formatNumber(sum)}`;
};

#Numbers outside of React components

Outside of React components, the formatNumber() method can be used directly, by providing a locale.

import { formatNumber } from "@segments/localization";

const formattedNumber = formatNumber(20.56, "de-CH");

#Price

• Currency is always prefixed to the number, example: CHF 20.56.
• Decimal places without value are always represented with .– example: CHF 50.–
• Grouping prices stars 10 000, meaning 9999 and lower, are not grouped.
• Grouping separator is narrow no-break space U+202F, example: CHF 15 500.56

#Price format without currency

#Price format with currency

#Price range

#Price range format

#Prices in React components

In React components, the useLocalization() hook provides formatPrice, by using the hook, there is no need to provide a locale.

import { useLocalization } from "@segments/localization";

const MyPriceComponent: FunctionComponent<{ price: number }> = ({ price }) => {
  const { formatPrice } = useLocalization();
  return `Price: ${formatPrice(price)}`;
};

#Prices outside of React components

Outside of React components, the formatPrice() method can be used directly, by providing a locale.

import { formatPrice } from "@segments/localization";

const price = formatPrice(20.56, "de-CH", { currency: "CHF" });