nestjs-i18n

nestjs-i18n is a NestJS module that adds first-class internationalization to a Nest application: translation loading, locale resolution from headers/query/cookies, variable interpolation, pluralization, and DTO validation message translation. It integrates with Nest’s dependency-injection system as a standard dynamic module, and ships a CLI for generating TypeScript types from translation files so missing or mistyped keys are caught at compile time.

It supports GraphQL and gRPC contexts in addition to REST, and lets applications plug in custom resolvers, loaders, and formatters when the built-in ones don’t fit.

What You Get

• I18nModule with configurable loaders (JSON, YAML, or custom) and fallback languages
• Locale resolvers for headers, query params, cookies, and Accept-Language, with custom resolver support
• A CLI (nestjs-i18n) that generates TypeScript types from translation files for compile-time key safety
• Pluralization and variable formatting in translation strings
• Integration hooks for class-validator DTOs, GraphQL, and gRPC contexts

Common Use Cases

• Serving translated API responses based on a request’s Accept-Language header
• Translating class-validator error messages for multi-language REST APIs
• Adding locale-aware pluralization and formatting to email or notification templates
• Generating typed translation keys to prevent typos in large, multi-locale NestJS codebases

Under The Hood

Architecture The library is structured as a standard NestJS dynamic module (I18nModule.forRoot/forRootAsync in src/i18n.module.ts, ~550 lines) that registers an I18nService, a set of pluggable loaders (src/loaders) responsible for reading translation files, and resolvers (src/resolvers) that determine the active locale per request from headers, cookies, or query params. An I18nContext (src/i18n.context.ts) exposes the resolved locale and translate function to interceptors, pipes, and decorators throughout the request lifecycle, with dedicated pipes/filters for validation-message translation.

Tech Stack Built in TypeScript on top of NestJS’s DI/module system, with a small companion CLI (bin/nestjs-i18n.mjs, backed by src/cli) for type generation, and integrations for Fastify/Express, GraphQL, and gRPC transports.

Code Quality The tests/ directory has a large Jest suite (config in tests/jest-test.json) with e2e specs per feature area (validation, GraphQL, view engines, disabled middleware, CLI), run with coverage tracked via Coveralls — a notably thorough test setup for a community NestJS module. Contribution volume (84 contributors) and active CI (test.yaml workflow) point to consistent code review practices.

API Design The module follows NestJS conventions closely (forRoot/forRootAsync, decorators like @I18n, injectable I18nService), which keeps the learning curve low for anyone already familiar with Nest’s DI patterns, and the generated-types CLI adds an ergonomic layer that many i18n libraries lack — catching invalid translation keys before runtime.