Three weeks ago I shipped a bilingual LMS. The architecture modeled one language as source and the rest as overlay: a source_locale column on every translatable entity, an MT pipeline reading source rows and writing overlay rows. It worked. Students used it. Certificates issued. Three published courses, fourteen real users, end-to-end.

Last week it broke in a way that did not fit a bug fix.

A teacher whose interface was set to English wrote a course entirely in Russian. The system saw teacher.preferred_locale = 'en', stamped source_locale = 'en' on every course field, and then served Russian students a course labelled "Russian translation of an English source" — when no English source existed, ever. The fallback path showed [translation missing] placeholders on a course that was, in fact, perfectly written in the language being requested.

The first fix attempt was a heuristic: detect the actual character set of the content and derive source_locale from that, not from the teacher's UI. Better. Still wrong, because per-entity source locale assumes the entity is monolingual — and there is no rule that says it has to be. A course with an English title and a Russian description is one entity with no single answer to "which locale is source?"

The second attempt moved detection per-field. Better still. Still wrong, because per-field source locale assumes the field is monolingual — and there is no rule that says it has to be. A bilingual paragraph (a sentence in English, a Russian phrase set off in italics, a quoted scripture reference) has no single answer either.

At that point the model is the bug, not the heuristic.

Locale is just a column

The new schema, shipped to main last night across eight stacked PRs:

CREATE TABLE content_versions (

    id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),

    entity_type        text NOT NULL CHECK (entity_type IN (

                           'course','chapter_block','assignment','cohort',

                           'course_event','announcement', ...

                       )),

    entity_id          uuid NOT NULL,

    field              text NOT NULL,

    locale             text NOT NULL CHECK (locale IN ('en','ru')),

    body               text NOT NULL,

    origin             text NOT NULL CHECK (origin IN ('human','mt')),

    source_version_id  uuid REFERENCES content_versions(id),

    superseded_by      uuid REFERENCES content_versions(id),

    created_at         timestamptz NOT NULL DEFAULT now(),

    created_by         uuid REFERENCES auth.users(id)

);



CREATE UNIQUE INDEX content_versions_active_unique

ON content_versions (entity_type, entity_id, field, locale)

WHERE superseded_by IS NULL;

Every (entity, field, locale) is its own row. There is no source locale and no overlay. There are rows that exist because a human wrote them, rows that exist because the MT pipeline produced them, and the lineage between them. The thing that says "this Russian title was machine-translated from that English title" is source_version_id. The thing that says "an editor revised it" is superseded_by. The thing that says "what language is this row" is locale. No row outranks another by default.

The model is symmetric. The data is the data. Adding a third language is INSERT INTO content_versions ... plus appending a string to a Pydantic Literal. Zero DDL. No schema deltas. No "let's refactor source_locale to be nullable for the Spanish migration."

What this fixes that you can name

The "Тайтл" bug class disappears entirely. There is no source_locale column to be wrong, so it cannot be wrong. A teacher's UI preference no longer leaks into the content model.

Mixed-language entities are first-class. A course with an English title and a Russian description is two content_versions rows. Each one is correct in isolation. No "what's the source locale of this course" question to argue about, because no field on the entity claims to know.

Translation history is preserved by construction. Editing a row creates a new row with superseded_by pointing at the old one. The previous translation is not overwritten or archived in some side table; it is still in content_versions, just with a non-null superseded_by. The active row is the one with superseded_by IS NULL, enforced by the partial unique index above.

Cascade invalidation gets precise. When the English title is edited, the MT rows that were generated from it — and only those — get invalidated, via source_version_id. The old code had to purge_course_translations(course_id) and re-translate everything, because the lineage was not recorded anywhere readable. The new code knows exactly which rows depend on which.

What stays true from before

The registry pattern still holds. The fact that an entity has translatable fields is declared once, in backend/app/services/translation/registry.py, and read by the orchestrator, the schemas, and the CI guard. The schema change did not move this; it sharpened it. The registry now declares "this entity has these fields in content_versions" instead of "this entity has these _ru/_en overlay columns."

The Bible substitution layer still holds. Canonical text — KJV, Synodal, anything where the wording is a contract with the reader — never goes through the LLM. The MT pipeline substitutes placeholders, translates the prose around them, restores canonical target-locale text. The new model did not touch this. It could not; canonical text is not translated content. It is content that happens to exist in multiple locales because the canon exists in multiple locales. The substitution layer just makes sure the canonical version is the one that ships.

The three-layer split still holds. UI strings, user-generated content, canonical artifacts — three problems, three mechanisms, one product. The new model only touches the middle layer. The other two were already right.

The principle, generalized

The "source language" idea is a residue of monolingual-first design. Pick almost any i18n library, almost any LMS, almost any CMS, and you will find the same implicit assumption: one language is canonical, the rest are derived. Defaults, fallbacks, base locales, primary languages, source-of-truth columns. They all encode the same idea — somebody's language is real, everybody else's is a copy.

For documentation, that may be honest. The MDN reference is in English; the French version is a translation of the English version; calling English the source is correct because it is. For a product that serves bilingual or multilingual users as equally first-class — a faith community, an immigrant network, a multilingual school — the assumption is wrong, and it leaks. Every dropdown that says "EN (Original)", every fallback_locale: 'en' in a config file, every test that asserts the English string and ignores the Russian one, is a cultural primacy choice masquerading as engineering simplicity.

The cost of refusing the assumption is real but bounded. The backfill script is ~550 lines of dual-write reconciliation. The schema is symmetric, so there is no per-language DDL. Read paths read one table, not "canonical column union overlay table." The whole migration is in flight as a six-phase stacked PR — half shipped, the rest sequenced with DO NOT auto-merge until previous live + 7 days, take pg_dump, confirm PITR window, schedule Tue/Wed UTC. Boring, careful, recoverable. The principle is sharp; the rollout is not.

How to verify you have the same bug

Two checks. If your data model has a source_locale (or original_locale, or default_locale) column on a translatable entity, you have a primary language. If your application config has a fallback_locale and your read paths use it when a translation is missing, you have a primary language. Either is the residue. Both is the full version.

The honest move is to model what is actually true: a course has content. Some of that content is in English. Some is in Russian. Some was written by a human. Some was generated by an MT pipeline from a specific human-written version. None of those facts make any language more real than any other.

Bigger than i18n

The deeper read is that the "source plus overlay" pattern is a default reach for any time you have versions of the same thing in different shapes: translations, variants, A/B copy, accessibility re-writes, plain-language summaries, audio scripts. The same model — every variant is a row, lineage is explicit, supersession is preserved, no variant is privileged by schema — generalizes cleanly past locale.

If you are building anything where multiple variants of the same content need to coexist as equals, the question is not which one is the source. The question is what is the lineage, and who or what wrote each row.

If your bilingual app has a fallback locale, you have already chosen which language is real.

Equip is open source under MIT at github.com/ArVaViT/equip. Live at equipbible.com. The content_versions foundation migration is supabase/migrations/20260527230000_content_versions_foundation.sql. The six-phase rollout spans PRs #531 through #553 — Phase 1 (dual-write) is fully merged across all eleven translatable entity types; Phases 2 through 5 (dual-read with comparator, backfill, cv-primary read behind a flag, delete legacy + drop content_translations + drop the source text columns) are sequenced as an open stack.

ArVaViT
/
equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools
church ministries, and nonprofit educational programs

Live demo ·
Roadmap ·
Contributing ·
Support ·
Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Hundreds of small Bible schools, home churches, and missionary training
programs around the world still manage courses on paper, WhatsApp, or
spreadsheets. Commercial LMS platforms are expensive, overkill, or require
technical expertise that volunteer-run organizations simply don't have.

Equip is designed to change that:

• 
  Free forever — MIT-licensed, no paywalls, no "premium" tiers.


• 
  Simple to deploy — one-click Vercel deploy with a free Supabase
  database. No Docker, no servers to manage.


• 
  Built for small scale — optimized for 20-100 students, not…

View on GitHub