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#

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

src/messagevisor.js

const { createMessagevisorLoader } = require("./messagevisor-loader");
const loader = createMessagevisorLoader();
const getMessagevisor = loader.get;
const refreshMessagevisor = loader.refresh;
module.exports = { getMessagevisor, refreshMessagevisor };

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) => {
  try {
    req.locale = req.acceptsLanguages("nl-NL", "en-US") || "en-US";
    req.messagevisor = await getMessagevisor();
    next();
  } catch (error) {
    next(error);
  }
});
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#

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

Install#

Load one server SDK instance#

Middleware#

TypeScript request type#

Refreshing datafiles#

Related#