Migration guide v16 → v17

For full details on version support across Angular releases, refer to the Angular Compatibility documentation.

Key Highlights

New Provider System: Complete overhaul of the configuration system with new provider functions for better tree-shaking and modularity.
Terminology Changes: “Default” language terminology changed to “Fallback” throughout the API for clarity.
Observable-based Events: EventEmitters replaced with Observables for better RxJS integration.
Enhanced Type Safety: Stricter TypeScript types and improved type definitions.
HTTP Loader Redesign: Configuration-based approach with new features like cache busting and interceptor bypass.
Modern Injection Patterns: Full support for Angular’s inject() function in components.

Breaking Changes Summary

Category	v16	v17
Terminology	`setDefaultLang()`	`setFallbackLang()`
Configuration	`defaultLang` + `useDefaultLang`	`fallbackLang`
Events	`EventEmitter`	`Observable`
Properties	Direct access	Getter methods preferred

1. Update Dependencies

Start by updating to the newest version of @ngx-translate/core:

npm i @ngx-translate/core@^17

pnpm add @ngx-translate/core@^17

yarn add @ngx-translate/core@^17

If you are using @ngx-translate/http-loader, update that too:

npm i @ngx-translate/http-loader@^17

pnpm add @ngx-translate/http-loader@^17

yarn add @ngx-translate/http-loader@^17

2. Update Configuration

2.1 Use `fallbackLang` configuration property Required

The most important change in v17 is updating your language configuration to use the new fallbackLang property instead of the previous defaultLanguage + useDefaultLang combination.

Standalone Components

Migration Example:

import { provideTranslateService } from '@ngx-translate/core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideTranslateService({
      defaultLanguage: 'en',
      useDefaultLang: true
      fallbackLang: 'en',
    })
  ],
};

NgModule Configuration

@NgModule({
  imports: [
    TranslateModule.forRoot({
      defaultLanguage: 'en',
      useDefaultLang: true
      fallbackLang: 'en',
    })
  ],
})
export class AppModule { }

2.2 Using provider functions Optional

v17 introduces new provider functions that replace the traditional Angular provider objects for better type safety:

import { TranslateLoader } from '@ngx-translate/core';
...
 { provide: TranslateLoader, useClass: CustomLoader }
...

import { provideTranslateLoader } from '@ngx-translate/core';
...
 provideTranslateLoader(CustomLoader)
...

Available provider functions:

import {
  provideTranslateService,
  provideTranslateLoader,
  provideTranslateCompiler,
  provideTranslateParser,
  provideMissingTranslationHandler
} from '@ngx-translate/core';

provideTranslateService({
  loader: provideTranslateLoader(CustomLoader),
  compiler: provideTranslateCompiler(CustomCompiler),
  parser: provideTranslateParser(CustomParser),
  missingTranslationHandler: provideMissingTranslationHandler(CustomMissingTranslationHandler),
})

Important: Correct Provider Usage

Critical Always use provider functions within the provideTranslateService configuration object.

❌ Incorrect Usage:

import {
  provideTranslateService,
  provideTranslateLoader,
  provideTranslateCompiler,
  provideTranslateParser
} from '@ngx-translate/core';

// This might NOT work as expected
[
  provideTranslateService(),
  provideTranslateLoader(CustomLoader),    // Conflict with defaults in provideTranslateService()
  provideTranslateCompiler(CustomCompiler) // Conflict with defaults in provideTranslateService()
]

✅ Correct Usage:

import {
  provideTranslateService,
  provideTranslateLoader,
  provideTranslateCompiler,
  provideTranslateParser
} from '@ngx-translate/core';

// This is the proper way
provideTranslateService({
  loader: provideTranslateLoader(CustomLoader),
  compiler: provideTranslateCompiler(CustomCompiler),
  parser: provideTranslateParser(CustomParser)
})

Why this matters: provideTranslateService loads default implementations for any providers not explicitly included in its configuration object. If you provide these services separately, they won’t be used by the TranslateService.

2.3 HTTP Loader Configuration Optional

If you’re using the HTTP loader, v17 introduces a new provider function approach that simplifies configuration and adds new features.

Migrate to provider function

Standalone Components

The constructor of TranslateHttpLoader does not accept parameters anymore. Instead, use provideTranslateHttpLoader to pass the parameters.

Migration Example:

import { provideTranslateService } from '@ngx-translate/core';
import {provideTranslateHttpLoader} from '@ngx-translate/http-loader';

const httpLoaderFactory: (http: HttpClient) => TranslateHttpLoader = (http: HttpClient) =>
    new TranslateHttpLoader(http, './i18n/', '.json');

export const appConfig: ApplicationConfig = {
  providers: [
    provideTranslateService({
      loader: {
        provide: TranslateLoader,
        useFactory: httpLoaderFactory,
        deps: [HttpClient],
      },
      loader: provideTranslateHttpLoader({prefix:"./assets/i18n/", suffix:".json"}),
    })
  ],
};

NgModule Configuration

Migration Example:

import { TranslateModule } from '@ngx-translate/core';
import { provideTranslateHttpLoader } from '@ngx-translate/http-loader';

const httpLoaderFactory: (http: HttpClient) => TranslateHttpLoader = (http: HttpClient) =>
    new TranslateHttpLoader(http, './i18n/', '.json');

@NgModule({
  imports: [
    TranslateModule.forRoot({
      loader: {
        provide: TranslateLoader,
        useFactory: httpLoaderFactory,
        deps: [HttpClient],
      },
      loader: provideTranslateHttpLoader({prefix:"./i18n/", suffix:".json"}),
    })
  ],
})
export class AppModule { }

For comprehensive information about using ngx-translate with NgModules, see the NgModules Support documentation.

New HTTP Loader Features

The new provider function also enables additional configuration options that weren’t available in v16:

import { provideTranslateHttpLoader } from '@ngx-translate/http-loader';

provideTranslateHttpLoader({
  prefix: './assets/i18n/',
  suffix: '.json',
  enforceLoading: true,    // Adds cache-busting timestamp
  useHttpBackend: true     // Bypasses HTTP interceptors
})

3. Update Method Calls Required

3.1 Language Configuration Methods

v16 → v17 Method Changes:

v16 Method	v17 Method	Notes
`setDefaultLang(lang)`	`setFallbackLang(lang)`	Returns Observable
`getDefaultLang()`	`getFallbackLang()`	Returns `Language \| null`
`onDefaultLangChange`	`onFallbackLangChange`	Now Observable

Breaking change: getDefaultLang() in v16 returned a string - which was not always true since it could also return undefined or null if no fallback language was configured. getFallbackLang() returns Language|null. Language is an alias for string.

Migration Example:

import { TranslateService } from '@ngx-translate/core';

 translate.setDefaultLang('en');
 translate.setFallbackLang('en')

 const defaultLang = translate.getDefaultLang();
 const fallbackLang = translate.getFallbackLang();

translate.onDefaultLangChange.subscribe(event => {
translate.onFallbackLangChange.subscribe(event => {
  console.log('Default language changed:', event.lang);
});

3.2 Property Access

v16 → v17 Property Changes:

v16 Property	v17 Replacement	Notes
`currentLang`	`getCurrentLang()`	Method preferred
`defaultLang`	`getFallbackLang()`	Method preferred
`langs`	`getLangs()`	Method preferred

Migration Example:

import { TranslateService } from '@ngx-translate/core';

const current = translate.currentLang;
const current = translate.getCurrentLang();

const fallback = translate.defaultLang;
const fallback = translate.getFallbackLang();

const languages = translate.langs;
const languages = translate.getLangs();

4. Update Event Subscriptions Required

Use onFallbackLangChange instead of onDefaultLangChange:

import { TranslateService, DefaultLangChangeEvent, FallbackLangChangeEvent } from '@ngx-translate/core';

translate.onDefaultLangChange.subscribe((event: DefaultLangChangeEvent) => {
  console.log('Default language changed:', event.lang);
translate.onFallbackLangChange.subscribe((event: FallbackLangChangeEvent) => {
  console.log('Fallback language changed:', event.lang);
});