Vue SDK

Vue SDK provides Vue 3 bindings for the JavaScript SDK: a plugin, provider component, Composition API composables, rich text components, and template globals.

Find a task#

Install and configure the plugin
Translate and format with composables
Pass reactive inputs and render rich text
Scope a provider
Load and update datafiles
Change locale, currency, and time zone
Observe diagnostics, events, and register modules
Integrate Nuxt, isolate server requests, and test translations

Install#

Command

$ npm install --save @messagevisor/sdk @messagevisor/vue

Plugin setup#

Create a Messagevisor SDK instance and install the Vue plugin:

src/main.ts

import { createApp, h } from "vue";
import { createMessagevisor } from "@messagevisor/sdk";
import { createICUModule } from "@messagevisor/module-icu";
import { createMessagevisorProvider } from "@messagevisor/vue";
import App from "./App.vue";
import datafile from "./datafiles/messagevisor-web-en-US.json";
const m = createMessagevisor({
  datafile,
  modules: [createICUModule({ ignoreTags: false })],
});
createApp(App)
  .use(
    createMessagevisorProvider({
      instance: m,
      defaultRichTextElements: {
        strong: (chunks) => h("strong", chunks),
        link: (chunks) => h("a", { href: "/terms" }, chunks),
      },
    }),
  )
  .mount("#app");

The plugin provides the instance to Composition API helpers and installs three template globals:

$messagevisor: full Vue Messagevisor API
$m: short alias for $messagevisor
$t: translation function

<template>
  <h1>{{ $t("dashboard.welcome", { name: "Ada" }) }}</h1>
  <p>{{ $m.formatNumber(12, { style: "currency", currency: "EUR" }) }}</p>
</template>

Composables#

Use useMessagevisor() when you want imperative SDK-style methods:

<script setup lang="ts">
import { useMessagevisor } from "@messagevisor/vue";
const { t, translate, formatNumber, setLocale } = useMessagevisor();
</script>
<template>
  <button @click="setLocale('nl-NL')">Nederlands</button>
  <h1>{{ t("dashboard.welcome", { name: "Ada" }) }}</h1>
  <p>{{ translate("billing.total", { amount: 12 }) }}</p>
  <p>{{ formatNumber(12, { style: "currency", currency: "EUR" }) }}</p>
</template>

Use value-oriented composables when the component should update after SDK state changes. They return ComputedRefs, which Vue unwraps in templates:

<script setup lang="ts">
import { ref } from "vue";
import { useLocale, useTranslation, useFormatNumber } from "@messagevisor/vue";
const name = ref("Ada");
const locale = useLocale();
const title = useTranslation("dashboard.welcome", { name });
const total = useFormatNumber(12, { style: "currency", currency: "EUR" });
</script>
<template>
  <main :lang="locale || undefined">
    <h1>{{ title }}</h1>
    <p>{{ total }}</p>
  </main>
</template>

In script code, access computed values with .value.

Reactive inputs#

Reactive composables accept plain values, refs, computed refs, or getter functions:

const key = computed(() => "dashboard.welcome");
const name = ref("Ada");
const plan = ref("pro");
const title = useTranslation(
  key,
  { name },
  () => ({ context: { plan: plan.value } }),
);

Values and options records are shallow-unwrapped, so refs inside a values object work without extra computed wrappers.

Rich text components#

Use MessageTranslation for keyed translations and FormatMessage for raw message strings:

<script setup lang="ts">
import { MessageTranslation } from "@messagevisor/vue";
</script>
<template>
  <MessageTranslation
    message-key="legal.terms"
    tag="p"
    :values="{ product: 'Messagevisor' }"
  >
    <template #link="{ chunks }">
      <a href="/terms">{{ chunks }}</a>
    </template>
    <template #strong="{ chunks }">
      <strong>{{ chunks }}</strong>
    </template>
  </MessageTranslation>
</template>

Named slots map to rich text tags in the selected ICU message. Local slots win over defaultRichTextElements from the plugin or provider.

MessageTranslation and FormatMessage render without a wrapper by default. Pass tag when you need a concrete root element for classes, attributes, or layout.

Provider override#

Use MessagevisorProvider when a subtree needs a different instance or rich text defaults than the app plugin:

<script setup lang="ts">
import { MessagevisorProvider } from "@messagevisor/vue";
</script>
<template>
  <MessagevisorProvider :instance="previewMessagevisor">
    <PreviewPanel />
  </MessagevisorProvider>
</template>

This is useful for previews, embedded admin tools, or tests.

Both provider forms accept a root or spawned child through MessagevisorConsumer. useSdk() returns that shared consumer type. Keep root ownership operations such as setDatafile(), addModule(), removeModule() and spawn() on the root reference rather than expecting them from an arbitrary provider.

Server side rendering#

Create a provider for each rendered request. It can consume a child from m.spawn(context, { locale }) so request context and locale stay isolated while the root owns datafiles and modules. Pass that child as the provider's instance and close it after rendering, including when rendering fails. Do not close a shared root after an individual request.

Hydrate the browser with the same datafile and locale used for server rendering. If the provider is deliberately installed only in the browser, place consuming components inside an explicit client boundary, as shown in the Nuxt recipe.

Available exports#

createMessagevisorProvider()
MessagevisorProvider
MessageTranslation
FormatMessage
useMessagevisor()
useSdk()
useMessagevisorSnapshot()
useLocale()
useDirection()
useLocaleInfo()
useMessagevisorContext()
useCurrency()
useTimeZone()
useTranslation()
useFormatMessage()
useFormatNumber()
useFormatDate()
useFormatTime()
useFormatDateTimeRange()
useFormatRelativeTime()
useFormatPlural()
useFormatList()
useFormatDisplayName()