@lunmark/vokativ-next-intl 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.0.1
+
+First release.
+
+- `createVokativNextIntlPlugin(options, nextIntlSetting)` in place of next-intl's plugin, and
+  `withVokativ(config)` after it: `<voc>{name}</voc>` in a message puts the name in the Serbian
+  vocative, with no change at call sites.
+- `languages`: `auto` for every Serbian locale, or per locale with `"latin"`, `"cyrillic"`,
+  `true` or `false`; the most specific key wins. A misspelled setting stops the build.
+- A `gender` value in the message decides surnames.
+- Works with next-intl's precompiled messages, Turbopack and webpack.
+- `vokativNextIntl()` for Vitest.

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Lunmark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The name data in data/ and the exception lists derived from it are based on
+"Vokativi" by Startit (https://github.com/startitrs/vokativi), licensed under
+CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); see data/LICENSE.md.
+Changes: typo corrections (data/errata.csv), and only the names the rules
+don't cover are shipped.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @lunmark/vokativ-next-intl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Serbian vocative for [next-intl](https://next-intl.dev): mark where a Serbian message
+addresses someone, and the name is put in the vocative.
+
+```jsonc
+// messages/sr.json
+"greeting": "Dobar dan, <voc>{name}</voc>!"   // → "Dobar dan, Ivane!"
+// messages/en.json, unchanged
+"greeting": "Good afternoon, {name}!"          // → "Good afternoon, Ivan!"
+```
+
+```tsx
+t("greeting", { name: user.firstName }) // no change at any call site
+```
+
+It works everywhere next-intl formats a message: server and client components, `t()`,
+`t.rich()`, `t.markup()` and `getTranslations()`, with or without precompiled messages.
+
+## Setup
+
+```bash
+pnpm add @lunmark/vokativ-next-intl
+```
+
+In `next.config.ts`, use it in place of next-intl's plugin. next-intl's own setting goes
+second, unchanged:
+
+```ts
+import createVokativNextIntlPlugin from "@lunmark/vokativ-next-intl/plugin"
+
+const withNextIntl = createVokativNextIntlPlugin(
+  { languages: { auto: true } },
+  "./i18n/request.ts"
+)
+
+export default withNextIntl(nextConfig)
+```
+
+Already wrapping your config another way? `withVokativ(withNextIntl(nextConfig))` does the
+same after next-intl's plugin:
+
+```ts
+import { withVokativ } from "@lunmark/vokativ-next-intl/plugin"
+```
+
+Then put `<voc>…</voc>` around the name in your Serbian messages. That's all.
+
+## Languages
+
+`languages` decides which locales get the vocative, and in which script the name is written.
+
+```ts
+{ languages: { auto: true } }                          // the default
+{ languages: { "sr-Latn": "latin", sr: "cyrillic" } }  // explicit
+{ languages: { auto: true, "sr-ME": false } }          // all Serbian but one
+```
+
+- **`auto: true`** covers every Serbian locale (`sr`, `sr-*`). A locale code that names a
+  script gets it (`sr-Latn-RS` → Latin, `sr-Cyrl` → Cyrillic); a bare `sr` keeps the name's
+  own script.
+- **A locale key** covers that locale and the ones under it (`"sr-Latn"` covers
+  `sr-Latn-RS`); the most specific key wins. `"latin"` or `"cyrillic"` writes the name in that
+  script (Ivan → Иване on a Cyrillic page), `true` keeps the name's own script, `false` turns
+  the vocative off.
+- A locale code that names its own script keeps it when the matching key doesn't name one:
+  with `{ sr: "cyrillic" }`, `sr-Latn` is still Latin.
+- Everywhere else, `<voc>` leaves the name as it is, so a tag that slips into another
+  language does no harm.
+
+A misspelled setting (`"cyrilic"`) stops the build with an error rather than doing nothing.
+
+## Gender
+
+If the message also gets a `gender` value (`"m"`/`"male"` or `"f"`/`"female"`), which Serbian
+messages often need anyway for "Dragi/Draga", surnames are declined for men:
+
+```jsonc
+"dear": "{gender, select, f {Draga <voc>{name}</voc>} other {Dragi <voc>{name}</voc>}}"
+// { name: "Marko Janković", gender: "m" } → "Dragi Marko Jankoviću"
+// { name: "Ana Janković", gender: "f" }   → "Draga Ana Janković"
+```
+
+Without one, only the first name is declined; a surname is never wrong left as written.
+
+## Tests (Vitest)
+
+Vitest doesn't run `next.config`, so add the same swap there, or a message with `<voc>`
+renders as its key:
+
+```ts
+// vitest.config.ts
+import { vokativNextIntl } from "@lunmark/vokativ-next-intl/vitest"
+
+export default defineConfig({
+  plugins: [vokativNextIntl({ languages: { auto: true } })],
+})
+```
+
+## How it works
+
+Every message next-intl formats goes through one function in use-intl,
+`use-intl/format-message`. The plugin points that import at a small stand-in, the way
+next-intl itself swaps it when it precompiles messages. The stand-in adds a `voc` handler and
+calls the original formatter.
+
+- A message without `<voc>` goes straight through: about 20 ns extra.
+- A `voc` you pass yourself always wins.
+- Names longer than 100 characters are left as written.
+- The declension is [`@lunmark/vokativ`](https://www.npmjs.com/package/@lunmark/vokativ),
+  about 3 KB gzipped with this package.
+
+## Good to know
+
+- **Requirements:** next-intl 4, and Next.js 15.3 or later, with Turbopack or webpack.
+- **Typed messages** generated from your Serbian file make `t.rich()` and `t.markup()` ask for
+  a `voc` handler, since the tag is in their type. Plain `t()` doesn't. Most apps type their
+  messages from English, where there's no tag.
+- **`t.markup()` doesn't escape values**, with or without `<voc>`; the name comes out exactly
+  as `{name}` would. `t()` and `t.rich()` render through React, which escapes.
+- `use-intl/format-message` is a public entry point, but swapping it isn't a documented
+  next-intl API. This package pins next-intl 4 and is tested against it.
+
+## License
+
+MIT. Name data: "[Vokativi](https://github.com/startitrs/vokativi)" by Startit,
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), modified.

package/dist/format-message.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stands in for `use-intl/format-message` in the app's bundles (the plugin points the import
+ * here) and hands every message to the original formatter, adding the `voc` tag.
+ */
+import { type FormatMessage } from "./with-vokativ-tag.js";
+declare const _default: FormatMessage;
+export default _default;

package/dist/format-message.js

@@ -0,0 +1,23 @@
+/**
+ * Stands in for `use-intl/format-message` in the app's bundles (the plugin points the import
+ * here) and hands every message to the original formatter, adding the `voc` tag.
+ */
+// The formatter next-intl chose (the runtime compiler, or the precompiled-message formatter);
+// the plugin points this specifier at it.
+import formatMessage from "@lunmark/vokativ-next-intl/original-format-message";
+import { DEFAULT_LANGUAGES } from "./languages.js";
+import { withVokativTag } from "./with-vokativ-tag.js";
+export default withVokativTag(formatMessage, languages());
+/** The setting the plugin put in the bundle's env, as JSON. */
+function languages() {
+    try {
+        // Written out in full so the bundler can replace it.
+        const json = process.env._vokativ_languages;
+        if (json)
+            return JSON.parse(json);
+    }
+    catch {
+        // No `process` in this environment: the default applies.
+    }
+    return DEFAULT_LANGUAGES;
+}

package/dist/languages.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which locales get the vocative, and in which script. Shared by the Next.js plugin (which checks
+ * the setting) and the runtime (which reads it for every message).
+ */
+export type Script = "latin" | "cyrillic";
+/**
+ * `auto: true` covers every Serbian locale (sr, sr-*). A locale key covers that locale and the
+ * ones under it ("sr-Latn" covers sr-Latn-RS): `"latin"` or `"cyrillic"` writes the name in that
+ * script, `true` keeps the name's own script, `false` turns the vocative off.
+ */
+export interface Languages {
+    auto?: boolean;
+    [locale: string]: Script | boolean | undefined;
+}
+/** What a locale gets: the name written in a script, or "keep" for the name's own script. */
+export type Target = Script | "keep";
+export declare const DEFAULT_LANGUAGES: Languages;
+/**
+ * The target for a locale, or undefined when the vocative is off for it. The most specific key
+ * wins (sr-Latn-RS tries sr-Latn-RS, sr-Latn, sr). A locale that names its own script keeps it
+ * when the key that matched doesn't name one: with `{ sr: "cyrillic" }`, sr-Latn is still Latin.
+ */
+export declare function resolveLanguage(locale: string, languages: Languages): Target | undefined;
+/** Throws on a setting that would silently do nothing, like a misspelled script. */
+export declare function checkLanguages(languages: Languages): void;

package/dist/languages.js

@@ -0,0 +1,61 @@
+/**
+ * Which locales get the vocative, and in which script. Shared by the Next.js plugin (which checks
+ * the setting) and the runtime (which reads it for every message).
+ */
+export const DEFAULT_LANGUAGES = { auto: true };
+/**
+ * The target for a locale, or undefined when the vocative is off for it. The most specific key
+ * wins (sr-Latn-RS tries sr-Latn-RS, sr-Latn, sr). A locale that names its own script keeps it
+ * when the key that matched doesn't name one: with `{ sr: "cyrillic" }`, sr-Latn is still Latin.
+ */
+export function resolveLanguage(locale, languages) {
+    const subtags = locale.split(/[-_]/);
+    const ownScript = scriptOf(subtags);
+    const settings = new Map(Object.entries(languages)
+        .filter(([key]) => key !== "auto")
+        .map(([key, setting]) => [normalize(key), setting]));
+    for (let length = subtags.length; length > 0; length--) {
+        const key = normalize(subtags.slice(0, length).join("-"));
+        const setting = settings.get(key);
+        if (setting === undefined)
+            continue;
+        if (setting === false)
+            return undefined;
+        if (ownScript && !scriptOf(key.split("-")))
+            return ownScript;
+        return setting === true ? "keep" : setting;
+    }
+    if (languages.auto && subtags[0]?.toLowerCase() === "sr") {
+        return ownScript ?? "keep";
+    }
+    return undefined;
+}
+/** Throws on a setting that would silently do nothing, like a misspelled script. */
+export function checkLanguages(languages) {
+    for (const [key, setting] of Object.entries(languages)) {
+        if (key === "auto") {
+            if (typeof setting !== "boolean") {
+                throw new Error(`vokativ: languages.auto must be true or false.`);
+            }
+        }
+        else if (setting !== true &&
+            setting !== false &&
+            setting !== "latin" &&
+            setting !== "cyrillic") {
+            throw new Error(`vokativ: languages[${JSON.stringify(key)}] is ${JSON.stringify(setting)}; use "latin", "cyrillic", true or false.`);
+        }
+    }
+}
+function scriptOf(subtags) {
+    for (const subtag of subtags) {
+        const lower = subtag.toLowerCase();
+        if (lower === "latn")
+            return "latin";
+        if (lower === "cyrl")
+            return "cyrillic";
+    }
+    return undefined;
+}
+function normalize(locale) {
+    return locale.toLowerCase().replace(/_/g, "-");
+}

package/dist/paths.d.ts

@@ -0,0 +1,11 @@
+/** Where the pieces live on disk, for the bundler aliases. Node only (next.config, vitest.config). */
+/** The import every message goes through, and the name the original is reached by. */
+export declare const FORMAT_MESSAGE = "use-intl/format-message";
+export declare const ORIGINAL_FORMAT_MESSAGE = "@lunmark/vokativ-next-intl/original-format-message";
+/** Our stand-in for `use-intl/format-message`: built (.js), or the source in our own tests. */
+export declare function shimPath(): string;
+/**
+ * The formatter next-intl uses when it doesn't precompile messages, from the app's own next-intl.
+ * Outside a production build, its development build, which has the clearer error messages.
+ */
+export declare function defaultFormatMessage(): string;

package/dist/paths.js

@@ -0,0 +1,41 @@
+/** Where the pieces live on disk, for the bundler aliases. Node only (next.config, vitest.config). */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** The import every message goes through, and the name the original is reached by. */
+export const FORMAT_MESSAGE = "use-intl/format-message";
+export const ORIGINAL_FORMAT_MESSAGE = "@lunmark/vokativ-next-intl/original-format-message";
+/** Our stand-in for `use-intl/format-message`: built (.js), or the source in our own tests. */
+export function shimPath() {
+    const js = fileURLToPath(new URL("./format-message.js", import.meta.url));
+    return existsSync(js) ? js : js.replace(/\.js$/, ".ts");
+}
+/**
+ * The formatter next-intl uses when it doesn't precompile messages, from the app's own next-intl.
+ * Outside a production build, its development build, which has the clearer error messages.
+ */
+export function defaultFormatMessage() {
+    const production = fromNextIntl().resolve(FORMAT_MESSAGE);
+    if (process.env.NODE_ENV !== "production") {
+        const development = production.replace(`${path.sep}production${path.sep}`, `${path.sep}development${path.sep}`);
+        if (existsSync(development))
+            return development;
+    }
+    return production;
+}
+/** Resolves from where the app's next-intl is, which knows its own use-intl. */
+function fromNextIntl() {
+    for (const base of [
+        path.join(process.cwd(), "package.json"),
+        import.meta.url,
+    ]) {
+        try {
+            return createRequire(createRequire(base).resolve("next-intl/plugin"));
+        }
+        catch {
+            // Not resolvable from here; try the next place.
+        }
+    }
+    throw new Error("vokativ: next-intl isn't installed.");
+}

package/dist/plugin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Next.js side: next-intl's plugin, plus the Serbian vocative. In a Serbian message,
+ * `<voc>{name}</voc>` addresses the person by name ("Zdravo, <voc>{name}</voc>!" → "Zdravo,
+ * Ivane!"), with every `t()` call left as it is.
+ *
+ * It works by pointing `use-intl/format-message` (the one function every message is formatted
+ * by) at a stand-in that adds the `voc` tag and calls the original, the way next-intl itself
+ * swaps that import when it precompiles messages.
+ */
+import type { NextConfig } from "next";
+import createNextIntlPlugin from "next-intl/plugin";
+import { type Languages } from "./languages.js";
+export type { Languages, Script } from "./languages.js";
+export interface VokativOptions {
+    /** Which locales get the vocative; every Serbian one by default (`{ auto: true }`). */
+    languages?: Languages;
+}
+/** next-intl's own plugin setting: the request config path, or its options. */
+type NextIntlPluginConfig = Parameters<typeof createNextIntlPlugin>[0];
+/**
+ * Use in place of next-intl's `createNextIntlPlugin`; its setting goes second, unchanged:
+ *
+ * ```ts
+ * const withVokativNextIntl = createVokativNextIntlPlugin(
+ *   { languages: { auto: true } },
+ *   "./i18n/request.ts"
+ * )
+ * export default withVokativNextIntl(nextConfig)
+ * ```
+ */
+export default function createVokativNextIntlPlugin(options?: VokativOptions, nextIntl?: NextIntlPluginConfig): (config?: NextConfig) => NextConfig;
+/**
+ * Adds the vocative to a config next-intl's plugin has already been applied to, for an app that
+ * keeps calling `createNextIntlPlugin` itself: `withVokativ(withNextIntl(nextConfig))`.
+ */
+export declare function withVokativ(config: NextConfig, { languages }?: VokativOptions): NextConfig;

package/dist/plugin.js

@@ -0,0 +1,73 @@
+/**
+ * The Next.js side: next-intl's plugin, plus the Serbian vocative. In a Serbian message,
+ * `<voc>{name}</voc>` addresses the person by name ("Zdravo, <voc>{name}</voc>!" → "Zdravo,
+ * Ivane!"), with every `t()` call left as it is.
+ *
+ * It works by pointing `use-intl/format-message` (the one function every message is formatted
+ * by) at a stand-in that adds the `voc` tag and calls the original, the way next-intl itself
+ * swaps that import when it precompiles messages.
+ */
+import path from "node:path";
+import createNextIntlPlugin from "next-intl/plugin";
+import { checkLanguages, DEFAULT_LANGUAGES, } from "./languages.js";
+import { defaultFormatMessage, FORMAT_MESSAGE, ORIGINAL_FORMAT_MESSAGE, shimPath, } from "./paths.js";
+/**
+ * Use in place of next-intl's `createNextIntlPlugin`; its setting goes second, unchanged:
+ *
+ * ```ts
+ * const withVokativNextIntl = createVokativNextIntlPlugin(
+ *   { languages: { auto: true } },
+ *   "./i18n/request.ts"
+ * )
+ * export default withVokativNextIntl(nextConfig)
+ * ```
+ */
+export default function createVokativNextIntlPlugin(options = {}, nextIntl) {
+    const withNextIntl = createNextIntlPlugin(nextIntl);
+    return function withVokativNextIntl(config = {}) {
+        return withVokativ(withNextIntl(config), options);
+    };
+}
+/**
+ * Adds the vocative to a config next-intl's plugin has already been applied to, for an app that
+ * keeps calling `createNextIntlPlugin` itself: `withVokativ(withNextIntl(nextConfig))`.
+ */
+export function withVokativ(config, { languages = DEFAULT_LANGUAGES } = {}) {
+    checkLanguages(languages);
+    const shim = shimPath();
+    // next-intl already points the import at its precompiled-message formatter when asked to.
+    const chosen = config.turbopack?.resolveAlias?.[FORMAT_MESSAGE];
+    return {
+        ...config,
+        env: { ...config.env, _vokativ_languages: JSON.stringify(languages) },
+        turbopack: {
+            ...config.turbopack,
+            resolveAlias: {
+                ...config.turbopack?.resolveAlias,
+                [FORMAT_MESSAGE]: turbopackPath(shim),
+                [ORIGINAL_FORMAT_MESSAGE]: typeof chosen === "string"
+                    ? chosen
+                    : turbopackPath(defaultFormatMessage()),
+            },
+        },
+        webpack(webpackConfig, context) {
+            const result = config.webpack
+                ? config.webpack(webpackConfig, context)
+                : webpackConfig;
+            result.resolve ??= {};
+            result.resolve.alias ??= {};
+            const alias = result.resolve.alias;
+            const original = alias[FORMAT_MESSAGE];
+            delete alias[FORMAT_MESSAGE];
+            alias[`${FORMAT_MESSAGE}$`] = shim;
+            alias[`${ORIGINAL_FORMAT_MESSAGE}$`] =
+                typeof original === "string" ? original : defaultFormatMessage();
+            return result;
+        },
+    };
+}
+/** Turbopack takes aliases relative to the project, starting with "./" (as next-intl does). */
+function turbopackPath(file) {
+    const relative = path.relative(process.cwd(), file).replace(/\\/g, "/");
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}

package/dist/vitest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The same swap for Vitest, which doesn't run next.config: without it, a message with
+ * `<voc>{name}</voc>` renders as its key in tests.
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { vokativNextIntl } from "@lunmark/vokativ-next-intl/vitest"
+ * export default defineConfig({ plugins: [vokativNextIntl()] })
+ * ```
+ */
+import { type Languages } from "./languages.js";
+export type { Languages, Script } from "./languages.js";
+/** A Vite/Vitest plugin; typed loosely so this package needn't depend on Vite. */
+export declare function vokativNextIntl({ languages, }?: {
+    languages?: Languages;
+}): {
+    name: string;
+    config(): {
+        resolve: {
+            alias: ({
+                find: RegExp;
+                replacement: string;
+            } | {
+                find: string;
+                replacement: string;
+            })[];
+        };
+        test: {
+            server: {
+                deps: {
+                    inline: string[];
+                };
+            };
+        };
+    };
+};

package/dist/vitest.js

@@ -0,0 +1,46 @@
+/**
+ * The same swap for Vitest, which doesn't run next.config: without it, a message with
+ * `<voc>{name}</voc>` renders as its key in tests.
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { vokativNextIntl } from "@lunmark/vokativ-next-intl/vitest"
+ * export default defineConfig({ plugins: [vokativNextIntl()] })
+ * ```
+ */
+import { checkLanguages, DEFAULT_LANGUAGES, } from "./languages.js";
+import { defaultFormatMessage, FORMAT_MESSAGE, ORIGINAL_FORMAT_MESSAGE, shimPath, } from "./paths.js";
+/** A Vite/Vitest plugin; typed loosely so this package needn't depend on Vite. */
+export function vokativNextIntl({ languages = DEFAULT_LANGUAGES, } = {}) {
+    checkLanguages(languages);
+    const json = JSON.stringify(languages);
+    return {
+        name: "vokativ-next-intl",
+        config() {
+            // Test workers inherit it; the stand-in reads it at runtime.
+            process.env._vokativ_languages = json;
+            return {
+                resolve: {
+                    alias: [
+                        {
+                            find: new RegExp(`^${FORMAT_MESSAGE}$`),
+                            replacement: shimPath(),
+                        },
+                        {
+                            find: ORIGINAL_FORMAT_MESSAGE,
+                            replacement: defaultFormatMessage(),
+                        },
+                    ],
+                },
+                test: {
+                    // Run these through Vite, so the alias reaches use-intl's own import.
+                    server: {
+                        deps: {
+                            inline: ["use-intl", "next-intl", "@lunmark/vokativ-next-intl"],
+                        },
+                    },
+                },
+            };
+        },
+    };
+}

package/dist/with-vokativ-tag.d.ts

@@ -0,0 +1,17 @@
+import { type Languages } from "./languages.js";
+type Values = Record<string, unknown>;
+/**
+ * use-intl's message formatter, `use-intl/format-message`: every `t()`, `t.rich()`, `t.markup()`
+ * and `getTranslations()` call ends here, with the message (an ICU string, or a precompiled one)
+ * and the locale. Not a documented API, so only what we rely on is typed.
+ */
+export type FormatMessage = (key: string, message: unknown, values: Values | undefined, options: {
+    locale: string;
+}) => unknown;
+/**
+ * Wraps use-intl's formatter so a message can address someone: `<voc>{name}</voc>` declines the
+ * name for the locales `languages` turns on, and passes it through unchanged elsewhere. A message
+ * without the tag, or a call that brings its own `voc`, goes straight through.
+ */
+export declare function withVokativTag<F extends FormatMessage>(formatMessage: F, languages: Languages): F;
+export {};

package/dist/with-vokativ-tag.js

@@ -0,0 +1,68 @@
+import { vokativ } from "@lunmark/vokativ";
+import { resolveLanguage } from "./languages.js";
+/**
+ * Wraps use-intl's formatter so a message can address someone: `<voc>{name}</voc>` declines the
+ * name for the locales `languages` turns on, and passes it through unchanged elsewhere. A message
+ * without the tag, or a call that brings its own `voc`, goes straight through.
+ */
+export function withVokativTag(formatMessage, languages) {
+    const targets = new Map();
+    /** The locale lookup, once per locale: an app has a handful. */
+    function targetFor(locale) {
+        // Without a locale (use-intl changed how it calls us), pass names through rather than fail.
+        if (typeof locale !== "string")
+            return undefined;
+        if (!targets.has(locale)) {
+            // A bound, in case an app formats with locales it doesn't control.
+            if (targets.size >= 100)
+                targets.clear();
+            targets.set(locale, resolveLanguage(locale, languages));
+        }
+        return targets.get(locale);
+    }
+    const wrapped = ((key, message, values, options) => {
+        if (!mentionsVoc(message) || (values && Object.hasOwn(values, "voc"))) {
+            return formatMessage(key, message, values, options);
+        }
+        const target = targetFor(options?.locale);
+        const voc = (chunks) => decline(chunks, target, values);
+        return formatMessage(key, message, { ...values, voc }, options);
+    });
+    // use-intl reads flags off the formatter (`formatMessage.raw`).
+    return Object.assign(wrapped, formatMessage);
+}
+/** The name inside the tag, declined; anything but plain text (a React element) is left alone. */
+function decline(chunks, target, values) {
+    if (!chunks.every((chunk) => typeof chunk === "string"))
+        return chunks;
+    const name = chunks.join("");
+    if (target === undefined)
+        return name;
+    const gender = genderOf(values?.gender);
+    return vokativ(name, {
+        ...(gender && { gender }),
+        ...(target !== "keep" && { script: target }),
+    });
+}
+/** The `gender` value a message often already gets, for "Dragi/Draga": decides surnames. */
+function genderOf(value) {
+    if (value === "m" || value === "male")
+        return "m";
+    if (value === "f" || value === "female")
+        return "f";
+    return undefined;
+}
+const scanned = new WeakMap();
+/** Whether a message uses the tag: as written, or precompiled, where it's `["voc", …]`. */
+function mentionsVoc(message) {
+    if (typeof message === "string")
+        return message.includes("<voc>");
+    if (typeof message !== "object" || message === null)
+        return false;
+    let found = scanned.get(message);
+    if (found === undefined) {
+        found = JSON.stringify(message).includes('["voc"');
+        scanned.set(message, found);
+    }
+    return found;
+}

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@lunmark/vokativ-next-intl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Serbian vocative for next-intl: write <voc>{name}</voc> in a Serbian message and the name is addressed properly.",
+  "keywords": [
+    "serbian",
+    "srpski",
+    "vokativ",
+    "vocative",
+    "next-intl",
+    "next.js",
+    "i18n"
+  ],
+  "license": "MIT",
+  "author": "Lunmark",
+  "homepage": "https://gitlab.com/lunmark/vokativ/-/tree/main/vokativ-next-intl#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/lunmark/vokativ.git",
+    "directory": "vokativ-next-intl"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/lunmark/vokativ/-/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "default": "./dist/vitest.js"
+    },
+    "./format-message": {
+      "types": "./dist/format-message.d.ts",
+      "default": "./dist/format-message.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@lunmark/vokativ": "^0.1.0"
+  },
+  "peerDependencies": {
+    "next": "^15.3.0 || ^16.0.0",
+    "next-intl": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.14",
+    "@types/node": "^24",
+    "@types/react": "^19.3.0",
+    "icu-minify": "^4.14.9",
+    "next": "^16.4.2",
+    "next-intl": "^4.14.9",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^6.0.3",
+    "use-intl": "^4.14.9",
+    "vitest": "^5.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.14.0",
+      "onFail": "download"
+    },
+    "runtime": {
+      "name": "node",
+      "version": ">=24"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/fix-declarations.ts",
+    "check": "biome check",
+    "fix": "biome check --write",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }