@bigbear713/nb-trans v17.0.0

@bigbear713/nb-trans

Angular translation lib by bigBear713.

OnlineDemo

Bug Report

Feature Request

Document

• 中文
• English

Changelog

• 中文
• English

Feature

• 支持翻译文本懒加载，或者急性加载；
• 支持切换语言时，不刷新页面自动更新翻译文本；
• 支持设置翻译文本加载失败时的重试次数；
• 支持翻译文本中带有参数；
• 支持翻译文本中带有组件的复杂场景；
• 支持组件的更新策略为ChangeDetectionStrategy.OnPush;
• 支持在standalone component中使用；
• 支持以standalone component的方式引入;

Version

nb-trans的大版本和Angular的大版本保持对应关系

Installation

$ npm i @bigbear713/nb-trans
// or
$ yarn add @bigbear713/nb-trans

API

Module

NbTransModule

多语言模块。引入该模块后，可使用component，pipe。service不需要引入该模块也可使用，默认为全局。

NbTransTestingModule

多语言测试模块。用于Unit Test。

Services

NbTransService

v12.0.0

提供多语言翻译功能的service

Properties

Methods

Usage

constructor(private transService: NbTransService) {}

// 切换语言，异步事件，subscribe()是必需的
this.transService.changeLang(lang).subscribe(result=>{
    // result是切换后的结果
});

// 切换语言，同步事件，但不保证语言切换成功
this.transService.changeLangSync(lang);

NbTransService.transService.getBrowserLang(); // 'en'

NbTransService.transService.getBrowserLangs(); // ['en']

// 语言异步翻译。可订阅获取翻译后的值，也可在模板中和async管道结合使用
const trans$ = this.transService.translationAsync('title');
trans$.subscribe(trans=>{
    // trans是翻译后的文本
});

// 语言同步翻译。获取当前语言下的翻译内容
const trans = this.transService.translationSync('title'); // trans是翻译后的文本

// 语言切换订阅。当语言被切换时，会触发订阅事件，得到切换后的语言
this.transService.subscribeLangChange().subscribe(lang=>{
      // lang是切换后的语言值
});

// 默认语言翻译文本加载结束订阅事件。当翻译文本被加载完成时，会触发订阅事件
this.transService.subscribeLoadDefaultOver().subscribe(over=>{
      // over是加载后的结果
});

Components

<nb-trans></nb-trans>

v12.0.0

从v15.1.0开始为standalone component

当翻译文本中含有组件等复杂场景时使用的组件。当语言被切换时，组件渲染的内容将自动更新

Input

Usage

<!-- If the key is missing, an error will be reported -->
<nb-trans />
<!-- only trans key -->
<nb-trans key="title" />
<nb-trans [key]="transKey" />

<!-- trans key and options -->
<nb-trans key="title" [options]="options" />
<nb-trans key="helloWorld" [options]="({prefix:'content'})" />

<!-- trans key, options and components -->
<nb-trans [key]="complexContent" [options]="options" [components]="[com1,com2]" />
<ng-template #comp1 let-compContent="content">
  <span>{{compContent}}</span>
</ng-template>
<ng-template #comp2 let-compContent="content" let-compList="list">
  <ng-container *ngTemplateOutlet="compContent,context:{list}" />
</ng-template>

// v15.1.0新增
// 在NgModule中引入
@NgModule({
  imports:[NbTransComponent],
  // ...
})
export class XXXModule{}

// 在standalone component中引入
@Component({
  standalone:true,
  imports:[NbTransComponent],
  // ...
})
export class XXXComponent{}

[nb-trans]

v16.0.0

当翻译文本中含有组件等复杂场景时使用的组件。当不想使用"\<nb-trans \/>"标签元素，而是自己选择原生html标签时使用，比如"\<div \/>","\<span \/>"。当语言被切换时，组件渲染的内容将自动更新。

Input

Usage

<!-- only trans key -->
<div nb-trans="title"></div>
<div [nb-trans]="transKey"></div>
<!-- other native html tags -->
<span [nb-trans]="transKey"></span>
<p [nb-trans]="transKey"></p>
<h2 [nb-trans]="transKey"></h2>

<!-- trans key and options -->
<div nb-trans="title" [nb-trans-options]="options"></div>
<div nb-trans="helloWorld" [nb-trans-options]="({prefix:'content'})"></div>

<!-- trans key, options and components -->
<div [nb-trans]="complexContent" [nb-trans-options]="options" [nb-trans-components]="[com1,com2]"></div>
<ng-template #comp1 let-compContent="content">
  <span>{{compContent}}</span>
</ng-template>
<ng-template #comp2 let-compContent="content" let-compList="list">
  <ng-container *ngTemplateOutlet="compContent,context:{list}" />
</ng-template>

// imported in NgModule
@NgModule({
  imports:[NbTrans2Component],
  // ...
})
export class XXXModule{}

// imported in standalone component
@Component({
  standalone:true,
  imports:[NbTrans2Component],
  // ...
})
export class XXXComponent{}

[nb-trans-subcontent]

v12.0.0

从v15.1.0开始为standalone component

当翻译文本中含有组件嵌套时使用的一种官方提供的方案(可根据需要有自己的实现方式)，会将嵌套的组件内容渲染出来。selector为attribute，可用于<div />, <span />, <a />，<ng-container />等。该组件是搭配<nb-trans></nb-trans>使用，请勿单独使用。

Input

Usage

<!-- 和配合<nb-trans></nb-trans>使用 -->
<!-- 示例：这是一个句子：<0>组件1</0>.<1> <0>组件2中的组件1</0> 组件2的其他部分 </1>.<2>组件3</2> -->
<nb-trans [key]="complexContent" [components]="[comp1,comp2,comp3]" />
<ng-template #comp1 let-comContent="content" let-list="list">
  <b [nb-trans-subcontent]="comContent" [subcontentList]="list"></b>
</ng-template>
<ng-template #comp2 let-comContent="content" let-list="list">
  <app-widget [comContent]="comContent" [list]="list" />
</ng-template>
<ng-template #comp3 let-comContent="content">
  <b>{{comContent}}</b>
</ng-template>

// v15.1.0新增
// 在NgModule中引入
@NgModule({
  imports:[NbTransSubcontentComponent],
  // ...
})
export class XXXModule{}

// 在standalone component中引入
@Component({
  standalone:true,
  imports:[NbTransSubcontentComponent],
  // ...
})
export class XXXComponent{}

Pipes

nbTrans: transform(key: string, options?: INbTransOptions): string

v12.0.0

从v15.1.0开始为standalone component

翻译文本的管道，可用于在模版中根据key值翻译文本。当语言被切换时，组件渲染的内容将自动更新

Params

Return

Usage

<!-- only key param -->
<div>{{'title'|nbTrans}}</div>

<!-- key and options params -->
<div>{{'title'|nbTrans:options}}</div>
<div>{{'helloWorld'|nbTrans:({prefix:'content'})}}</div>

// v15.1.0新增
// 在NgModule中引入
@NgModule({
  imports:[NbTransPipe],
  // ...
})
export class XXXModule{}

// 在standalone component中引入
@Component({
  standalone:true,
  imports:[NbTransPipe],
  // ...
})
export class XXXComponent{}

Tokens

NB_TRANS_DEFAULT_LANG

string

v12.0.0

用于设置默认语言，初始化NbTransService实例时将自动加载该语言的文本内容。不设置时默认为NbTransLang.ZH_CN。一般只在AppModule设置一次

Usage

  providers: [
    // ...
    {
      provide: NB_TRANS_DEFAULT_LANG,
      useValue: NbTransLang.ZH_CN,
    },
    // ...
  ]

NB_TRANS_LOADER

{ key: string: INbTransLoader }

v12.0.0

翻译文本加载器。加载器支持急性加载和懒加载。一般只在AppModule设置一次

• 急性加载：直接引入翻译文本内容，作为值赋给对应的语言。急性加载会增大项目初始化文件的体积.
• 懒加载：通过http.get()或者import()等方式加载翻译文本文件。当翻译文本文件为json格式时，可使用http.get()加载。当翻译文本文件为ts格式时，可使用import()加载。

Usage

急性加载

  providers: [
    // ...
    {
      provide: NB_TRANS_LOADER,
      useValue: {
        [NbTransLang.ZH_CN]: zhCNTrans,
        [NbTransLang.EN]: enTrans,
      }
    }
    // ...
  ]

懒加载

• 翻译文本文件为json格式

  providers: [
    // ...
    {
      provide: NB_TRANS_LOADER,
      useFactory: (http: HttpClient) => ({
        // dyn load and the content is a json file
        // the loader fn return value can be Observable<Object>/Promise<Object> type
        // [NbTransLang.EN]: () => http.get('./assets/localization/en/translations.json').toPromise(),
        [NbTransLang.EN]: () => http.get('./assets/localization/en/translations.json'),
        // [NbTransLang.ZH_CN]: () => http.get('./assets/localization/zh-CN/translations.json').toPromise(),
        [NbTransLang.ZH_CN]: () => http.get('./assets/localization/zh-CN/translations.json'),
      }),
      deps: [HttpClient]
    }
    // ...
  ]

• 翻译文本文件为ts格式

  providers: [
    // ...
    {
      provide: NB_TRANS_LOADER,
      useValue: {
        [NbTransLang.EN]: () => import('./localization/en/translations').then(data => data.trans),
        [NbTransLang.ZH_CN]: () => import('./localization/zh-CN/translations').then(data => data.trans),
      }
    }
    // ...
  ]

NB_TRANS_MAX_RETRY

number

v15.0.0

NB_TRANS_MAX_RETRY_TOKEN

number

v12.0.0, 从v15.0.0开始为@deprecated

翻译文本加载失败时的最大重试次数，默认为5次。一般只在AppModule设置一次

Usage

  providers: [
    // ...
    {
      provide: NB_TRANS_MAX_RETRY,
      useValue: 3
    },
    // ...
  ]

NB_TRANS_PARAM_KEY_INVALID_WARNING

boolean

v16.0.0

当 param key 不符合规则时，是否在 console 中打印警告信息。默认为 true。在生产环境下（调用enableProdMode()时，也将处于生产模式），将自动关闭打印警告信息的设置。

Usage

  providers: [
    // ...
    {
      provide: NB_TRANS_PARAM_KEY_INVALID_WARNING,
      useValue: false
    },
    // ...
  ]

Interfaces

INbTransLoader

v12.0.0

文本加载器

INbTransOptions

v12.0.0

翻译配置

INbTransParams

v12.0.0

注意：param key 的命名规则

• 自v16.0.0起：

1. 由 字母，数字，_和$组成；
2. 数字不能是第一个字符；

翻译文本中的参数

INbTransChangeLang

v12.0.0

切换语言的结果

INbTransSentencePart

v12.0.0

句子部分，可能为string或者INbTransSentenceCompPart类型。为string时，即该句子为文本；为INbTransSentenceCompPart时，即该句子中含有需要解析的组件。一般交给组件自己处理便可，可不用关心内部逻辑

INbTransSentenceCompPart

v12.0.0

句子中含有组件的部分

Enums

NbTransLang

v15.0.0

NbTransLangEnum

v12.0.0, 从v15.0.0开始为@deprecated

常用语言枚举。除了默认语言未设置时的默认值外，组件以及服务中均未直接使用该枚举中的值，所以不强制要求使用该枚举。

NbTransSentenceItem

v15.0.0

NbTransSentenceItemEnum

v12.0.0, 从v15.0.0开始为@deprecated

句子项类型枚举。在对句子内容进行解析时，会将句子分为STR,COMP和MULTI_COMP这3种类型

贡献

欢迎提feature和PR，一起使该项目更好

License

MIT