Skip to content

Clarify "missing_placeholder_in_template" error message #183

@JanCizmar

Description

@JanCizmar

When the CLI exports keys that belong to more than one namespace, it currently throws the missing_placeholder_in_template error if fileStructureTemplate lacks the {namespace} placeholder. The message, however, does not explain why this is required, leading to confusion.

Steps to Reproduce

Configure fileStructureTemplate without the {namespace} placeholder, e.g.

fileStructureTemplate: "locales/{language}.json"

Export namespaces common and admin together using the CLI.

Current Behavior

The CLI fails with the error code missing_placeholder_in_template, but the message does not clarify the root cause or how to fix it.

Expected Behavior

The error message should:

  • Explicitly state that multiple namespaces were detected.
  • Explain that writing all namespaces to a single file leads to key collisions and unpredictable results.
  • Point out that the purpose of namespaces is to separate content into distinct files.
  • Provide an actionable fix (i.e., add {namespace} to the template or export one namespace at a time).

Proposed Error Message

Error: Your export involves multiple namespaces (e.g. "common", "admin"), but
`fileStructureTemplate` does not contain the `{namespace}` placeholder.

Without `{namespace}`, the CLI would merge all namespaces into the same file,
causing key conflicts and unpredictable overrides.  
→ Add `{namespace}` to `fileStructureTemplate` (e.g. "locales/{namespace}/{language}.json")  
  or export a single namespace at a time.

Additional Context

Namespaces exist precisely so that translations can be split into separate files; a single‑file export defeats that purpose.

Because there is no deterministic way to resolve key collisions across namespaces, the CLI must enforce this constraint.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions