Messagevisor

Express.js

Express applications usually use Messagevisor by loading server datafiles once, then evaluating translations with per-request locale and context in route handlers.

Install

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

Load one server SDK instance

src/messagevisor.js
const { createMessagevisor } = require("@messagevisor/sdk");
const { createICUModule } = require("@messagevisor/module-icu");
const supportedLocales = ["en-US", "nl-NL"];
let instancePromise;
async function getMessagevisor() {
  if (instancePromise) return instancePromise;
  instancePromise = Promise.all(
    supportedLocales.map((locale) =>
      fetch(`https://cdn.yoursite.com/datafiles/messagevisor-web-${locale}.json`).then(
        (response) => response.json()
      )
    )
  ).then((datafiles) => {
    const m = createMessagevisor({
      datafile: datafiles[0],
      modules: [createICUModule({ ignoreTags: false })],
    });
    datafiles.slice(1).forEach((datafile) => m.setDatafile(datafile));
    return m;
  });
  return instancePromise;
}
module.exports = { getMessagevisor };

The server instance contains datafiles for every supported locale. Route handlers choose the locale per call; they do not mutate the instance locale.

Middleware

Attach a helper to each request:

src/server.js
const express = require("express");
const { getMessagevisor } = require("./messagevisor");
const app = express();
app.use(async (req, res, next) => {
  req.locale = req.acceptsLanguages("nl-NL", "en-US") || "en-US";
  req.messagevisor = await getMessagevisor();
  next();
});
app.get("/", (req, res) => {
  const title = req.messagevisor.translate(
    "dashboard.welcome",
    { name: "Ada" },
    {
      context: {
        platform: "web",
        plan: req.query.plan,
      },
      locale: req.locale,
    }
  );
  res.send(`<h1>${title}</h1>`);
});
app.listen(3000);

Do not call setContext() or setLocale() on a shared instance for request-specific values. Pass locale and context in evaluation options so concurrent requests stay isolated.

TypeScript request type

src/express.d.ts
import type { Messagevisor } from "@messagevisor/sdk";
declare global {
  namespace Express {
    interface Request {
      locale: string;
      messagevisor: Messagevisor;
    }
  }
}

Refreshing datafiles

If datafiles are published to a CDN, refresh your cache on a timer, by revision checks, or during deployment. The SDK supports setDatafile() if you need to update the datafile without recreating the instance; pass true as the second argument when you need to fully replace an already-loaded locale.