timepiece/node_modules/date-fns/docs/i18n.md

Internationalization

Table of Contents

• Usage

• Adding New Language

Usage

There are just a few functions that support I18n:

• format
• formatDistance
• formatDistanceStrict
• formatRelative

To use a locale, you need to require it and then pass as an option to a function:

import { formatDistance } from "date-fns";
// Require Esperanto locale
import { eo } from "date-fns/locale";

const result = formatDistance(
  new Date(2016, 7, 1),
  new Date(2015, 0, 1),
  { locale: eo }, // Pass the locale as an option
);
//=> 'pli ol 1 jaro'

It might seem complicated to require and pass locales as options, but unlike Moment.js which bloats your build with all the locales by default date-fns forces developer to manually require locales when needed. To make API simple, we encourage you to write tiny wrappers and use those instead of original functions:

// app/_lib/format.js

import { format } from "date-fns";
import { enGB, eo, ru } from "date-fns/locale";

const locales = { enGB, eo, ru };

// by providing a default string of 'PP' or any of its variants for `formatStr`
// it will format dates in whichever way is appropriate to the locale
export default function (date, formatStr = "PP") {
  return format(date, formatStr, {
    locale: locales[window.__localeId__], // or global.__localeId__
  });
}

// Later:

import format from "app/_lib/format";

window.__localeId__ = "enGB";
format(friday13, "EEEE d");
//=> 'Friday 13'

window.__localeId__ = "eo";
format(friday13, "EEEE d");
//=> 'vendredo 13'

// If the format string is omitted, it will take the default for the locale.
window.__localeId__ = "enGB";
format(friday13);
//=> Jul 13, 2019

window.__localeId__ = "eo";
format(friday13);
//=> 2019-jul-13

Adding New Language

At the moment there is no definitive guide, so if you feel brave enough, use this quick guide:

• First of all, create an issue so you won't overlap with others.
• A detailed explanation of how to add a new locale.
• Use English locale as the basis and then incrementally adjust the tests and the code.
• Directions on adding a locale with the same language as another locale.
• If you have questions or need guidance, leave a comment in the issue.

Thank you for your support!