FAQ

Is Messagevisor only for YAML?#

No. YAML is the default and the primary authoring style, but JSON is also supported as a built-in parser. Custom parsers are also possible if your project uses a different format.

Do I have to use sets?#

No. Sets are optional. Most projects start without sets. Use them when you need multiple parallel definition trees - for example, environments like dev, staging, and production, or product variants that need different translation sets.

Do I have to commit generated datafiles?#

Not necessarily. Some teams commit them so they are always available without a build step. Others build them in CI and serve them from a CDN or object storage. Either approach works; the choice usually depends on your deployment model.

Can Messagevisor evaluate raw strings too?#

Yes. The CLI evaluate --rawMessage=... and SDK formatMessage() flows accept raw message strings directly. This is useful for testing ICU or interpolation syntax before authoring a full message file.

What is the difference between a segment and an inline condition on an override?#

Both express conditional logic. A segment is a named, reusable condition you define once and reference from many overrides. An inline conditions block on an override is a one-off condition specific to that override.

Use a segment when:

• the condition appears in more than one message
• you want to test the condition directly
• you want the condition named for readability in the catalog

Use inline conditions when:

• the logic is small and specific to one message
• creating a segment file would just add noise

What is the difference between a target and a set?#

They model different concerns:

• a target is a runtime output slice - it controls which messages, locales, and formats go into a built datafile
• a set is a parallel authoring tree - it models different definition versions, such as staging vs production

You can have targets without sets (most projects do). Sets are for managing multiple concurrent versions of your authoring content, not for slicing the output.

Why does a segment condition disappear from my built datafile?#

If target context makes a condition always true or always false, the builder removes impossible branches at build time. This is intentional - it shrinks the datafile and prevents dead overrides from appearing in production.

If you want all overrides to survive into the datafile, do not set context on the target, or remove the conflicting context key.

How do locale inheritance and override inheritance interact?#

They are resolved independently:

• inheritTranslationsFrom resolves the base translation for a message
• inheritFormatsFrom resolves formatting presets

When a locale inherits from another, override translations follow the same chain. If en-US inherits from en, an override translation authored for en will also be visible to en-US unless en-US has its own override translation.

See Inheritance for the full workflow.

How do I send translations to an external translator?#

Use npx messagevisor export to produce a CSV, send that CSV for translation work, then preview the returned file with npx messagevisor import before applying it with --apply.

See Export and import.

Can I use Messagevisor with Next.js, Astro, Express, or Fastify?#

Yes. The framework guides show how to load datafiles, create SDK instances, pass request context, and use ICU modules.

See Frameworks.

Can I use Messagevisor in React Native?#

Yes. React Native can use @messagevisor/sdk and @messagevisor/react, with mobile-specific handling for datafile storage, Intl support, platform context, and RTL direction.

See React Native SDK.

What happens when a message key is missing at runtime?#

By default, the SDK does not throw. It reports a missing_translation diagnostic and keeps normal fallback behavior, which returns the per-call defaultTranslation when provided, otherwise the key itself. You can observe this with onDiagnostic and use structured fields like diagnostic.messageKey and diagnostic.locale when routing it.

Can I use ICU plural and select in the same message?#

Yes. ICU syntax supports nesting. You can write {gender, select, male {He has {count, plural, one {# item} other {# items}}} female {She has {count, plural, one {# item} other {# items}}}} and it will evaluate correctly when the ICU module is loaded.

What does promotable: false do?#

It prevents an entity (locale, message, attribute, segment, or individual override) from being updated during a promote operation. Use it for entities that are environment-specific and should not be copied between sets.

For example, if you have a staging-only segment that controls internal test users, set promotable: false on it so it never gets promoted into production.

Can I use Messagevisor without the CLI?#

The CLI handles authoring workflows (build, lint, test, evaluate, export, import, promote). The SDK is separate and can be used independently if you have pre-built datafiles. If you want to skip the CLI entirely, you can build datafiles in code using the @messagevisor/core package directly.

How do I switch locale at runtime?#

Call m.setLocale("fr") (or the equivalent reactive method in the React SDK). If the new locale has a different datafile, call m.setDatafile(newDatafile) first. For reactive updates in React, hooks like useLocale() and useDirection() automatically respond to locale changes.