@sco-techlab/nestjs-i18n v10.0.8

Nest.JS i18n

Nest.JS i18n is a simple backend message translation service based on JSON files organized in a folder. Perfect for applications that require multilingual support.

Get Started

• Install dependency

npm i @sco-techlab/nestjs-i18n

• Import Translate module in your 'app.module.ts' file, register or registerAsync methods availables

import { TranslateModule } from '@sco-techlab/nestjs-i18n';
import { ConfigModule, ConfigService } from "@nestjs/config";

@Module({
  imports: [

    // Register module example
    TranslateModule.register({
      default: 'en',
      path: './i18n',
      filesCache: true,
      multiFiles: false,
      encoding: 'utf8',
      header: 'accept-language',
    }),

    // RegisterAsync module example
    TranslateModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => {
        return {
          default: configService.get("translate.default"),
          path: parseInt(configService.get("translate.path")),
          filesCache: configService.get("translate.filesCache"),
          multiFiles: configService.get("translate.multiFiles"),
          encoding: configService.get("translate.encoding"),
          header: configService.get("translate.header"),
        };
      },
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

• Module import is global mode, to use translate service only need constructor dependency inyection

import { TranslateService } from '@sco-techlab/nestjs-i18n';

constructor(private translateService: TranslateService) {}

Nest.JS i18n config

export class TranslateConfig {
  // default file name which will load if no accept-language header provided or accept-language header value not exists
  default: string; 

  // Path of the folder who contains the translate.json files
  path: string; 

  // Cache files to avoid reloading them on each request, if you want to hot reload files, set this value to false
  filesCache: boolean;

  // If you want to use multi files / folders translations structure, set this value to true
  // Recommend to use filesCache: true if you want to use big multi files / folders translations structure
  multiFiles: boolean;

  // Encoding of the translate.json file by default value is 'utf8'
  encoding?: BufferEncoding; 

  // Header name to find the language to set to the service in the interceptor by default value is 'accept-language'
  header?: string; 
}

Translate files (JSON)

You should create the translation files with the following format 'language.json' such as 'en.json', 'es.json'... All translation files should be in the same folder, which is the path we configured in the module

• En translates

{
  "hello-world": "Hello world",
  "tests": {
    "test1": {
      "1": "First translate of tests / test1 block",
      "2": "Second translate of tests / test1 block"
    }
  }
}

• Es translates

{
  "hello-world": "Hola mundo",
  "tests": {
    "test1": {
      "1": "Primera traducción del bloque tests / test1",
      "2": "Segunda traducción del bloque tests / test1"
    }
  }
}

Multi files / folders translations structure

If you want to use multi files / folders translations structure, set the 'multiFiles' value to true in the module configuration. You should create the files with the next structure:

• i18n
  • en
    • en.json
    • en.validations.json
  • es
    • es.json
    • es.validations.json

The service will load all the files in the folder of the language and will merge all the files in a single data object. So you can divide your translations in different files to avoid a translations file mess.

You cant have a empty language folder. The language folder files should have next structure:

• First part of the file name is the language name
• The last part of the file name is 'json'
• Example: 'en.XXXXX.json'

Example of multi files

• en.json

{
  "hello-world": "Hello world"
}

• en.validations.json

{
  "VALIDATIONS": {
    "VAL_1": "Val 1",
    "VAL_2": "Val 2"
  }
}

• Merge result:

{
  "hello-world": "Hello world",
  "VALIDATIONS": {
    "VAL_1": "Val 1",
    "VAL_2": "Val 2"
  }
}

Translate method

For single translate like 'hello-world' in last translate files example you should pass the label name like argument

translateService.translate('hello-world')

For nested translates like 'tests / test1 / 1' you should pass the blocks and the translate of the JSON object like the last example

translateService.translate('tests.test1.1')

An other example for nested translate like 'tests / test1 / 1' you can pass the blocks of the JSON object in parent order as a string[] value

translateService.translate(['tests', 'test1', '1'])

If the translation does not exist, the method will return as a result the name of the translation passed by parameter to the translate method

Block method

For block of translates like 'tests.test1' in last translate files example you should pass the block name like argument

translateService.block('tests.test1')

If the block exist the method will return as a result the block value like

{
  "1": "First translate of tests / test1 block",
  "2": "Second translate of tests / test1 block"
}

If the block does not exist, the method will return a empty object

Examples

• Live coding: Stackblitz example

Changelog

• You can see the library's change history in the Changelog.

Author

Santiago Comeras Oteo

• GitHub
• Npm
• LinkedIn