Attention
该组件已经废弃,将不再推出v16
版本,v15
是最后一个版本。推荐您使用@bigbear713/nb-trans
或者其他多语言组件库.
Document
Feature
支持翻译文本懒加载,或者急性加载;
支持切换语言时,不刷新页面自动更新翻译文本;
支持设置翻译文本加载失败时的重试次数;
支持翻译文本中带有参数;
支持翻译文本中带有组件的复杂场景;
支持组件的更新策略为ChangeDetectionStrategy.OnPush
;
支持在standalone component
中使用;
Version
ng-trans的大版本和Angular的大版本保持对应关系
"@bigbear713/ng-trans":"^12.0.0" - "@angular/core": "^12.0.0"
"@bigbear713/ng-trans":"^13.0.0" - "@angular/core": "^13.0.0"
"@bigbear713/ng-trans":"^14.0.0" - "@angular/core": "^14.0.0"
"@bigbear713/nb-trans":"^15.0.0" - "@angular/core": "^15.0.0"
Installation
$ npm i @bigbear713/ng-trans
// or
$ yarn add @bigbear713/ng-trans
Module
NgTransModule
多语言模块。引入该模块后,可使用component
,pipe
。service
不需要引入该模块也可使用,默认为全局。
NgTransTestingModule
多语言测试模块。用于Unit Test。
Service
NgTransService
v12.0.0
提供多语言翻译功能的service
Properties
Properties
Type
Description
Version
lang
string
当前语言值
v12.0.0
loadDefaultOver
boolean
默认语言的翻译文本是否加载完毕
v12.0.0
Methods
Name
Return
Description
Scenes
Version
changeLang(lang: string)
Observable<INgTransChangeLang>
切换语言。lang参数需要和NG_TRANS_LOADER
中的key值相对应。是一个观察者异步事件。当切换的语言的翻译文本被加载完成后才会返回结果。订阅后无需取消订阅,因为当语言切换后(不管是否成功),将自动complete。结果的具体内容见下方INgTransChangeLang
的定义
需要切换语言时
v12.0.0
changeLangSync(lang: string)
void
切换语言。lang参数需要和NG_TRANS_LOADER
中的key值相对应。是一个同步事件。但是并不保证语言切换成功,以及何时成功。
适合只想触发切换语言操作,并不关心切换后的结果的场景
v12.0.0
getBrowserLang()
string | undefined
获取浏览器的首选语言
适合只关心浏览器界面语言的场景
v12.1.0
getBrowserLangs()
readonly string[]| undefined
返回一个用户已知语言的数组,并按照优先级排列
适合需要知道用户已知语言的场景
v12.1.0
translationAsync(key: string, options?: INgTransOptions)
Observable<string>
根据key和options异步获取翻译文本。options选填,具体配置见下方INgTransOptions
定义。返回一个观察者对象。获取值后如果未取消订阅,当语言被切换时,将会订阅、获取切换后的语言下的翻译文本
适合将订阅事件变量在模板中使用,推荐结合ng官方的async
管道使用。
v12.0.0
translationSync(key: string, options?: INgTransOptions)
string
根据key和options同步获取翻译文本。options选填,具体配置见下方INgTransOptions
定义。因为是同步获取,所以返回的获取后的文本内容。当语言被切换时,需要重新调用该方法才能获取切换后的语言下的文本。
适合文本内容临时使用,每次显示文本都需要重新获取的场景。比如通过service动态创建modal时,设置modal的title。
v12.0.0
subscribeLangChange()
Observable<string>
语言切换的订阅事件。返回一个观察者对象。当订阅未取消时,语言被切换时,会自动被订阅到。订阅的内容为切换后的语言值
适合需要根据不同语言进行动态调整的地方
v12.0.0
subscribeLoadDefaultOver()
Observable<boolean>
默认语言翻译文本是否加载完成的订阅事件。加载成功时订阅到的值为true,反之为false。加载完成后(不管是否加载成功)会自动complete,因此可以不用取消订阅
适合整个项目最外层的数据准备。当默认语言的翻译文本被加载完成后再显示整个项目,体验效果更好.
v12.0.0
Usage
constructor ( private transService : NgTransService ) { }
// 切换语言,异步事件,subscribe()是必需的
this . transService . changeLang ( lang ) . subscribe ( result => {
// result是切换后的结果
} ) ;
// 切换语言,同步事件,但不保证语言切换成功
this . transService . changeLangSync ( lang ) ;
// 语言异步翻译。可订阅获取翻译后的值,也可在模板中和async管道结合使用
const trans$ = this . transService . translationAsync ( 'title' ) ;
trans$ . subscribe ( trans => {
// trans是翻译后的文本
} ) ;
this . transService . getBrowserLang ( ) ; // 'en'
this . transService . getBrowserLangs ( ) ; // ['en']
// 语言同步翻译。获取当前语言下的翻译内容
const trans = this . transService . translationSync ( 'title' ) ; // trans是翻译后的文本
// 语言切换订阅。当语言被切换时,会触发订阅事件,得到切换后的语言
this . transService . subscribeLangChange ( ) . subscribe ( lang => {
// lang是切换后的语言值
} ) ;
// 默认语言翻译文本加载结束订阅事件。当翻译文本被加载完成时,会触发订阅事件
this . transService . subscribeLoadDefaultOver ( ) . subscribe ( over => {
// over是加载后的结果
} ) ;
Component
<ng-trans></ng-trans>
v12.0.0
当翻译文本中含有组件等复杂场景时使用的组件。当语言被切换时,组件渲染的内容将自动更新
Input
Name
Type
Default
Description
Version
components
TemplateRef<{ content: string | TemplateRef<any>; list?: INgTransSentencePart[] }>[]
[]
翻译文本中的对应的组件。
v12.0.0
key
string
''
获取翻译文本的key值
v12.0.0
options
INgTransOptions
{}
翻译的配置信息。具体配置见下方的INgTransOptions
定义。
v12.0.0
Usage
<!-- only trans key -->
< ng-trans key ="title "> </ ng-trans >
< ng-trans [key] ="transKey "> </ ng-trans >
<!-- trans key and options -->
< ng-trans key ="title " [options] ="options "> </ ng-trans >
< ng-trans key ="helloWorld " [options] ="({prefix:'content'}) "> </ ng-trans >
<!-- trans key, options and components -->
< ng-trans [key] ="complexContent " [options] ="options " [components] ="[com1,com2] "> </ ng-trans >
< 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-container >
</ ng-template >
[ng-trans-subcontent]
v12.0.0
当翻译文本中含有组件嵌套时使用的一种官方提供的方案(可根据需要有自己的实现方式),会将嵌套的组件内容渲染出来。selector为attribute,可用于<div />
, <span />
, <a />
,<ng-container />
等。该组件是搭配<ng-trans></ng-trans>
使用,请勿单独使用。
Input
Name
Type
Default
Description
Version
ng-trans-subcontent
string | TemplateRef<any>
''
要显示的子内容。接受string
类型和TemplateRef
类型。当为string
类型时,直接渲染出来,trans-subcontent-list
输入参数不起作用。当为TemplateRef
类型时,trans-subcontent-list
参数将起作用。
v12.0.0
trans-subcontent-list
INgTransSentencePart[]
[]
仅当ng-trans-subcontent
为TemplateRef
类型时,且该内容为<ng-trans></ng-trans>
的components输入属性的子内容时有效。[ng-trans-subcontent]
会将该参数的值传到template的context中。详情见下方Usage
v12.0.0
Usage
<!-- 和配合<ng-trans></ng-trans>使用 -->
<!-- 示例:这是一个句子:<0>组件1</0>.<1> <0>组件2中的组件1</0> 组件2的其他部分 </1>.<2>组件3</2> -->
< ng-trans [key] ="complexContent " [components] ="[comp1,comp2,comp3] "> </ ng-trans >
< ng-template #comp1 let-comContent ="content " let-list ="list ">
< b [nb-trans-subcontent] ="comContent " [trans-subcontent-list] ="list "> </ b >
</ ng-template >
< ng-template #comp2 let-comContent ="content " let-list ="list ">
< app-widget [comContent] ="comContent " [list] ="list "> </ app-widget >
</ ng-template >
< ng-template #comp3 let-comContent ="content ">
< b > {{comContent}}</ b >
</ ng-template >
Pipe
ngTrans: transform(key: string, options?: INgTransOptions): string
v12.0.0
翻译文本的管道,可用于在模版中根据key值翻译文本。当语言被切换时,组件渲染的内容将自动更新
Params
Name
Type
Mandatory
Description
Version
key
string
true
翻译文本的key值
v12.0.0
options
INgTransOptions
false
翻译配置。具体配置见下方的INgTransOptions
定义
v12.0.0
Return
Type
Description
string
翻译后的文本
Usage
<!-- only key param -->
< div > {{'title'|ngTrans}}</ div >
<!-- key and options params -->
< div > {{'title'|ngTrans:options}}</ div >
< div > {{'helloWorld'|ngTrans:({prefix:'content'})}}</ div >
Token
NG_TRANS_DEFAULT_LANG:
v12.0.0
用于设置默认语言,初始化NgTransService
实例时将自动加载该语言的文本内容。不设置时默认为NgTransLang.ZH_CN
。一般只在AppModule设置一次
Usage
providers: [
// ...
{
provide : NG_TRANS_DEFAULT_LANG ,
useValue : NgTransLang . ZH_CN ,
} ,
// ...
]
NG_TRANS_LOADER:
v12.0.0
翻译文本加载器。加载器支持急性加载和懒加载。一般只在AppModule设置一次
急性加载:直接引入翻译文本内容,作为值赋给对应的语言。急性加载会增大项目初始化文件的体积.
懒加载:通过http.get()
或者import()
等方式加载翻译文本文件。当翻译文本文件为json
格式时,可使用http.get()
加载。当翻译文本文件为ts
格式时,可使用import()
加载。
Usage
急性加载
providers: [
// ...
{
provide : NG_TRANS_LOADER ,
useValue : {
[ NgTransLang . ZH_CN ] : zhCNTrans ,
[ NgTransLang . EN ] : enTrans ,
}
}
// ...
]
懒加载
providers: [
// ...
{
provide : NG_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
// [NgTransLang.EN]: () => http.get('./assets/localization/en/translations.json').toPromise(),
[ NgTransLang . EN ] : ( ) => http . get ( './assets/localization/en/translations.json' ) ,
// [NgTransLang.ZH_CN]: () => http.get('./assets/localization/zh-CN/translations.json').toPromise(),
[ NgTransLang . ZH_CN ] : ( ) => http . get ( './assets/localization/zh-CN/translations.json' ) ,
} ) ,
deps : [ HttpClient ]
}
// ...
]
providers: [
// ...
{
provide : NG_TRANS_LOADER ,
useValue : {
[ NgTransLang . EN ] : ( ) => import ( './localization/en/translations' ) . then ( data => data . trans ) ,
[ NgTransLang . ZH_CN ] : ( ) => import ( './localization/zh-CN/translations' ) . then ( data => data . trans ) ,
}
}
// ...
]
NG_TRANS_MAX_RETRY:
v15.0.0
NG_TRANS_MAX_RETRY_TOKEN:
v12.0.0
, @deprecated
from v15.0.0
翻译文本加载失败时的最大重试次数,默认为5次。一般只在AppModule设置一次
Usage
providers: [
// ...
{
provide : NG_TRANS_MAX_RETRY ,
useValue : 3
} ,
// ...
]
WARN_DEPRECATED:
v15.0.0
WARN_DEPRECATED_TOKEN
v12.1.1
, @deprecated
from v15.0.0
本组件库将被弃用,使用时默认会在console输出警告信息。如果你不想在console看到这些警告信息,可在AppModule中设置该token为false。
Usage
providers: [
// ...
{
provide : WARN_DEPRECATED ,
useValue : false
} ,
// ...
]
Interface
INgTransLoader:
v12.0.0
文本加载器
Property
Type
Mandatory
Description
Version
[langKey: string]
Object | (() => (Observable<Object> | Promise<Object>))
false
key值为字符串类型,通常使用对应的语言的字符串值;value为含有文本的Object,或者返回含有文本的Object的Observable或者Promise
v12.0.0
INgTransOptions:
v12.0.0
翻译配置
Property
Type
Mandatory
Description
Version
prefix
string
false
key值的前缀。根据key值获取对应文本时,会自动将该值追加在key值之前,形成一个新的key值,并以此来获取文本
v12.0.0
params
INgTransParams
false
翻译文本中的参数。为key值为字符串,value值为字符串的对象
returnKeyWhenEmpty
boolean
false
当根据key值获取不到文本时,是否返回key值。默认为true。当显式设为false时,会返回空字符串
v12.0.0
INgTransParams:
v12.0.0
翻译文本中的参数
Property
Type
Mandatory
Description
Version
[key: string]
string
false
key值为字符串类型,value值为字符串类型
v12.0.0
INgTransChangeLang:
v12.0.0
切换语言的结果
Property
Type
Mandatory
Description
Version
result
boolean
true
切换语言的结果。切换成功时为true,否则为false
v12.0.0
curLang
string
true
当前语言。如果语言切换失败,则为切换前的语言;否则为切换后的语言
v12.0.0
INgTransSentencePart:
v12.0.0
句子部分,可能为string
或者INgTransSentenceCompPart
类型。为string
时,即该句子为文本;为INgTransSentenceCompPart
时,即该句子中含有需要解析的组件。一般交给组件自己处理便可,可不用关心内部逻辑
INgTransSentenceCompPart:
v12.0.0
句子中含有组件的部分
Property
Type
Mandatory
Description
Version
index
number
true
组件索引,用于匹配<ng-trans />
组件的components
输入属性中的组件
v12.0.0
content
string
true
翻译文本
v12.0.0
list
INgTransSentencePart[]
false
文本句子的解析部分
v12.0.0
Enum
NgTransLang:
v15.0.0
NgTransLangEnum:
v12.0.0
, @deprecated
from v15.0.0
常用语言枚举。除了默认语言未设置时的默认值外,组件以及服务中均未直接使用该枚举中的值,所以不强制要求使用该枚举。
NgTransSentenceItem:
v15.0.0
NgTransSentenceItemEnum:
v12.0.0
, @deprecated
from v15.0.0
句子项类型枚举。在对句子内容进行解析时,会将句子分为STR
,COMP
和MULTI_COMP
这3种类型
贡献
欢迎提feature和PR,一起使该项目更好
License
MIT