国际化

目前的默认文案是中文,如果需要使用其他语言,可以在初始化时进行配置,也可以在运行中随时修改,可以参考下面的方案。 你也可以在新建项目时通过 ng add ng-zorro-antd 设置国际化语言。

配置默认国际化语言#

ng-zorro-antd 提供了几个配置型 token 用于全局配置国际化文案和日期,NZ_I18N用于国际化文案,NZ_DATE_CONFIG用于修改日期相关特性。 此外,我们默认使用 Angular 的语言包来进行日期格式化(需要引入相应的 Angular 语言包)。

另外,我们还提供了可选的 NZ_DATE_LOCALE 用于 date-fns 方式来格式化本地日期(依赖 date-fns 库,详见下方的如何使用 date-fns 进行日期格式化)。

/** 导入需要使用的 Angular 语言包 **/
import { registerLocaleData } from '@angular/common';
import en from '@angular/common/locales/en';
registerLocaleData(en);

/** 配置 ng-zorro-antd 国际化 **/
import { provideNzI18n, en_US } from 'ng-zorro-antd/i18n';

/** 静态配置 **/
export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideNzI18n(en_US)
  ]
}

与 Angular 应用本地化方案联动#

当使用 Angular 应用本地化方案 时,可以根据 LOCALE_ID 自动切换 ng-zorro-antd 默认语言

/** 导入需要使用的语言包 **/
import { LOCALE_ID } from '@angular/core';
import { registerLocaleData } from '@angular/common';
import en from '@angular/common/locales/en';
import zh from '@angular/common/locales/zh';
registerLocaleData(en);
registerLocaleData(zh);

/** 配置 ng-zorro-antd 国际化 **/
import { en_US, NZ_I18N, zh_CN } from 'ng-zorro-antd/i18n';

/** 根据 LOCALE_ID 自动切换 ng-zorro-antd 语言 **/
export const appConfig: ApplicationConfig = {
  providers   : [{
    provide: NZ_I18N,
    useFactory: () => {
      const localId = inject(LOCALE_ID);
      switch (localId) {
        case 'en':
          return en_US;
        /** 与 angular.json i18n/locales 配置一致 **/
        case 'zh':
          return zh_CN;
        default:
          return en_US;
      }
    }
  }]
}

运行时修改#

ng-zorro-antd 提供了 NzI18nService 服务用于动态修改国际化文案。

import { en_US, NzI18nService } from 'ng-zorro-antd/i18n';

class SomeComponent {
  private i18n = inject(NzI18nService);

  switchLanguage() {
    this.i18n.setLocale(en_US);
  }
}

注意:en_US 是语言包名称,以下表格也遵循同样的规则。

支持语言#

语言包名语言
ar_EG阿拉伯
az_AZ阿塞拜疆
bg_BG保加利亚语
bn_BD孟加拉语(孟加拉国)
by_BY白俄罗斯语
ca_ES加泰罗尼亚语
cs_CZ捷克语
da_DK丹麦语
de_DE德语
el_GR希腊语
en_AU英语(澳大利亚)
en_GB英语
en_US英语(美式)
es_ES西班牙语
et_EE爱沙尼亚语
fa_IR波斯语
fi_FI芬兰语
fr_BE法语(比利时)
fr_CA法语(加拿大)
fr_FR法语
ga_IE爱尔兰盖尔语
gl_ES加利西亚语(西班牙)
he_IL希伯来语
hi_IN印地语
hr_HR克罗地亚语
hu_HU匈牙利
hy_AM亚美尼亚
id_ID印度尼西亚语
is_IS冰岛语
it_IT意大利语
ja_JP日语
ka_GE格鲁吉亚语
kk_KZ哈萨克语
km_KH高棉语
kmr_IQ北库尔德语
kn_IN卡纳达语
ko_KR韩语/朝鲜语
ku_IQ库尔德语
lt_LT立陶宛语
lv_LV拉脱维亚语
ml_IN马拉雅拉姆语
mn_MN蒙古语
ms_MY马来语
nb_NO挪威
ne_NP尼泊尔语
nl_BE荷兰语(比利时)
nl_NL荷兰语
pl_PL波兰语
pt_BR葡萄牙语(巴西)
pt_PT葡萄牙语
ro_RO罗马尼亚语
ru_RU俄罗斯语
sk_SK斯洛伐克语
sl_SI斯洛文尼亚
sr_RS塞尔维亚
sv_SE瑞典语
ta_IN泰米尔语
th_TH泰语
tr_TR土耳其语
uk_UA乌克兰语
ur_PK乌尔都语 (巴基斯坦)
vi_VN越南语
zh_CN简体中文
zh_HK繁体中文
zh_TW繁体中文

如何使用 date-fns 进行日期格式化#

对于日期的格式化,我们默认采用 Angular 的 DatePipe(语法参考来实现(依赖Angular的locale语言包),但由于Angular自带的DatePipe并非按照ISO标准算法实现(issue #25380),使用时周数的展示可能与预期不符(相关issue: #2406, #2819)。

所以我们新提供了date-fns方式(语法参考)来进行标准的日期格式化,您可以通过以下方式切换至 date-fns(切换后将影响所有日期类组件如Calendar/DatePicker的日期格式化):

// 在 App Config 中设置 NZ_DATE_LOCALE 的值,将激活 date-fns 方式的日期格式化展示
import { enUS, ja } from 'date-fns/locale';

export const appConfig: ApplicationConfig = {
  providers: [
    { provide: NZ_DATE_LOCALE, useValue: enUS }
  ]
}

// 运行时切换语言为日语
import { NzI18nService } from 'ng-zorro-antd/i18n';

export class AppComponent{
  private i18n = inject(NzI18nService);

  switchLanguage() {
    this.i18n.setDateLocale(ja);
  }
}

切换成功后,可以选择移除掉对 Angular Locales 包的依赖(删除下方代码)来减小打包体积(前提是代码对其无依赖):

// 以下代码可根据需要移除
import { registerLocaleData } from '@angular/common';
import en from '@angular/common/locales/en';
registerLocaleData(en);

NZ_DATE_CONFIG 日期全局配置#

默认配置如下:

{
  /** 指定哪一天为一周的开始(null表示采用内部默认值,0表示星期日,1表示星期一,以此类推) */
  firstDayOfWeek: null
}

date-fns 支持语言#

https://date-fns.org/docs/I18n#supported-languages

如何更改默认国际化语言包配置#

ng-zorro 中有些组件的文本依赖于国际化文本,例如 nz-pagination 中的 size changer, 这时候你可以修改国际化配置来更改 size changer 中的文本内容:

import { en_US, provideNzI18n } from 'ng-zorro-antd/i18n';

const customLanguagePack = {
  en_US,
  ...{
    Pagination: {
      items_per_page: "per page"
    }
  }
}

export const appConfig: ApplicationConfig = {
  providers: [
    provideNzI18n(customLanguagePack)
  ]
}