Internationalization (i18n) in NestJS Applications

3 min readJan 6, 2025

Internationalization, commonly abbreviated as i18n (where 18 represents the number of letters between the ‘i’ and the ‘n’), is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. In this article, we’ll explore how to implement internationalization in a NestJS application using the nestjs-i18n package.

NestJS is a rapidly growing framework for building efficient and easily maintainable server-side applications. It’s built with TypeScript and leverages powerful features from modern JavaScript while supporting comprehensive development patterns such as dependency injection, modularization, and decorators.

Setting Up the Project

First, let’s create a new NestJS project:

$ npm i -g @nestjs/cli
$ nest new my-i18n-app
$ cd my-i18n-app

Installing Internationalization Dependencies

To add internationalization support to our NestJS application, we’ll use the nestjs-i18n package. Install it along with necessary dependencies:

$ npm install nestjs-i18n
$ npm install @nestjs/config
$ npm install @nestjs/platform-express
$ npm install i18next

Setting Up i18n Module

Setup AppModule to integrate the nestjs-i18n module. Open src/app.module.ts and configure the i18n module as shown below:

import { Module } from '@nestjs/common';
import { I18nModule, I18nJsonParser } from 'nestjs-i18n';
import * as path from 'path';

@Module({
  imports: [
    // Register I18nModule
    I18nModule.forRoot({
      fallbackLanguage: 'en',
      parser: I18nJsonParser,
      parserOptions: {
        path: path.join(__dirname, '/i18n/'),
        watch: true,
      },
    }),
  ],
})
export class AppModule {}

Here we are leveraging the I18nModule in our AppModule and configuring it to use JSON files located in the src/i18n/ directory for storing translations. Ensure that directory exists.

Configuring Translations

Create a directory named i18n in the src directory and add translation files for different languages. For example, create en.json and es.json files for English and Spanish translations:

src/i18n/en.json:

{
  "greeting": "Hello, {{ name }}!"
}

src/i18n/es.json:

{
  "greeting": "¡Hola, {{ name }}!"
}

Using Translations in Controllers

Create a simple controller to use our translations. Open src/app.controller.ts and modify it as follows:

import { Controller, Get, Query } from '@nestjs/common';
import { I18nService, I18nLang } from 'nestjs-i18n';

@Controller()
export class AppController {
  constructor(private readonly i18n: I18nService) {}

  @Get('greet')
  async greet(@I18nLang() lang: string, @Query('name') name: string): Promise<string> {
    const greeting = await this.i18n.translate('greeting', { lang, args: { name } });
    return greeting;
  }
}

In this code, we have a greet endpoint that accepts a query parameter name and uses the I18nService to translate the greeting message based on the lang parameter. If no language is specified in the request, it defaults to the fallback language (English in our setup).

Testing the Application

Run the application:

$ npm run start

Test the endpoints in your browser or with a tool like curl or Postman. For example:

English greeting:

http://localhost:3000/greet?name=John

Spanish greeting:

http://localhost:3000/greet?name=John&lang=es

You should see responses like:

English: Hello, John!
Spanish: ¡Hola, John!

Conclusion

We’ve successfully added internationalization to a NestJS application using the nestjs-i18n package. This demonstration shows how to set up the infrastructure, define translations, and use them in controllers. Proper i18n support can greatly enhance user experience by making your application accessible to a wider audience.