Installation

tip

If you already have i18n implemented in your project and are considering migrating to Transloco, be sure to check out our Migration scripts.

Install the library using Angular CLI:

ng add @jsverse/transloco
# On an nx workspace
npm i @jsverse/transloco
nx g @jsverse/transloco:ng-add

For more information, see the ng-add command page.

As part of the installation process you'll be presented with questions; Once you answer them, everything you need will automatically be created for you. Let's take a closer look at the updates made and the generated files:

Standalone

The command will add the provideTransloco and provideHttpClient to your app providers:

app.config.ts

import { ApplicationConfig, isDevMode } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideTransloco } from '@jsverse/transloco';

import { TranslocoHttpLoader } from './transloco-loader';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTransloco({
      config: {
        availableLangs: ['en', 'es'],
        defaultLang: 'en',
        // Remove this option if your application doesn't support changing language in runtime.
        reRenderOnLangChange: true,
        prodMode: !isDevMode(),
      },
      loader: TranslocoHttpLoader,
    }),
  ],
};

NgModule

When added to a module based application a new transloco-root.module.ts which exposes an Angular module with a default configuration, and inject it into the AppModule:

transloco-root.module.ts

import { provideTransloco, TranslocoModule } from '@jsverse/transloco';
import { Injectable, isDevMode, NgModule } from '@angular/core';

import { TranslocoHttpLoader } from './transloco-loader';

@NgModule({
  exports: [TranslocoModule],
  providers: [
    provideTransloco({
      config: {
        availableLangs: ['en', 'es'],
        defaultLang: 'en',
        // Remove this option if your application doesn't support changing language in runtime.
        reRenderOnLangChange: true,
        prodMode: !isDevMode(),
      },
      loader: TranslocoHttpLoader,
    }),
  ],
})
export class TranslocoRootModule {}

note

You should import the TranslocoRootModule once in your root module, and use TranslocoModule in any other module.

Transloco loader

A default http loader implementation to fetch the translation files:

import { inject, Injectable } from '@angular/core';
import { Translation, TranslocoLoader } from '@jsverse/transloco';
import { HttpClient } from '@angular/common/http';

@Injectable({ providedIn: 'root' })
export class TranslocoHttpLoader implements TranslocoLoader {
  private http = inject(HttpClient);

  getTranslation(lang: string) {
    return this.http.get<Translation>(`/assets/i18n/${lang}.json`);
  }
}

note

When you deploy your application and Transloco is unable to load your language files it might because you need to use a relative path:

getTranslation(langPath: string) {
  return this.http.get(`./assets/i18n/${langPath}.json`);
}

Translation JSON files

Transloco creates boilerplate files for the requested languages with an empty JSON:

assets/i18n/{en, es}.json

{}

Transloco Global Config

This config is used by tools & plugins such as the scoped lib extractor and the keys-manager.

transloco.config.ts

import { TranslocoGlobalConfig } from '@jsverse/transloco-utils';

const config: TranslocoGlobalConfig = {
  rootTranslationsPath: 'src/assets/i18n/',
  langs: ['en', 'es'],
  keysManager: {},
};

export default config;

And that's it! Now we are ready to use it in our project.