NestJS

NestJS applications can expose one shared Messagevisor instance through injectable providers and keep request-specific locale and context in controller method calls.

Install#

Command

$ npm install @messagevisor/sdk @messagevisor/module-icu

Messagevisor service#

Create an injectable service that loads all supported locale datafiles into one SDK instance:

Copy the shared datafile loader beside this helper. It checks HTTP status, retries initial failures, and retains the last known good datafiles during refresh failures.

src/messagevisor/messagevisor.service.ts

import { Injectable } from "@nestjs/common";
import { createMessagevisorLoader } from "./messagevisor-loader.js";
@Injectable()
export class MessagevisorService {
  private readonly loader = createMessagevisorLoader();
  getInstance() {
    return this.loader.get();
  }
  refresh() {
    return this.loader.refresh();
  }
}

Controllers pass locale per call. Do not call setLocale() or setContext() while handling requests.

Module#

src/messagevisor/messagevisor.module.ts

import { Module } from "@nestjs/common";
import { MessagevisorService } from "./messagevisor.service";
@Module({
  providers: [MessagevisorService],
  exports: [MessagevisorService],
})
export class MessagevisorModule {}

Then import MessagevisorModule from your app or feature module.

Controller#

Use Nest's @Query() decorator for locale and runtime context values:

src/app.controller.ts

import { Controller, Get, Query } from "@nestjs/common";
import { MessagevisorService } from "./messagevisor/messagevisor.service";
@Controller()
export class AppController {
  constructor(private readonly messagevisor: MessagevisorService) {}
  @Get()
  async index(@Query("locale") locale = "en-US", @Query("plan") plan?: string) {
    const m = await this.messagevisor.getInstance();
    return {
      title: m.translate(
        "dashboard.welcome",
        { name: "Ada" },
        { locale, context: { platform: "web", plan } }
      ),
    };
  }
  @Get("api/welcome")
  async welcome(@Query("locale") locale = "en-US") {
    const m = await this.messagevisor.getInstance();
    return {
      message: m.translate("dashboard.welcome", { name: "Ada" }, { locale }),
    };
  }
}

Nest serializes returned objects as JSON by default. If you render HTML from Nest, resolve the translation in the same way and pass it to your template or response layer.

Refreshing datafiles#

Call await service.refresh() from a deployment hook or revision poller. Handle rejection and keep using getInstance() for the last known good snapshot. See explicit refresh for cache age, request lifetime, and snapshot replacement.

Loading from a CDN#

Set baseUrl when creating the shared loader:

const loader = createMessagevisorLoader({
  baseUrl: "https://cdn.yoursite.com/datafiles",
});

The helper performs a new fetch when its cache expires or when you call its refresh() method. See explicit refresh for failure handling and deployment considerations.