Quickstart

💡 Tip

If you already have i18n implemented in your project and are considering migrating to Transloco, check out our ngx-translate & Angular's i18n migrations.

v9 is in alpha. It is published under the npm next tag, which is why the commands below use @jsverse/transloco@next. Once 9.0.0 is stable, drop the tag.

Coming from v8? Start with the v9 migration guide.

The recommended way to add Transloco to your project is by running the add schematics:

Angular CLI

ng add @jsverse/transloco@next

Nx 🐋

pnpm add @jsverse/transloco@next
# Standalone
nx g @jsverse/transloco:ng-add
# Integrated monorepo workspace
nx g @jsverse/transloco:ng-add --project=my-app

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

As part of the installation process, you'll be presented with questions; Once you answer them, everything you need will automatically be created.

If you prefer not to use the schematics, you can install Transloco and manually add the files described below

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 injects it into the AppModule:

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 {}

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`);
  }
}

When you deploy your application and Transloco is unable to load your language files it might be 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.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;

You can read more about it here.

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