KO
|
EN
gitlite — search
Search
#php
#java
#javascript
#android
#c-sharp
#game
#hacktoberfest
#dotfiles
#python
#xml
#docker
#tex
angular-i18next
★ 136
Open GitHub ↗
angular integration with i18next
Download README (.md)
Explore Similar Repositories
ngx-validators
:
Validator library for Angular 2+
AutoMapper.Data
:
For ADO.NET extensions to AutoMapper, IDataReader support etc
aframe-mouse-cursor-component
:
Mouse Cursor Component for A-Frame VR.
CrashlyticsDemo
:
Setup Fabric Crashlytics CI friendly
activejob-retry
:
Automatic retries for ActiveJob
// repository documentation
Was this content helpful?
★ 0
(0 ratings)
Select Rating:
★
★
★
★
★
Submit Feedback
Recent Feedback
×
Download README
Do you want to download the
README.md
file for
angular-i18next
?
Download (.md)
[](https://badge.fury.io/js/angular-i18next) [](https://npmjs.org/package/angular-i18next) [](https://github.com/Romanchuk/angular-i18next/actions/workflows/static.yml) [](https://coveralls.io/github/Romanchuk/angular-i18next?branch=master) [](http://commitizen.github.io/cz-cli/) [](https://www.paypal.com/paypalme2/sergeyromanchuk/10USD) [](https://github.com/romanchuk/angular-i18next) # angular-i18next Best [i18next](http://i18next.com/) integration with [angular](https://angular.io/) [Live DEMO](https://angular-i18next.onrender.com) - [Features](#features) - [Installation](#installation) - [Usage](#usage) - [Cookbook](#cookbook) - [In-project testing](#in-project-testing) - [Demo](#demo) - [Articles](#articles) - [Support project](#cheers) - [DEPRECATED DOCS](./README_DEPRECATED.md) # Features - Native i18next [options](https://www.i18next.com/configuration-options.html) - Promise initialization - [i18next plugin](https://www.i18next.com/plugins-and-utils.html#plugins) support - Events support - Namespaces lazy load - i18next native [format](https://www.i18next.com/api.html#format) support - document.title localization - Error handling strategies - i18next namespaces and scopes (prefixes) for angular modules and components - AOT support - SSR support - Providers for unit testing - Angular Package Format support - Zoneless compatible # Cheers Star this project Hey dude! Help me out for a couple of :beers:! Поддержи проект - угости автора кружечкой пива! [](https://www.paypal.com/paypalme2/sergeyromanchuk/10USD) ## Available Submodules (optional) - **`angular-i18next/ssr`**: Adds Server Side Rendering support. - **`angular-i18next/forms`**: Provides localization for `@angular/forms`. - **`angular-i18next/testing`**: Offers features for testing. # Installation **1.** Install package ```bash npm install i18next angular-i18next ``` **2.** Initialize i18next before angular application and provide Angular would not load until i18next initialize event fired ```typescript import { I18NEXT_SERVICE } from 'angular-i18next'; export function i18nAppInit() { return () => { const i18next = inject(I18NEXT_SERVICE); return i18next.init({ whitelist: ['en', 'ru'], fallbackLng: 'en', debug: true, returnEmptyString: false, ns: [ 'translation', 'validation', 'error' ], }); } } ``` ```typescript providers: [ provideAppInitializer(i18nAppInit()), provideI18Next( withCustomErrorHandlingStrategy(StrictErrorHandlingStrategy) ) ] ``` # Usage ## Pipes Use "i18next" pipe to translate key: ```html <div>{{ 'test' | i18next }}</div> ``` Passing ["t options"](https://www.i18next.com/api.html#t): ```html <div>{{ 'test' | i18next: { count: 5, nsSeparator: '#' } }}</div> ``` Remember to import the Pipe into the Component: ```typescript @Component({ // ... imports: [I18NextPipe], }) export class SomeExampleComponent {} ``` Trigger native i18next [format method](https://www.i18next.com/formatting.html) by using I18NextFormatPipe or I18NextPipe with option 'format': `{{ 'any_key' | i18next | i18nextFormat }}` `{{ 'any_key' | i18next: { format: 'cap' } }}` `{{ 'any_key' | i18nextCap }}` **Note:** Using "i18nextCap" you will get the same result as `i18next: { format: 'cap' }` **REMEMBER** that format will not work until you set "interpolation.format" function in i18next options. `angular-i81next` has static method `static interpolationFormat(customFormat: Function = null): Function` that can be used as default interpolation format function (it provides 'upper', 'cap' and 'lower' formatters). You also can pass your custom function to be called after library formatters: ```typescript import { defaultInterpolationFormat, interpolationFormat } from "angular-i18next"; const i18nextOptions = { supportedLngs: ['en', 'ru'], ns: [ 'translation', 'validation', 'error', ], interpolation: { format: interpolationFormat((value, format, lng) => { // extend interpolation format if(value instanceof Date) return moment(value).format(format); return value; }); // format: interpolationFormat(defaultInterpolationFormat) } }; ``` **i18nextEager pipe** This is the impure analog of *i18next pipe* that is subscribed to language change, it will change string right away to choosen language (without reloading page). **Warning!**: Use i18nextEager only in combine with [OnPush change detection strategy](https://netbasal.com/a-comprehensive-guide-to-angular-onpush-change-detection-strategy-5bac493074a4), or else (default change detection) each pipe will retrigger more than one time (cause of performance issues). Subscribing to event observables: ```typescript this.i18NextService.events.languageChanged.subscribe(lang => { // do something }) ``` Add a provider to module/component if you want to prefix child i18next keys: ```typescript { provide: I18NEXT_NAMESPACE, useValue: 'feature' // set 'feature:' prefix } ``` ```typescript { provide: I18NEXT_SCOPE, useValue: 'person' // set 'person.' prefix } ``` Since v3.1.0+ it is possible to pass array of namespaces (or scopes). [Key would fallback](https://www.i18next.com/api.html#t) to next namespace in array if the previous failed to resolve. `[feature_validators:key, validators:key]` ```typescript { provide: I18NEXT_NAMESPACE, useValue: ['feature_validators', 'validators'] } ``` _NOTE:* **Do NOT** use default (or custom) i18next delimiters in namespace names. ### Document title If you want to turn on document title localization resolve Title as `I18NextTitle` imported from 'angular-i18next': ```typescript providers: [provideI18Next(withTitle())] ``` Routes example: ```typescript const appRoutes: Routes = [ { path: 'error', component: AppErrorComponent, data: { title: 'error:error_occured' } }, { path: 'denied', component: AccessDeniedComponent, data: { title: 'error:access_denied' } } ]; ``` Ways to use I18NextService in your code: > **Warning:** Injection of **I18NextService** is possible, but it would not consider I18NEXT_NAMESPACE and I18NEXT_SCOPE providers. There are 2 possible reasons to inject **I18NextService**: initialization and subscription to its events. In all other cases inject **I18NextPipe**. 1) **Recommended way:** Inject via **I18NEXT_SERVICE** token. By default it will inject instance of **I18NextService**. ```typescript export class AppComponent implements OnInit { constructor(private router: Router, private title: Title, @Inject(I18NEXT_SERVICE) private i18NextService: ITranslationService) ``` 2) Legacy way: Inject via type ```typescript export class AppComponent implements OnInit { constructor(private router: Router, private title: Title, private i18NextService: I18NextService) ``` ### Error handling Error handling is now configurable: 1) By default i18next promise will use NativeErrorHandlingStrategy. I18Next would be always resolve successfully. Error could be get from 'then' handler parameter. 2) Set StrictErrorHandlingStrategy to reject load promises (init, languageChange, loadNamespaces) on first load fail (this was default in v2 but changed to fit [native i18next behavior](https://github.com/Romanchuk/angular-i18next/issues/9): ```typescript providers: [ provideI18Next( withCustomErrorHandlingStrategy(StrictErrorHandlingStrategy) ) ] ``` ### Lazy loading Use `i18NextNamespacesGuard` in your routes to to load i18next namespace. Note: It is not necessary to register lazy loading namespaces in global i18next options. ``` { path: 'rich_form', loadComponent: () => RichFormComponent, providers: [ { provide: I18NEXT_NAMESPACE, // namespace to start in component useValue: 'feature.rich_form', }, ], canActivate: [i18NextNamespacesGuard('feature.rich_form')] } ``` Use I18NextService.loadNamespaces() method to load namespaces in code. # Cookbook ### i18next plugin support ```typescript import { I18NextModule, ITranslationService, I18NEXT_SERVICE } from 'angular-i18next'; // import Backend from 'i18next-xhr-backend'; //for i18next < 20.0.0 import HttpApi from 'i18next-http-backend'; import LanguageDetector from 'i18next-browser-languagedetector'; ... i18next.use(HttpApi) .use(LanguageDetector) .init(i18nextOptions) ``` ### Server side rendereng (SSR) 1. Provide for server: ```typescript import { provideI18Next, withTitle } from 'angular-i18next'; import { withSSR } from 'angular-i18next/ssr'; const serverConfig: ApplicationConfig = { providers: [ provideServerRendering(), provideServerRouting(serverRoutes), provideI18Next(withTitle(), withSSR()), ], }; export const config = mergeApplicationConfig(appConfig, serverConfig); ``` 2. Configure i18next in `server.ts` ([Example](./apps/angular-i18next-demo/src/server.ts)): ### Auto error message for `@angular/forms` Use `i18nextValidationMessage` directive with formControlName ```typescript import { I18NextValidationMessageDirective } from 'angular-i18next/forms' @Component({ imports: [I18NextValidationMessageDirective] }) <input i18nextValidationMessage class="form-control" type="text" formControlName="lastName"/> ``` There is priority order for validation messages: 1. namespace + `control_specific` with form hierarchy 2. namespace + Common validation key(like `required`) 3. `control_specific` with form hierarchy 4. Common validation key like `required` Also you can interpolate `control.error` values. For example: For validator `Validators.min(1)` ```json "min": "Minimal {{min}}. Actual: {{actual}}." ``` `en.validation.json` ```json { "required": "Field is required.", "pattern": "$t(validation:_fill) valid value.", "_fill": "Please fill in", "control_specific": { "technicalContact": { "firstName": { "required": "$t(validation:_fill) technical specialist's first name." }, "lastName": { "required": "$t(validation:_fill) technical specialist's last name." }, "middleName": { "required": "$t(validation:_fill) technical specialist's patronymic." } } } } ``` ### Testing ```typescript import { withSSR } from 'angular-i18next/testing'; TestBed.configureTestingModule({ imports: [ProjectComponent], providers: [ provideI18NextMockAppInitializer(), provideI18Next(withMock()) ] }); ``` # What to do if... ? ## New angular version released, but angular-i18next is not released YET Angular releases mostly don't break angular-i18next, but we cannot tell ahead that current version of `angular-i18next` will work correctly with latest angular version. You can override an angular-i18next `peerDependencies` in your `package.json` on your **own risk**: ```json "overrides": { "angular-i18next": { "@angular/common": "*", "@angular/core": "*", "@angular/platform-browser": "*" } } ``` # In-project testing You might want to unit-test project components that are using i18next pipes Example tests setup: [libs/angular-i18next/src/tests/projectTests](https://github.com/Romanchuk/angular-i18next/tree/master/libs/angular-i18next/src/tests/projectTests) # Demo [Live DEMO](https://angular-i18next.onrender.com) Demo app source code available here: <https://github.com/Romanchuk/angular-i18next-demo> # Articles - [Angular L10n with I18next](https://phrase.com/blog/posts/angular-l10n-with-i18next/) - [Best Libraries for Angular I18n](https://phrase.com/blog/posts/best-libraries-for-angular-i18n/)
