1 | # Internationalization
|
2 |
|
3 | ## Table of Contents
|
4 |
|
5 | - [Usage](#usage)
|
6 |
|
7 | - [Adding New Language](#adding-new-language)
|
8 |
|
9 | ## Usage
|
10 |
|
11 | There are just a few functions that support I18n:
|
12 |
|
13 | - [`format`](https://date-fns.org/docs/format)
|
14 | - [`formatDistance`](https://date-fns.org/docs/formatDistance)
|
15 | - [`formatDistanceStrict`](https://date-fns.org/docs/formatDistanceStrict)
|
16 | - [`formatRelative`](https://date-fns.org/docs/formatRelative)
|
17 |
|
18 | To use a locale, you need to require it and then pass
|
19 | as an option to a function:
|
20 |
|
21 | ```js
|
22 | import { formatDistance } from 'date-fns'
|
23 | // Require Esperanto locale
|
24 | import { eo } from 'date-fns/locale'
|
25 |
|
26 | const result = formatDistance(
|
27 | new Date(2016, 7, 1),
|
28 | new Date(2015, 0, 1),
|
29 | {locale: eo} // Pass the locale as an option
|
30 | )
|
31 | //=> 'pli ol 1 jaro'
|
32 | ```
|
33 |
|
34 | It might seem complicated to require and pass locales as options,
|
35 | but unlike Moment.js which bloats your build with all the locales
|
36 | by default date-fns forces developer to manually require locales when needed.
|
37 | To make API simple, we encourage you to write tiny wrappers and use those
|
38 | instead of original functions:
|
39 |
|
40 | ```js
|
41 | // app/_lib/format.js
|
42 |
|
43 | import { format } from 'date-fns'
|
44 | import { enGB, eo, ru } from 'date-fns/locale'
|
45 |
|
46 | const locales = {enGB, eo, ru}
|
47 |
|
48 | // by providing a default string of 'PP' or any of its variants for `formatStr`
|
49 | // it will format dates in whichever way is appropriate to the locale
|
50 | export default function (date, formatStr = 'PP') {
|
51 | return format(date, formatStr, {
|
52 | locale: locales[window.__localeId__] // or global.__localeId__
|
53 | })
|
54 | }
|
55 |
|
56 | // Later:
|
57 |
|
58 | import format from 'app/_lib/format'
|
59 |
|
60 | window.__localeId__ = 'en'
|
61 | format(friday13, 'EEEE d')
|
62 | //=> 'Friday 13'
|
63 |
|
64 | window.__localeId__ = 'eo'
|
65 | format(friday13, 'EEEE d')
|
66 | //=> 'vendredo 13'
|
67 |
|
68 | // If the format string is omitted, it will take the default for the locale.
|
69 | window.__localeId__ = 'en'
|
70 | format(friday13)
|
71 | //=> Jul 13, 2019
|
72 |
|
73 | window.__localeId__ = 'eo'
|
74 | format(friday13)
|
75 | //=> 2019-jul-13
|
76 |
|
77 | ```
|
78 |
|
79 | ## Adding New Language
|
80 |
|
81 | At the moment there is no definitive guide, so if you feel brave enough,
|
82 | use this quick guide:
|
83 |
|
84 | - First of all, [create an issue](https://github.com/date-fns/date-fns/issues/new?title=XXX%20language%20support)
|
85 | so you won't overlap with others.
|
86 | - A detailed explanation of how to [add a new locale](https://github.com/date-fns/date-fns/blob/master/docs/i18nContributionGuide.md#adding-a-new-locale).
|
87 | - Use [English locale](https://github.com/date-fns/date-fns/tree/master/src/locale/en-US)
|
88 | as the basis and then incrementally adjust the tests and the code.
|
89 | - Directions on [adding a locale with the same language as another locale](https://github.com/date-fns/date-fns/blob/master/docs/i18nContributionGuide.md#creating-a-locale-with-the-same-language-as-another-locale).
|
90 | - If you have questions or need guidance, leave a comment in the issue.
|
91 |
|
92 | Thank you for your support!
|