@iplab/ngx-l10n

Pure Angular localization (l10n) library.

Demo

Description

It's an Angular functional set (pipe, directive, service) used to localize application
Compatible with Angular 2+ versions
No external dependency
Supported some of the most used localization files: .properties, .po, .json
Load localization file/s when you need it
Easily manage localization storage
Customizable localization loader

Tested with

Firefox (latest)
Chrome (latest)
Chromium (latest)
Edge
IE11

Installing / Getting started

npm install @iplab/ngx-l10n

Use the following snippet inside your app module:

import { L10nModule, L10nService, LanguageCodes } from '@iplab/ngx-l10n';
...
...

@Injectable()
export class LocalizationResolve implements Resolve {

    constructor(private localization: L10nService){
        this.localization.languageChanges.subscribe(({ code }) => {
            this.localization.setFromFile(`${code}.locales.properties`);
        })
    }

    public resolve(): Observable|Promise {
        return this.localization.setFromFile(`${this.localization.languageCode}.locales.properties`);
    }
}

@NgModule({
    imports: [
        BrowserModule,
        L10nModule.forRoot({ config: { defaultLanguage: LanguageCodes.EnglishUnitedStates } }),
        RouterModule.forRoot([
            { path: '', component: AppComponent, resolve: { localization: LocalizationResolve }}
        ])
    ],
    providers: [LocalizationResolve],
    bootstrap: [AppComponent]
})
export class AppModule {}

Use the following snippet inside your component:

import { L10nService } from '@iplab/ngx-l10n';


@Component({
  ...
})
export class AppComponent {

  constructor(private localization: L10nService) {
  }
}

Use the following snippet inside your template:

<div l10n="app.hello.key" [l10n-args]="params"></div>
<div l10n="app.hello.key" [l10n-args]="{value: 'world'}"></div>
<div l10n="app.hello.key" l10n-args="{value: 'world'}"></div>

<div [l10n]="'app.hello.key'" [l10n-args]="params"></div>
<div [l10n]="'app.hello.key'" l10n-args="{value: 'world'}"></div>

<div>{{'app.hello.key' | l10n:param }}</div>
<div [innerHTML]="'app.hello.key' | l10n"></div>
<div>{{'app.hello.key' | l10n: {'key': 'value'} }}</div>

NativeScript

tns plugin add @iplab/ngx-l10n

Use the following snippet inside your app module:

import { L10nModule, L10nService, L10nBaseLoader } from '@iplab/ngx-l10n';
import { knownFolders } from "file-system";
import { Subject, Observable, from } from 'rxjs';
import { map } from 'rxjs/operators';
import { Resolve } from "@angular/router";
...
import { NativeScriptModule } from "nativescript-angular/nativescript.module";
import { NativeScriptRouterModule } from "nativescript-angular/router";
...
...

@Injectable()
export class CustomLoader extends L10nBaseLoader {

    private readonly folderName = 'locales'; // folder where you place your locale files, 
                                            // in our case that is locales/en.locales.properties
    private readonly documents = knownFolders.currentApp();
    private readonly folder = this.documents.getFolder(this.folderName);

    public getFile({ url, code }: IL10nFileRequest ): Observable<IL10nLoaderResponse> {
        let fileType = this.getFileExtension( url );                           
        let file = this.folder.getFile(url);

        return from(file.readText())
                .pipe(map((response) => {
                    return { response, fileType }
                }));
    }
}

@Injectable()
export class LocalizationResolve implements Resolve {

    constructor(private localization: L10nService){
        this.localization.languageChanges.subscribe(({ code }) => {
            this.localization.setFromFile(`${code}.locales.properties`);
        })
    }

    public resolve(): Observable|Promise {
        return this.localization.setFromFile(`${this.localization.languageCode}.locales.properties`);
    }
}

@NgModule({
    imports: [
        NativeScriptModule,
        L10nModule.forRoot({ 
            config: {defaultLanguage: LanguageCodes.EnglishUnitedStates, bindingProperty: 'text' },
            loader: CustomLoader
        }),
        NativeScriptRouterModule.forRoot([
            { path: '', component: AppComponent, resolve: { localization: LocalizationResolve }}
        ])
    ],
    providers: [
        LocalizationResolve,
        L10nService, // because currently NativeScript doesn\'t work with @Injectable({ providedIn: \'root\' })
        CustomLoader
    ],
    bootstrap: [AppComponent]
})
export class AppModule {}

Use the following snippet inside your template:

<ActionBar title="{{ 'app.header.title' | l10n }}" class="action-bar"></ActionBar>
<ActionBar [title]="'app.hello.key' | l10n"></ActionBar>
<Label text="{{'app.hello.key' | l10n }}"></Label>
<Button text="{{'app.hello.key' | l10n }}" (tap)="onTap($event)"></Button>

If bindingProperty in configuration is set to text l10 directive will use it as default element property

<Label l10n="app.hello.key" [l10n-args]="params"></Label>
<Label l10n="app.hello.key" [l10n-args]="{value: 'world'}"></Label>
<Label l10n="app.hello.key" l10n-args="{value: 'world'}"></Label>

<Label [l10n]="'app.hello.key'" [l10n-args]="params"></Label>
<Label [l10n]="'app.hello.key'" l10n-args="{value: 'world'}"></Label>

Developing

Built With:

Angular
RxJS

Setting up Dev

This project was generated with Angular CLI version 6.0.7.

Angular CLI must be installed before building L10n project.

npm install -g @angular/cli

git clone https://github.com/pIvan/l10n.git
cd l10n/
npm install
npm run start

Open "http://localhost:4200" in browser

Versioning

We use SemVer for versioning. For the versions available, see the link to tags on this repository.

Tests

This project was generated with Angular CLI version 6.0.7.

Angular CLI must be installed before testing L10n project.

npm install -g @angular/cli

git clone https://github.com/pIvan/l10n.git
cd l10n/
npm install
npm run test

Contributing

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our contributing guide and then check out one of our issues.

Licensing

L10n is freely distributable under the terms of the MIT license.