i18n

Moment.js has robust support for internationalization.

You can load multiple locales and easily switch between them.

In addition to assigning a global locale, you can assign a locale to a specificmoment.

Changing locale globally1.0.0+

  1. // From 2.8.1 onward
  2. moment.locale(String);
  3. moment.locale(String[]);
  4. moment.locale(String, Object);
  6. // Deprecated in 2.8.1
  7. moment.lang(String);
  8. moment.lang(String[]);
  9. moment.lang(String, Object);

By default, Moment.js comes with English (United States) locale strings. If you need other locales, you can load them into Moment.js for later use.

To load a locale, pass the key and the string values to moment.locale.

More details on each of the parts of the locale bundle can be found in the customization section.

  1. moment.locale('fr', {
  2.     months : 'janvier_février_mars_avril_mai_juin_juillet_août_septembre_octobre_novembre_décembre'.split('_'),
  3.     monthsShort : 'janv._févr._mars_avr._mai_juin_juil._août_sept._oct._nov._déc.'.split('_'),
  4.     monthsParseExact : true,
  5.     weekdays : 'dimanche_lundi_mardi_mercredi_jeudi_vendredi_samedi'.split('_'),
  6.     weekdaysShort : 'dim._lun._mar._mer._jeu._ven._sam.'.split('_'),
  7.     weekdaysMin : 'Di_Lu_Ma_Me_Je_Ve_Sa'.split('_'),
  8.     weekdaysParseExact : true,
  9.     longDateFormat : {
  10.         LT : 'HH:mm',
  11.         LTS : 'HH:mm:ss',
  12.         L : 'DD/MM/YYYY',
  13.         LL : 'D MMMM YYYY',
  14.         LLL : 'D MMMM YYYY HH:mm',
  15.         LLLL : 'dddd D MMMM YYYY HH:mm'
  16.     },
  17.     calendar : {
  18.         sameDay : '[Aujourd’hui à] LT',
  19.         nextDay : '[Demain à] LT',
  20.         nextWeek : 'dddd [à] LT',
  21.         lastDay : '[Hier à] LT',
  22.         lastWeek : 'dddd [dernier à] LT',
  23.         sameElse : 'L'
  24.     },
  25.     relativeTime : {
  26.         future : 'dans %s',
  27.         past : 'il y a %s',
  28.         s : 'quelques secondes',
  29.         m : 'une minute',
  30.         mm : '%d minutes',
  31.         h : 'une heure',
  32.         hh : '%d heures',
  33.         d : 'un jour',
  34.         dd : '%d jours',
  35.         M : 'un mois',
  36.         MM : '%d mois',
  37.         y : 'un an',
  38.         yy : '%d ans'
  39.     },
  40.     dayOfMonthOrdinalParse : /\d{1,2}(er|e)/,
  41.     ordinal : function (number) {
  42.         return number + (number === 1 ? 'er' : 'e');
  43.     },
  44.     meridiemParse : /PD|MD/,
  45.     isPM : function (input) {
  46.         return input.charAt(0) === 'M';
  47.     },
  48.     // In case the meridiem units are not separated around 12, then implement
  49.     // this function (look at locale/id.js for an example).
  50.     // meridiemHour : function (hour, meridiem) {
  51.     //     return /* 0-23 hour, given meridiem token and hour 1-12 */ ;
  52.     // },
  53.     meridiem : function (hours, minutes, isLower) {
  54.         return hours < 12 ? 'PD' : 'MD';
  55.     },
  56.     week : {
  57.         dow : 1, // Monday is the first day of the week.
  58.         doy : 4  // Used to determine first week of the year.
  59.     }
  60. });

Details about week.dow and week.doy can be found in the customization section.

Once you load a locale, it becomes the active locale. To change active locales, simply call moment.locale with the key of a loaded locale.

  1. moment.locale('fr');
  2. moment(1316116057189).fromNow(); // il y a une heure
  3. moment.locale('en');
  4. moment(1316116057189).fromNow(); // an hour ago

As of 2.21.0, Moment will console.warn if the locale is unavailable.

As of 2.8.0, changing the global locale doesn't affect existing instances.

  1. moment.locale('fr');
  2. var m = moment(1316116057189);
  3. m.fromNow(); // il y a une heure
  5. moment.locale('en');
  6. m.fromNow(); // il y a une heure
  7. moment(1316116057189).fromNow(); // an hour ago

moment.locale returns the locale used. This is useful because Moment won't change locales if it doesn't know the one you specify.

  1. moment.locale('fr'); // 'fr'
  2. moment.locale('tq'); // 'fr'

You may also specify a list of locales, and Moment will use the first one it has localizations for.

  1. moment.locale(['tq', 'fr']); // 'fr'

Moment will also try locale specifier substrings from most-specific to least-specific until it finds a locale it knows. This is useful when supplying Moment with a locale string pulled from the user's environment, such as window.navigator.language.

  1. moment.locale('en-NZ'); // 'en'

Finally, Moment will search intelligently through an array of locales and their substrings.

  1. moment.locale(['en-NZ', 'en-AU']); // 'en-au', not 'en'

Changing locales locally1.7.0+

  1. // From version 2.8.1 onward
  2. moment().locale(String|Boolean);
  4. // Deprecated version 2.8.1
  5. moment().lang(String|Boolean);

A global locale configuration can be problematic when passing around moments that may need to be formatted into different locale.

  1. moment.locale('en'); // default the locale to English
  2. var localLocale = moment();
  4. localLocale.locale('fr'); // set this instance to use French
  5. localLocale.format('LLLL'); // dimanche 15 juillet 2012 11:01
  6. moment().format('LLLL'); // Sunday, July 15 2012 11:01 AM
  8. moment.locale('es'); // change the global locale to Spanish
  9. localLocale.format('LLLL'); // dimanche 15 juillet 2012 11:01
  10. moment().format('LLLL'); // Domingo 15 Julio 2012 11:01
  12. localLocale.locale(false); // reset the instance locale
  13. localLocale.format('LLLL'); // Domingo 15 Julio 2012 11:01
  14. moment().format('LLLL'); // Domingo 15 Julio 2012 11:01

If you call moment#locale with no parameters, you get back the locale configuration that would be used for that moment.

  1. var fr = moment().locale('fr');
  2. fr.localeData().months(moment([2012, 0])) // "janvier"
  3. fr.locale('en');
  4. fr.localeData().months(moment([2012, 0])) // "January"

If you need to access the locale data for a moment, this is the preferred way to do so.

As of 2.3.0, you can also specify an array of locale identifiers. It works the same way it does in the global locale configuration.

Loading locales in NodeJS1.0.0+

  1. moment.locale(String);

Loading locales in NodeJS is super easy. If there is a locale file in moment-root/locale/ named after that key, the first call to moment.locale will load it.

  1. var moment = require('moment');
  2. moment.locale('fr');
  3. moment(1316116057189).fromNow(); // il y a une heure

If you want your locale supported, create a pull request to the develop branch with the required locale and unit test files.

Loading locales in the browser1.0.0+

  1. // From 2.8.1 onward
  2. moment.locale(String, Object);
  4. // Deprecated in 2.8.1
  5. moment.lang(String, Object);

Loading locales in the browser just requires you to include the locale files. Be sure to specify the charset to prevent encoding issues.

  1. <script src="moment.js"></script>
  2. <script src="locale/fr.js" charset="UTF-8"></script>
  3. <script src="locale/pt.js" charset="UTF-8"></script>
  4. <script>
  5.   moment.locale('fr');  // Set the default/global locale
  6.   // ...
  7. </script>

There are minified versions of all locales together:

  1. <script src="moment.js"></script>
  2. <script src="min/locales.js" charset="UTF-8"></script>

To minimize HTTP requests, use our Grunt task to compile Moment with a custom list of locales:

  1. grunt transpile:fr,it
  1. <script src="min/moment-with-locales.custom.js" charset="UTF-8"></script>

If you are using JSPM as plugin manager, you should add the locale in your lib.

  1. import * as moment from 'moment';
  2. import 'moment/locale/fr';

Note: Locale files are defined in UMD style, so they should work seamlessly in all environments.

Adding your locale to Moment.js

To add your locale to Moment.js, submit a pull request with both a locale file and a test file. You can find examples in moment/src/locale/fr.js and moment/src/test/locale/fr.js.

To run the tests in Node.js, do npm install, then grunt.

If all the tests pass, submit a pull request, and thank you for contributing!

Checking the current Moment.js locale1.6.0+

  1. // From version 2.8.1 onward
  2. moment.locale();
  4. // Deprecated in version 2.8.1
  5. moment.lang();

If you are changing locales frequently, you may want to know what locale is currently being used. This is as simple as calling moment.locale without any parameters.

  1. moment.locale('en'); // set to english
  2. moment.locale(); // returns 'en'
  3. moment.locale('fr'); // set to french
  4. moment.locale(); // returns 'fr'

As of version 2.12.0 it is possible to list all locales that have been loaded and are available to use:

  1. moment.locales()

Listing the months and weekdays of the current Moment.js locale2.3.0+

  1. moment.months()
  2. moment.monthsShort()
  3. moment.weekdays()
  4. moment.weekdaysShort()
  5. moment.weekdaysMin()

It is sometimes useful to get the list of months or weekdays in a locale, for example when populating a dropdown menu.

  1. moment.months();

Returns the list of months in the current locale.

  1. [ 'January',
  2.   'February',
  3.   'March',
  4.   'April',
  5.   'May',
  6.   'June',
  7.   'July',
  8.   'August',
  9.   'September',
  10.   'October',
  11.   'November',
  12.   'December' ]

Similarly, moment.monthsShort returns abbreviated month names, and moment.weekdays, moment.weekdaysShort, moment.weekdaysMin return lists of weekdays.

You can pass an integer into each of those functions to get a specific month or weekday.

  1. moment.weekdays(3); // 'Wednesday'

As of 2.13.0 you can pass a bool as the first parameter of the weekday functions. If true, the weekdays will be returned in locale specific order.For instance, in the Arabic locale, Saturday is the first day of the week, thus:

  1. moment.locale('ar');
  2. moment.weekdays(true); // lists weekdays Saturday-Friday in Arabic
  3. moment.weekdays(true, 2); //will result in Monday in Arabic

Note: Absent the locale specific parameter, weekdays always have Sunday as index 0, regardless of the local first day of the week.

Some locales make special considerations into account when formatting month names. For example, Dutch formats month abbreviations without a trailing period, but only if it's formatting the month between dashes. The months method supports passing a format in so that the months will be listed in the proper context.

  1. moment.locale('nl');
  2. moment.monthsShort(); // ['jan.', 'feb.', 'mrt.', ...]
  3. moment.monthsShort('-MMM-'); // [ 'jan', 'feb', 'mrt', ...]

And finally, you can combine both the format option and the integer option.

  1. moment.monthsShort('-MMM-', 3); // 'apr'

Accessing locale specific functionality2.8.0+

  1. localeData = moment.localeData()
  2. localeData.months(Moment)
  3. localeData.months()
  4. localeData.monthsShort(Moment)
  5. localeData.monthsShort()
  6. localeData.monthsParse(String)
  7. localeData.weekdays(Moment)
  8. localeData.weekdays()
  9. localeData.weekdays(Boolean)      ## Added 2.24.0, sorts weekdays by locale
  10. localeData.weekdaysShort(Moment)
  11. localeData.weekdaysShort()
  12. localeData.weekdaysShort(Boolean) ## Added 2.24.0, sorts weekdays by locale
  13. localeData.weekdaysMin(Moment)
  14. localeData.weekdaysMin()
  15. localeData.weekdaysMin(Boolean)   ## Added 2.24.0, sorts weekdays by locale
  16. localeData.weekdaysParse(String)
  17. localeData.longDateFormat(String)
  18. localeData.isPM(String)
  19. localeData.meridiem(Number, Number, Boolean)
  20. localeData.calendar(String, Moment)
  21. localeData.relativeTime(Number, Boolean, String, Boolean)
  22. localeData.pastFuture(Number, String)
  23. localeData.ordinal(Number)
  24. localeData.preparse(String)
  25. localeData.postformat(String)
  26. localeData.week(Moment)
  27. localeData.invalidDate()
  28. localeData.firstDayOfWeek()
  29. localeData.firstDayOfYear()

You can access the properties of the currently loaded locale through themoment.localeData(key) function. It returns the current locale or a localewith the given key:

  1. // get current locale
  2. var currentLocaleData = moment.localeData();
  3. var frLocaleData = moment.localeData('fr');

The returned object has the following methods:

  1. localeData.months(aMoment);  // full month name of aMoment
  2. localeData.monthsShort(aMoment);  // short month name of aMoment
  3. localeData.monthsParse(longOrShortMonthString);  // returns month id (0 to 11) of input
  4. localeData.weekdays(aMoment);  // full weekday name of aMoment
  5. localeData.weekdaysShort(aMoment);  // short weekday name of aMoment
  6. localeData.weekdaysMin(aMoment);  // min weekday name of aMoment
  7. localeData.weekdaysParse(minShortOrLongWeekdayString);  // returns weekday id (0 to 6) of input
  8. localeData.longDateFormat(dateFormat);  // returns the full format of abbreviated date-time formats LT, L, LL and so on
  9. localeData.isPM(amPmString);  // returns true iff amPmString represents PM
  10. localeData.meridiem(hours, minutes, isLower);  // returns am/pm string for particular time-of-day in upper/lower case
  11. localeData.calendar(key, aMoment);  // returns a format that would be used for calendar representation. Key is one of 'sameDay', 'nextDay', 'lastDay', 'nextWeek', 'prevWeek', 'sameElse'
  12. localeData.relativeTime(number, withoutSuffix, key, isFuture);  // returns relative time string, key is on of 's', 'm', 'mm', 'h', 'hh', 'd', 'dd', 'M', 'MM', 'y', 'yy'. Single letter when number is 1.
  13. localeData.pastFuture(diff, relTime);  // convert relTime string to past or future string depending on diff
  14. localeData.ordinal(number);  // convert number to ordinal string 1 -> 1st
  15. localeData.preparse(str);  // called before parsing on every input string
  16. localeData.postformat(str);  // called after formatting on every string
  17. localeData.week(aMoment);  // returns week-of-year of aMoment
  18. localeData.invalidDate();  // returns a translation of 'Invalid date'
  19. localeData.firstDayOfWeek();  // 0-6 (Sunday to Saturday)
  20. localeData.firstDayOfYear();  // 0-15 Used to determine first week of the year.

Details about firstDayOfYear can be found in the customization section.

Pseudo Locale2.13.0+

  1. moment.locale('x-pseudo')

As of version 2.13.0 moment optionally includes a pseudo locale. This locale will populate the dates with very obviously changed data.Pseudo locales can be useful when testing, as they make obvious what data has and has not been localized. Just include the pseudo-locale, and set moment's locale to x-pseudo.Text from Moment will be very easy to spot.

  1. moment.locale('x-pseudo');
  2. moment().format('LLL'); //14 F~ébrú~árý 2010 15:25
  3. moment().fromNow(); //'á ~féw ~sécó~ñds á~gó'
  4. moment().calendar(); //'T~ódá~ý át 02:00'