Installation

Install the Package

Install @nestbolt/translatable using your preferred package manager:

npm install @nestbolt/translatable

yarn add @nestbolt/translatable

pnpm add @nestbolt/translatable

Peer Dependencies

This package requires the following peer dependencies. If you are working in an existing NestJS + TypeORM project, you likely already have most of these installed:

If any are missing, install them:

npm install @nestjs/common @nestjs/core class-validator class-transformer reflect-metadata typeorm

Optional Dependencies

Event Emitter

Install @nestjs/event-emitter to enable translation change events. When installed, a translatable.translation-set event is emitted whenever a translation value is set on an entity. This is useful for audit logging, cache invalidation, or triggering search index updates.

npm install @nestjs/event-emitter

You must also register the EventEmitterModule in your application:

import { EventEmitterModule } from "@nestjs/event-emitter";

@Module({
  imports: [
    EventEmitterModule.forRoot(),
    TranslatableModule.forRoot({
      defaultLocale: "en",
    }),
  ],
})
export class AppModule {}

See the Events page for details on listening to translation events.

GraphQL

Install @nestjs/graphql to enable GraphQL resolver support. The TranslatableInterceptor automatically detects GraphQL execution contexts and reads the Accept-Language header from the underlying HTTP request.

npm install @nestjs/graphql

See the API Locale Resolution section for GraphQL setup details.

Database Requirement

This package requires PostgreSQL with the jsonb column type. Translatable fields are stored as jsonb objects in the database, and the query helpers generate PostgreSQL-specific jsonb operator expressions.

Make sure your TypeORM configuration uses the postgres driver:

TypeOrmModule.forRoot({
  type: "postgres",
  host: "localhost",
  port: 5432,
  database: "myapp",
  // ...
})

Your translatable columns must be defined with type: "jsonb":

@Translatable()
@Column({ type: "jsonb", default: {} })
name: Record<string, string>;

The default: {} ensures that new rows start with an empty translation map rather than NULL.