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.
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.
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:
Proposed Error Message
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.