Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gabrie-allaigre/ngx-easy-i18n-js
The easy internationalization (i18n) library for Angular
https://github.com/gabrie-allaigre/ngx-easy-i18n-js
Last synced: about 2 months ago
JSON representation
The easy internationalization (i18n) library for Angular
- Host: GitHub
- URL: https://github.com/gabrie-allaigre/ngx-easy-i18n-js
- Owner: gabrie-allaigre
- Created: 2022-11-30T15:35:09.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-10-08T14:14:14.000Z (2 months ago)
- Last Synced: 2024-10-08T16:29:34.100Z (2 months ago)
- Language: TypeScript
- Size: 2.48 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-angular - ngx-easy-i18n-js - The easy internationalization (i18n) library for Angular. (Table of contents / Angular)
- fucking-awesome-angular - ngx-easy-i18n-js - The easy internationalization (i18n) library for Angular. (Table of contents / Angular)
README
# ngx-easy-i18n-js
**Pure version angular for internalization (i18n).**
Translations are static. If you change language you must refresh the page or use bootstrap extension.
> Use EasyI18 Js library https://github.com/gabrie-allaigre/easy-i18n-js
## Download and Installation
Install using npm:
```shell
npm install easy-i18n-js @ngx-easy-i18n-js/core --save
```
Open angular.json and under allowedCommonJsDependencies add:
```json
"allowedCommonJsDependencies": [
"easy-i18n-js"
]
```
Usage in app.module.ts, add `imports`
```typescript
import localeFr from '@angular/common/locales/fr';
import localeEn from '@angular/common/locales/en';
imports: [
EasyI18nModule.forRoot({
options: {
logging: false
},
ngLocales: {
'fr': localeFr,
'en': localeEn,
},
defaultLanguage: 'en-US'
})
]
```
#### Configuration
```typescript
export interface EasyI18nModuleConfig {
// Options fo easy i18 js library
options?: EasyI18nOptions;
// Use specific loader
loader?: Provider;
// Add Angular locale import localeFr from '@angular/common/locales/fr';
ngLocales?: { [key: string]: any; };
// Use browser language
useBrowserLanguage?: boolean;
// Default fallback language use if current language not found
defaultLanguage?: string;
// exact only fr-FR, minimum only fr, all fr-FR and fr
discover?: 'exact' | 'minimum' | 'all';
}
```
In child module
```typescript
imports: [
EasyI18nModule
]
```
For change current locale use `EasyI18nService`
```typescript
export class MyComponent {
constructor(
private easyI18nService: EasyI18nService
) {
}
public doChangeLanguage(locale: string): void {
this.easyI18nService.registerCulture('fr');
}
}
```
Force reload if change culture
```typescript
this.easyI18nService.registerCulture('fr', { reload: true });
```
### Locale pipes
In HTML, uses locales pipes to get dates, numbers in locale format
| pipe | description | example |
|------------------|--------------------|-----------------------------------------------------|
| `localeDate` | Same as `date` | {{ mydate | localeDate:'short' }} |
| `localeNumber` | Same as `number` | {{ mydate | localeNumber }} |
| `localeCurrency` | Same as `currency` | {{ mydate | localeCurrency }} |
| `localePercent` | Same as `percent` | {{ mydate | localePercent }} |
### Translate
Main function for translate your language keys
#### HTML file
In HTML template, with pipe, parameter is TrOptions
```angular2html
{{ 'hello' | tr }}
{{ 'hello_with_genre' | tr: { gender: 'male' } }}
{{ 'My name is {}' | tr: { args: ['Gabriel'] } }}
```
**TrOptions arguments**
| Name | type | example |
|-----------|----------------------------------------------------|------------------------------------|
| args | `string[]` | `['Gabriel', '20']` |
| namedArgs | `{ [key: string]: string; } }` | `{ name : 'Gabriel', age : '20' }` |
| namespace | `string` | `'common'` |
| gender | 'male' | 'female' | 'other' | `gender: 'other'` |
**Directives**
There are 2 differents directives
First is simple, translate `[tr]`
| Directive | description | example |
|---------------|--------------------------------|------------------------------------------------------------------------------------|
| `tr` | Active directive translate | <span tr>hello</span> |
| `trNamespace` | Add namespace | <span tr trNamespace="common">hello</span> |
| `trKey` | Set key (if empty use content) | <span tr trKey="hello" trNamespace="common"></span> |
| `trGender` | Gender | <span tr trGender="male">hello_with_genre</span> |
| `trArgs` | Arguments | <span tr [trArgs]="['Gabriel']">hello</span> |
| `trNamedArgs` | Named arguments | <span tr [trNamedArgs]="{ name: 'Gabriel' }">hello</span> |
Second, use HTML named arguments `[trContent]`, replace `{namedArg}` with child element `*trElement`
| Directive | description |
|---------------|-----------------------------------------------|
| `trContent` | Active content directive translate, get a key |
| `trNamespace` | Add namespace |
| `trGender` | Gender |
| `trArgs` | Arguments |
| `trNamedArgs` | Named arguments |
| `demarc` | Change token start, end identifier |
**Examples**
```angular2html
Gabriel
```
```angular2html
Gabriel
{{ var_country }}
```
#### Typescript file
You can use extension methods of [String], you can also use tr() as a static function.
In typescript file, **there is no need to inject EasyI18nService**
```typescript
'hello'.tr();
'hello_with_genre'.tr({ gender: 'male' });
tr('hello');
tr('hello_with_genre', { gender: 'male' });
```
### Translate Plural
You can translate with pluralization. To insert a number in the translated string, use {}.
#### HTML file
In HTML template, with pipe, first parameter is number and second PluralOptions
```angular2html
{{ 'money' | plural:10 }}
{{ 'money_with_args' | plural:3: { args: ['Gabriel'] } }}
```
**PluralOptions arguments**
| Name | type | example |
|-------------------|----------------------------------------------------|------------------------------------|
| args | `string[]` | `['Gabriel', '20']` |
| namedArgs | `{ [key: string]: string; } }` | `{ name : 'Gabriel', age : '20' }` |
| namespace | `string` | `'common'` |
| name | `string` | `money` |
| numberFormatterFn | `(value: number) => string` | `(value) => value.Precision(3)` |
| gender | 'male' | 'female' | 'other' | `gender: 'other'` |
**Directives**
There are 2 different directives
First is simple, translate plural `[plural]`
| Directive | description | example |
|---------------------------|--------------------------------|---------------------------------------------------------------------------------------------------|
| `plural` | Active directive translate | <span [plural]="10">money</span> |
| `pluralNamespace` | Add namespace | <span [plural]="100" pluralNamespace="common">money</span> |
| `pluralKey` | Set key (if empty use content) | <span [plural]="100" pluralKey="money" pluralNamespace="common"></span> |
| `pluralGender` | Gender | <span [plural]="1" pluralGender="male">money_with_genre</span> |
| `pluralArgs` | Arguments | <span [plural]="5" [pluralArgs]="['Gabriel']">money</span> |
| `pluralNamedArgs` | Named arguments | <span [plural]="13" [pluralNamedArgs]="{ name: 'Gabriel' }">money</span> |
| `pluralName` | Name value | <span [plural]="4" pluralName="value">money</span> |
| `pluralNumberFormatterFn` | Formatter function | <span [plural]="10000" [pluralNumberFormatterFn]="myFn">money</span> |
Second, use HTML named arguments `[pluralContent]`, replace `{namedArg}` with child element `*pluralElement`
| Directive | description |
|---------------------------|-------------------------------------------------|
| `pluralContent` | Active content directive translate, get a key |
| `pluralValue` | Active content directive translate, get a value |
| `pluralNamespace` | Add namespace |
| `pluralGender` | Gender |
| `pluralArgs` | Arguments |
| `pluralNamedArgs` | Named arguments |
| `pluralName` | Name value |
| `pluralNumberFormatterFn` | Formatter function |
| `demarc` | Change token start, end identifier |
**Examples**
```angular2html
Gabriel
{{ var_money }}
```
#### Typescript file
You can use extension methods of [String], you can also use plural() as a static function.
In typescript file, **there is no need to inject EasyI18nService**
```typescript
'money_args'.plural(0, { args: ['Gabriel'] });
'money_args'.plural(1.5, { args: ['Gabriel'] });
plural('money_args', { args: ['Gabriel'] });
```
## Store
Default store is `EmptyEasyI18nStore`
Use `localStorage` store, usage in app.module.ts, add provider
```typescript
providers: [
{
provide: EasyI18nStore,
useFactory: () => new LocalStorageEasyI18nStore('current-lang')
}
]
```
## Add HttpLoader
### Standard
Load messages with `HttpClient`
Install using npm:
```shell
npm install @ngx-easy-i18n-js/http-loader --save
```
Usage in app.module.ts, add provider
```typescript
providers: [
{
provide: EasyI18nLoader,
deps: [HttpClient],
useFactory: (httpClient: HttpClient) => new HttpEasyI18nLoader(httpClient)
}
]
```
Change prefix or suffix with options
```typescript
new HttpEasyI18nLoader(httpClient, {
prefix: 'assets/',
suffix: '.json5'
});
```
```typescript
new HttpEasyI18nLoader(httpClient, {
prefix: ['assets/common/i18n', 'assets/i18n'],
suffix: '.json5'
});
```
### Scoped loader
Load multiples files with scope
Usage in app.module.ts, add provider
```typescript
providers: [
{
provide: EasyI18nLoader,
deps: [HttpClient],
useFactory: (httpClient: HttpClient) => new ScopedHttpEasyI18nLoader(httpClient, [
{ prefix: `/assets/i18n/` },
{ prefix: ['assets/common/i18n', 'assets/i18n/common'], scope: 'common' },
{ prefix: `/assets/i18n/errors/`, scope: 'errors' }
])
}
]
```
```angular2html
{{ 'common.save' | tr }}
{{ 'errors.internal_server_error' | tr }}
```
Change suffix
```typescript
new ScopedHttpEasyI18nLoader(httpClient, [
{ prefix: `/assets/i18n/` }
], {
suffix: '.json5'
});
```
Append scoped loader for lazy routes
```typescript
const routes: Routes = [
{
path: 'login',
loadChildren: () => import('./login/login.module').then(m => m.LoginModule),
canActivate: [
appendScopedHttpEasyI18nLoader([
{ prefix: `/assets/i18n/login/`, scope: 'login' }
])
]
}
];
```
## Add Bootstrap
Bootstrap application, refresh application when culture change without reload page
Install using npm:
```shell
npm install @angular/cdk @ngx-easy-i18n-js/bootstrap --save
```
Usage
```typescript
imports: [
EasyI18nBootstrapModule.forRoot({
bootstrap: AppComponent
})
]
bootstrap: [EasyI18nBootstrapComponent]
```
And in `index.html`, replace `` by ``
For custom loading component
```typescript
imports: [
EasyI18nBootstrapModule.forRoot({
bootstrap: AppComponent,
loadingComponent: MyLoadingComponent
})
]
bootstrap: [EasyI18nBootstrapComponent]
```