Projects

A Messagevisor project is a Git repository containing authoring definitions, tests, configuration, out of which you can generate artifacts such as datafiles and a browsable catalog.

Different approaches#

You can manage a Messagevisor project in a few different ways:

Independent Git repository#

• Option A: with a single set of definitions
• Option B: with multiple sets of definitions

Monorepo#

Keep definitions alongside your application code in a single repository.

We will focus on the independent Git repository approach in this documentation.

Initialize a new project#

You can initialize a new project with the following command:

$ mkdir my-messagevisor-project && cd my-messagevisor-project
$ npx messagevisor init

Directory structure#

Scaffolded with the YAML starter:

.
├── attributes/             # context schemas
├── catalog/                # generated by `npx messagevisor catalog export`
├── datafiles/              # generated by `npx messagevisor build`
├── locales/                # locale metadata, inheritance, formats
├── messages/               # translations and overrides
├── segments/               # reusable conditions
├── targets/                # config for generating targeted datafiles
├── tests/                  # picked up by `npx messagevisor test`
├── messagevisor.config.js  # project configuration
└── package.json

Not every project needs every directory at first, but this is the usual shape.

What lives where#

Available starters#

You can choose which starter project to initialize by passing the --project flag to the init command, like:

$ npx messagevisor init --project=<name>

Sets-based starter#

The concept of sets is best illustrated with an example:

sets
├── my-first-set
│   ├── locales
│   ├── messages
│   ├── targets
│   └── tests
├── my-second-set
│   ├── locales
│   ├── messages
│   ├── targets
│   └── tests
├── messagevisor.config.js
└── package.json

The idea is to have multiple sets of definitions, each with its own set of definitions, that are isolated from each other.

Sets can also be used to establish a promotion workflow between sets. Think of having a different set for each of your environments: dev, staging, and production, and linearly promoting content changes from one set to another:

sets
├── dev
│   ├── locales
│   ├── messages
│   ├── targets
│   └── tests
├── staging
│   ├── locales
│   ├── messages
│   ├── targets
│   └── tests
├── production
│   ├── locales
│   ├── messages
│   ├── targets
│   └── tests
├── messagevisor.config.js
└── package.json

Learn more in Sets and Promotions.

Git-first workflow#

Messagevisor is designed for repositories where:

• definitions are code-reviewed
• examples and tests live beside the content they validate
• generated artifacts can be rebuilt deterministically

That makes it a good fit for teams that want translation behavior to be reviewable in the same way as code changes.

Projects with and without sets#

Without sets, one project contains one definition tree.

With sets enabled, each set behaves like its own authored project under sets/<name>/..., while still sharing one top-level project configuration file via messagevisor.config.js.

Use sets when you need:

• staged environments
• promotion workflows
• multiple parallel definition trees in one repository

Use plain projects when you just need one canonical set of definitions.

Generated artifacts#

Projects generate:

• datafiles/ from npx messagevisor build (see Building datafiles)
• catalog/ output from npx messagevisor catalog export (see Catalog)
• CSV exports from npx messagevisor export (see Export and import)

These outputs are derived from authoring definitions and configuration. They are important operational artifacts, but the authored definitions remain the source of truth.

Where to go next#

• Start with project Configuration if you are shaping repository layout
• Read Locales, Messages, and Targets together if you are modeling content
• Read Attributes, Segments, and Overrides together if you are modeling conditional behavior
• Read Testing and Catalog if you want a strong review and debugging workflow

Related#

• CLI
• State files