feat(locale): add createLocale to make locale customizable, closes #1525

CHANGELOG.en-US.md

@@ -14,6 +14,10 @@
 - `n-menu` 's `defaultExpandedKeys` use watchEffect initialize, closes [#1536](https://github.com/TuSimple/naive-ui/issues/1536).
 - `n-date-picker`'s `type` prop support `year` option.
 
+### i18n
+
+- Add `createLocale` to make locale customizable, closes [#1525](https://github.com/TuSimple/naive-ui/issues/1525).
+
 ## 2.20.2 (2021-11-05)
 
 ### Feats

CHANGELOG.zh-CN.md

@@ -14,6 +14,10 @@
 - `n-menu` 的 `defaultExpandedKeys` 使用 watchEffect 初始化，关闭 [#1536](https://github.com/TuSimple/naive-ui/issues/1536)
 - `n-date-picker` 属性 `type` 支持 `year` 选项
 
+### i18n
+
+- 新增 `createLocale` 方法允许用户自定义国际化，关闭 [#1525](https://github.com/TuSimple/naive-ui/issues/1525)
+
 ## 2.20.2 (2021-11-05)
 
 ### Feats

demo/pages/docs/i18n/enUS/index.md

@@ -8,13 +8,13 @@ Learn more about `n-config-provider`, see [Config Provider](../components/config
 
 ## Configure
 
-Set `n-config-provider`'s `locale` prop to `zhCN` imported from naive-ui to set Chinese theme inside `n-config-provider`.
+Set `n-config-provider`'s `locale` prop to `enUS` imported from naive-ui to set Chinese theme inside `n-config-provider`.
 
-Set `n-config-provider`'s `date-locale` prop to `dateZhCN` imported from naive-ui to set Chinese theme's date inside `n-config-provider`.
+Set `n-config-provider`'s `date-locale` prop to `dateEnUS` imported from naive-ui to set Chinese theme's date inside `n-config-provider`.
 
 ```html
 <template>
-  <n-config-provider :locale="zhCN" :date-locale="dateZhCN">
+  <n-config-provider :locale="enUS" :date-locale="dateEnUS">
     <app />
   </n-config-provider>
 </template>
@@ -22,7 +22,7 @@ Set `n-config-provider`'s `date-locale` prop to `dateZhCN` imported from naive-u
 <script>
   import { defineComponent } from 'vue'
   import { NConfigProvider } from 'naive-ui'
-  import { zhCN, dateZhCN } from 'naive-ui'
+  import { enUS, dateEnUS } from 'naive-ui'
 
   export default defineComponent({
     components: {
@@ -30,28 +30,63 @@ Set `n-config-provider`'s `date-locale` prop to `dateZhCN` imported from naive-u
     },
     setup() {
       return {
-        zhCN,
-        dateZhCN
+        enUS,
+        dateEnUS
       }
     }
   })
 </script>
-
-<style>
-  body {
-    background: black;
-  }
-</style>
 ```
 
 ## Supported languages
 
+PR is welcomed for locales that is not supported yet!
+
 | Language                  | Config | Date config |
 | ------------------------- | ------ | ----------- |
 | English                   | enUS   | dateEnUS    |
 | Japanese                  | jaJP   | dateJaJP    |
 | Russian                   | ruRU   | dateRuRU    |
 | Ukrainian                 | ukUA   | dateUkUA    |
-| Chinese (Simplified)      | zhCN   | dateZhCN    |
+| Chinese (Simplified)      | enUS   | dateEnUS    |
 | German - Germany          | deDE   | dateDeDe    |
 | Norwegian Bokmål (Norway) | nbNO   | dateNbNO    |
+
+## Customize the existing theme
+
+You can use `createLocale` to customize the existing theme.
+
+```html
+<template>
+  <n-config-provider :locale="locale" :date-locale="dateEnUS">
+    <app />
+  </n-config-provider>
+</template>
+
+<script>
+  import { defineComponent } from 'vue'
+  import { NConfigProvider, createLocale, enUS } from 'naive-ui'
+  import { enUS, dateEnUS } from 'naive-ui'
+
+  const customizedLocale = createLocale(
+    {
+      Input: {
+        placeholder: '不提申请不构成加班'
+      }
+    },
+    enUS
+  )
+
+  export default defineComponent({
+    components: {
+      NConfigProvider
+    },
+    setup() {
+      return {
+        locale: customizedLocale,
+        dateEnUS
+      }
+    }
+  })
+</script>
+```

demo/pages/docs/i18n/zhCN/index.md

@@ -36,16 +36,12 @@ Naive-ui 通过使用 `n-config-provider` 调整语言，默认情况下所有
     }
   })
 </script>
-
-<style>
-  body {
-    background: black;
-  }
-</style>
 ```
 
 ## 支持语言
 
+欢迎提交 PR 来支持尚未支持的语言。
+
 | 语言       | 配置 | 日期配置 |
 | ---------- | ---- | -------- |
 | 英语       | enUS | dateEnUS |
@@ -56,3 +52,42 @@ Naive-ui 通过使用 `n-config-provider` 调整语言，默认情况下所有
 | 印度尼西亚 | idID | dateIdID |
 | 德语       | deDE | dateDeDe |
 | 书面挪威语 | nbNO | dateNbNO |
+
+## 在现有国际化基础上调整
+
+你可以使用 `createLocale` 在现有国际化基础上调整。
+
+```html
+<template>
+  <n-config-provider :locale="locale" :date-locale="dateZhCN">
+    <app />
+  </n-config-provider>
+</template>
+
+<script>
+  import { defineComponent } from 'vue'
+  import { NConfigProvider, createLocale, zhCN } from 'naive-ui'
+  import { zhCN, dateZhCN } from 'naive-ui'
+
+  const customizedLocale = createLocale(
+    {
+      Input: {
+        placeholder: '不提申请不构成加班'
+      }
+    },
+    zhCN
+  )
+
+  export default defineComponent({
+    components: {
+      NConfigProvider
+    },
+    setup() {
+      return {
+        locale: customizedLocale,
+        dateZhCN
+      }
+    }
+  })
+</script>
+```

src/locales/index.spec.tsx

@@ -22,6 +22,7 @@ import {
   NLocale,
   NInput
 } from '../index'
+import { createLocale } from '.'
 
 const Wrapper = (props: {
   dateLocale: NDateLocale
@@ -37,6 +38,21 @@ const Wrapper = (props: {
 }
 
 describe('locale', () => {
+  it('works with createLocale', () => {
+    const locale1: NLocale = createLocale(
+      {
+        Select: {
+          placeholder: '???'
+        }
+      },
+      enUS
+    )
+    expect(locale1.Select.placeholder).toEqual('???')
+    locale1.Select.placeholder = enUS.Select.placeholder
+    expect(locale1).toEqual(enUS)
+    const locale2: NLocale = createLocale(enUS)
+    expect(locale2).toEqual(enUS)
+  })
   it('works', () => {
     expect(
       mount(Wrapper, {

src/locales/index.ts

@@ -16,3 +16,5 @@ export { default as dateDeDE } from './date/deDE'
 export { default as dateNbNO } from './date/nbNO'
 export type { NLocale } from './common/enUS'
 export type { NDateLocale } from './date/enUS'
+export type { NPartialLocale } from './utils/index'
+export { createLocale } from './utils/index'

src/locales/utils/index.ts

@@ -0,0 +1,20 @@
+import { merge } from 'lodash-es'
+import { NLocale } from '../common/enUS'
+
+export type NPartialLocale = {
+  [key in keyof NLocale]+?: {
+    [childKey in keyof NLocale[key]]+?: NLocale[key][childKey]
+  }
+}
+
+export function createLocale (locale: NLocale): NLocale
+export function createLocale (
+  locale: NPartialLocale,
+  fallbackLocale: NLocale
+): NLocale
+export function createLocale (
+  locale: NPartialLocale,
+  fallbackLocale?: NLocale
+): NLocale {
+  return merge({}, fallbackLocale, locale)
+}