fix: Allow customizing "am" / "pm" strings with locale meridiem function (#580)

* fix: Allow customizing "am" / "pm" strings with locale meridiem function

fix #578

* test: Add meridiem test

* docs: Update meridiem docs

Author: iamkun

docs/en/I18n.md

@@ -122,6 +122,10 @@ const localeObject = {
     MM: '%d months',
     y: 'a year',
     yy: '%d years'
+  },
+  meridiem: (hour, minute, isLowercase) => {
+    // OPTIONAL, AM/PM
+    return hour > 12 ? 'PM' : 'AM'
   }
 }
 ```

docs/es-es/I18n.md

@@ -111,6 +111,10 @@ const localeObject = {
     MM: '%d months',
     y: 'a year',
     yy: '%d years'
+  },
+  meridiem: (hour, minute, isLowercase) => {
+    // OPTIONAL, AM/PM
+    return hour > 12 ? 'PM' : 'AM'
   }
 }
 ```

docs/ja/I18n.md

@@ -108,6 +108,10 @@ const localeObject = {
     MM: '%d months',
     y: 'a year',
     yy: '%d years'
+  },
+  meridiem: (hour, minute, isLowercase) => {
+    // OPTIONAL, AM/PM
+    return hour > 12 ? 'PM' : 'AM'
   }
 }
 ```

docs/ko/I18n.md

@@ -107,6 +107,10 @@ const localeObject = {
     MM: '%d months',
     y: 'a year',
     yy: '%d years'
+  },
+  meridiem: (hour, minute, isLowercase) => {
+    // OPTIONAL, AM/PM
+    return hour > 12 ? 'PM' : 'AM'
   }
 }
 ```

docs/pt-br/I18n.md

@@ -122,6 +122,10 @@ const objetoLocale = {
     MM: '%d months',
     y: 'a year',
     yy: '%d years'
+  },
+  meridiem: (hour, minute, isLowercase) => {
+    // OPTIONAL, AM/PM
+    return hour > 12 ? 'PM' : 'AM'
   }
 }
 ```

docs/zh-cn/I18n.md

@@ -108,6 +108,10 @@ const localeObject = {
     MM: '%d months',
     y: 'a year',
     yy: '%d years'
+  },
+  meridiem: (hour, minute, isLowercase) => {
+    // 可选, AM/PM
+    return hour > 12 ? '下午' : '上午'
   }
 }
 ```

src/index.js

@@ -279,7 +279,7 @@ class Dayjs {
     const zoneStr = Utils.z(this)
     const locale = this.$locale()
     const {
-      weekdays, months
+      weekdays, months, meridiem
     } = locale
     const getShort = (arr, index, full, length) => (
       (arr && arr[index]) || full[index].substr(0, length)
@@ -288,6 +288,11 @@ class Dayjs {
       Utils.s(this.$H % 12 || 12, num, '0')
     )
 
+    const meridiemFunc = meridiem || ((hour, minute, isLowercase) => {
+      const m = (hour < 12 ? 'AM' : 'PM')
+      return isLowercase ? m.toLowerCase() : m
+    })
+
     const matches = {
       YY: String(this.$y).slice(-2),
       YYYY: String(this.$y),
@@ -305,8 +310,8 @@ class Dayjs {
       HH: Utils.s(this.$H, 2, '0'),
       h: get$H(1),
       hh: get$H(2),
-      a: this.$H < 12 ? 'am' : 'pm',
-      A: this.$H < 12 ? 'AM' : 'PM',
+      a: meridiemFunc(this.$H, this.$m, true),
+      A: meridiemFunc(this.$H, this.$m, false),
       m: String(this.$m),
       mm: Utils.s(this.$m, 2, '0'),
       s: String(this.$s),

src/locale/ja.js

@@ -19,6 +19,7 @@ const locale = {
     lll: 'YYYY年M月D日 HH:mm',
     llll: 'YYYY年M月D日(ddd) HH:mm'
   },
+  meridiem: hour => (hour < 12 ? '午前' : '午後'),
   relativeTime: {
     future: '%s後',
     past: '%s前',

test/display.test.js

@@ -2,6 +2,7 @@ import moment from 'moment'
 import MockDate from 'mockdate'
 import dayjs from '../src'
 import th from '../src/locale/th'
+import '../src/locale/ja'
 
 beforeEach(() => {
   MockDate.set(new Date())
@@ -77,12 +78,18 @@ it('Format meridiens a A am / pm', () => {
   expect(dayjs(time).format('a')).toBe(moment(time).format('a'))
   expect(dayjs(time).format('A')).toBe('AM')
   expect(dayjs(time).format('A')).toBe(moment(time).format('A'))
+  expect(dayjs(time).locale('ja').format('a')).toBe('午前')
+  expect(dayjs(time).locale('ja').format('a'))
+    .toBe(moment(time).locale('ja').format('a'))
 
   const time2 = '2018-05-02T23:00:00.000'
   expect(dayjs(time2).format('a')).toBe('pm')
   expect(dayjs(time2).format('a')).toBe(moment(time2).format('a'))
   expect(dayjs(time2).format('A')).toBe('PM')
   expect(dayjs(time2).format('A')).toBe(moment(time2).format('A'))
+  expect(dayjs(time2).locale('ja').format('a')).toBe('午後')
+  expect(dayjs(time2).locale('ja').format('a'))
+    .toBe(moment(time2).locale('ja').format('a'))
 })
 
 it('Format Minute m mm', () => {

test/locale/keys.test.js

@@ -27,7 +27,8 @@ it('Locale keys', () => {
       weekdaysShort,
       monthsShort,
       weekdaysMin,
-      weekStart
+      weekStart,
+      meridiem
     } = locale.content
 
     expect(name).toEqual(locale.name.replace('.js', ''))
@@ -80,5 +81,11 @@ it('Locale keys', () => {
         'past', 's', 'y', 'yy']
         .sort())
     }
+
+    if (meridiem) {
+      for (let i = 1; i <= 23; i += 1) {
+        expect(meridiem(i)).toEqual(expect.anything())
+      }
+    }
   })
 })