Namespaces

A namespace is a dotted path into the merged message tree - core.global, @vitnode/blog.admin.article. It is the unit of two things at once: what useTranslations reads from, and what a page is allowed to download. The merged tree holds every installed plugin's copy, and no page should ship all of it, so a page names the branches it renders and gets exactly those.

Example

{
  "my-plugin": {
    "home": { "title": "Hello World" },
    "admin": { "overview": { "title": "My plugin" } }
  }
}

const t = useTranslations('my-plugin.home')

Two namespaces exist there - my-plugin.home and my-plugin.admin.overview - and a page that renders the public one never downloads the admin one.

The tree

Everything sits under the id of the package that owns it. Core owns three branches; a plugin owns exactly one, named after itself.

core.global is special only in that it is provided above every route, so any shared component can translate itself wherever it is mounted. Everything else is asked for.

The per-plugin prefix rule

Every top-level key a plugin ships is the plugin's own id. A key outside it collides with core and with every other plugin, so VitNode ignores it rather than letting two packages fight over one path.

{
  "my-plugin": {
    "hello": "Hello World"
  },
  "world": "World"
}

Scoped ids work exactly the same way - @vitnode/blog is one path segment even though it contains a slash, so @vitnode/blog.admin is a legal two-segment namespace.

Asking for a namespace

Declare the exact branches a plugin page renders as the route's messages. VitNode loads them with the route chunk, so public pages do not download a plugin’s AdminCP copy just because it exists.

import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/reports', {
    component: lazy(() => import('./pages/reports-page')),
    messages: ['my-plugin.reports'],
  }),
])

A route inherits every namespace its layouts declare, so a shared frame can name them once for a whole subtree. The route module then calls useTranslations('my-plugin.reports'); if a key renders as its own name, confirm the route declared the matching namespace.

Limits

A namespace list reaches the server through a server function, which is a public POST endpoint once the app is built. So the rules are enforced rather than assumed, and the same rules validate a plugin's build-time declaration - one definition, in @vitnode/core/routing, so a route tree cannot accept something the server refuses.

On top of the numbers: a namespace must be a non-empty string, must not contain an empty segment (core..global, a leading or trailing dot), and must not contain __proto__, constructor or prototype in any segment. All three are rejected outright rather than filtered away - a namespace containing one is not a namespace with a typo in it.

Import the constants if you need to budget against them:

import { MAX_NAMESPACES } from '@vitnode/core/tanstack/i18n'

Gotchas

Next