Namespaces

Namespaces in Messagevisor are derived from directory structure.

How keys are derived#

Message keys are formed by joining the path segments from the file's location relative to messagesDirectoryPath:

messages/checkout/total.yml          -> checkout.total
messages/auth/signin.yml             -> auth.signin
messages/notifications/email.yml     -> notifications.email
messages/app/nav/header.yml          -> app.nav.header

The top-level filename (without extension) becomes the last segment. Directories become intermediate segments.

Namespace separator#

The separator between segments is controlled by namespaceCharacter in your config:

module.exports = {
  namespaceCharacter: ".",
};

With ".", a file at messages/auth/signin.yml becomes auth.signin. With "/" it would become auth/signin.

The same separator applies to:

• attribute keys (derived from attributes/)
• segment keys (derived from segments/)
• all other keyed entity directories

Why it matters#

The namespace character directly shapes:

• all runtime message keys used in translate() and t()
• code generation output (TypeScript key unions and helpers)
• CLI patterns like --includeMessages=auth* and --excludeMessages=admin.*
• CSV export row keys
• catalog display

Changing namespaceCharacter after a project is in use requires updating all references to the old key format.

Attributes and other entities#

The same path-to-key rule applies to attributes and segments:

attributes/platform.yml              -> platform
attributes/user/role.yml             -> user.role
segments/plan-pro.yml                -> plan-pro
segments/checkout/vip.yml            -> checkout.vip

Nested attribute keys can be used with dot notation in conditions:

conditions:
  - attribute: user.role
    operator: equals
    value: admin

Related#

• Configuration
• Messages
• Attributes
• Segments
• CLI