---
title: Translation
description: Translation for experimental CMMF 1.3.0-beta.1.
editUrl: https://github.com/cmmf-project/content-model-master-format/blob/a0c7a3d87fe46d74b5e78ac851e8b156201376a4/docs/translation-concepts.md
---

## Why Translation Needs Its Own Mental Model

CMMF is designed as a source format, not as a direct declaration of one CMS implementation.

That means translation is not a mechanical copy step. It is a controlled decision-making process that maps source intent into a target platform.

## Why Translation Is Not Fully Deterministic

Two translators can produce different but valid outputs from the same CMMF input.

For example, a contained structure may become:

- an embedded object in one platform
- a separate content type in another
- a reusable block schema in a third

The important thing is not that every target looks the same. The important thing is that the source intent is preserved and translation decisions are explicit.

## What Translators Should Preserve

A translator should preserve:

- model identity
- field identity
- content structure
- relationship semantics
- meaningful validation intent
- important editorial metadata where feasible

## What Translators May Need to Decide

A translator may need to decide:

- whether to inline or split structures
- how to represent contained ownership
- how to handle unsupported validation features
- how to represent settings and taxonomy constructs
- how much to optimise for target-platform conventions

## Why a Decisions Log Matters

Without a decisions log, translators become black boxes. That makes debugging, governance, and architecture review much harder.

A good decisions log explains:

- which choices were fixed by spec
- which were inferred
- which were target-platform compromises
- which were lossy

## Recommended Modes

Future translators will likely benefit from explicit modes such as:

- `strict`
- `optimised`

`strict` focuses on preserving source intent as directly as possible. `optimised` allows more adaptation for target-platform fit, while still documenting those adaptations.

## Document-Level Hint Decisions

In this 1.3.0-beta.1 branch, every `validationHints` declaration requires a
disposition identifying its model and hint, with a reason. This applies to
structured hints, expressions with unknown dialects, and prose alike.

```yaml
decisionsLog:
  - modelId: article
    hintId: external-requires-source
    disposition: degraded
    reason: >-
      Generated editorial guidance describing conditional source_url
      requiredness; no conditional validation integration was generated.
  - modelId: subscription
    hintId: quarterly-price-bound
    disposition: unmapped
    reason: >-
      This translator does not understand jsonlogic and cannot generate
      meaningful target guidance for this rule.
```

`mapped` means the declared intent and severity are preserved. `degraded` means
some intent survives with a documented loss; guidance text alone falls here.
`unmapped` means no usable target representation was produced. The YAML shape is
illustrative: the [beta contract](/spec/1.3.0-beta.1/translation-contract/)
requires the information, not a particular serialization. These decisions do
not evaluate content and do not change authoritative field constraints.


<div class="source-note">Source: <a href="https://github.com/cmmf-project/content-model-master-format/blob/a0c7a3d87fe46d74b5e78ac851e8b156201376a4/docs/translation-concepts.md">CMMF 1.3.0-beta.1 at a0c7a3d8</a> · <a href="/raw/1.3.0-beta.1/docs/translation-concepts.md">Download original Markdown</a></div>