Astro

Astro can use Messagevisor during server rendering, static generation, or inside hydrated client islands.

Install#

Command

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

For React islands, also install:

Command

$ npm install @messagevisor/react

Load one server 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.ts

import { createMessagevisorLoader } from "./messagevisor-loader.js";
const loader = createMessagevisorLoader();
export const getMessagevisor = loader.get;
export const refreshMessagevisor = loader.refresh;

Server-rendered pages pass locale per call. Do not call setLocale() or setContext() while handling requests.

Server-rendered page#

src/pages/[locale]/index.astro

---
import { getMessagevisor } from "../../messagevisor";
const { locale = "en-US" } = Astro.params;
const m = await getMessagevisor();
const title = m.translate(
  "dashboard.welcome",
  { name: "Ada" },
  { locale, context: { platform: "web" } }
);
---
<h1>{title}</h1>

Client islands#

If a React island needs reactive translation hooks, pass the datafile into a React provider inside the island. The island follows the same pattern as React SDK.

src/components/TranslatedIsland.tsx

import { useMemo } from "react";
import { createMessagevisor } from "@messagevisor/sdk";
import { createICUModule } from "@messagevisor/module-icu";
import { MessagevisorProvider, useTranslation } from "@messagevisor/react";
function Greeting() {
  return <p>{useTranslation("dashboard.welcome", { name: "Ada" })}</p>;
}
export function TranslatedIsland({ datafile }: { datafile: any }) {
  const m = useMemo(
    () => createMessagevisor({ datafile, modules: [createICUModule()] }),
    [datafile]
  );
  return (
    <MessagevisorProvider instance={m}>
      <Greeting />
    </MessagevisorProvider>
  );
}

Client islands do not need to pass locale per call. They receive one datafile for the current user-facing locale, and the provider instance keeps that locale as its active locale.

Context and locale#

Astro pages often know locale from the route and context from cookies, headers, or frontmatter. Pass request-specific context per evaluation:

m.translate("billing.upgrade", undefined, {
  locale,
  context: {
    platform: "web",
    plan: Astro.cookies.get("plan")?.value,
  },
});

Install#

Load one server SDK instance#

Server-rendered page#

Client islands#

Context and locale#

Related#