Translatable Domain Model

Also Known As

TL;DR

Explanation

A translatable domain model treats locale-varying content (names, descriptions, slugs, units, currencies) as a structural property of the entity rather than an afterthought. Instead of one flat `name` column, the model exposes translations keyed by locale, with a defined fallback strategy when a locale is missing. Two common patterns exist: a translation-table approach (a parent entity row plus a child `entity_translations` table with one row per locale) and an embedded approach (a value object holding a map of locale to text). The key design decision is which fields are translatable - some are (product description), some are locale-formatted but not translated (price, stored as a raw amount plus currency), and some are locale-independent (SKU, internal IDs). Building this distinction into the aggregate avoids the classic retrofit where a single-language schema is patched with parallel tables, string concatenation hacks, or duplicated rows per language. A well-designed translatable model also separates content translation from locale-aware formatting: the model holds the translated string, while presentation applies NumberFormatter or IntlDateFormatter at render time. Fallback rules belong in the domain (request fr-CA, fall back to fr, then to a default locale) so that every consumer behaves consistently. Query patterns matter: loading an entity should not trigger one extra query per translation (N+1), so translations are typically eager-loaded for the requested locale only. Treating translation as a domain concern keeps invariants enforceable - for example, requiring at least the default-locale value to be present before an entity can be published. Retrofitting i18n onto an anemic single-language model is one of the most expensive refactors a product faces, because it touches the schema, the repository, every read path, and search indexing simultaneously.

Common Misconception

Why It Matters

Common Mistakes

• Storing one translation per row by duplicating the whole entity, which breaks referential integrity for non-translatable fields like SKU.
• Treating every field as translatable, including IDs and raw prices that should be locale-formatted, not translated.
• Loading translations with one query per locale or per row, producing N+1 queries on list pages.
• Defining no fallback strategy, so a missing locale renders an empty string or a 500 instead of the default-locale value.
• Mixing translation content with formatting, hardcoding currency or date strings inside the stored translated text.

Avoid When

• The product is single-locale by contract and has no roadmap toward multiple languages.
• Content is purely numeric or locale-independent (raw measurements, identifiers) where formatting alone suffices.
• An off-the-shelf CMS already owns translation and the domain only consumes rendered output.

When To Use

• The application serves users in multiple languages or plans to within its lifetime.
• Entities carry user-facing text (names, descriptions) that differs per locale and needs fallback rules.
• You need domain invariants like 'default-locale content required before publish' enforced consistently.
• Search, slugs, or URLs must vary per locale and be queryable without N+1 loads.

Code Examples

// Single-language model retrofitted with hacks:
class Product {
    public string $name;        // only ever one language
    public string $description;
    public string $priceLabel;  // '$19.99' baked in
}

// Later 'fix': duplicate the row per language
// products: (id, lang, name, description, price_label)
// SKU and stock now duplicated and drift out of sync
$row = $db->query("SELECT * FROM products WHERE id=? AND lang=?", [$id, $lang]);
echo $row['name'] ?? '';     // missing locale -> blank

// Translatable by design:
final class Translation {
    public function __construct(public readonly string $name) {}
}

final class Product {
    public function __construct(
        public readonly string $sku,        // locale-independent
        public readonly int $priceCents,    // raw amount, formatted at render
        public readonly string $currency,   // 'EUR'
        /** @var array<string, Translation> */
        private array $translations,        // ['en' => Translation, 'de' => ...]
        private string $defaultLocale = 'en',
    ) {}

    public function name(string $locale): string {
        foreach ($this->fallbackChain($locale) as $l) {
            if (isset($this->translations[$l])) {
                return $this->translations[$l]->name;
            }
        }
        throw new \LogicException('Default locale translation required');
    }

    private function fallbackChain(string $locale): array {
        $base = explode('-', $locale)[0];
        return array_unique([$locale, $base, $this->defaultLocale]);
    }
}

// Presentation formats raw values, never the stored string:
$fmt = new NumberFormatter('de-DE', NumberFormatter::CURRENCY);
echo $product->name('de-DE');
echo $fmt->formatCurrency($product->priceCents / 100, $product->currency);

Tags

Related Terms

References

• https://www.php.net/manual/en/book.intl.php
• https://www.w3.org/International/questions/qa-choosing-language-tags
• https://www.rfc-editor.org/rfc/rfc4647