Open source CapCut alternative.
TypeScript
docs: teach translations and gate stale ones
David Lecaa9a239066b
diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.ymlindex a733cbce..cb5a2640 100644--- a/.github/workflows/deploy-site.yml+++ b/.github/workflows/deploy-site.yml@@ -67,6 +67,7 @@ jobs:run: |node --test scripts/prepare-vercel-build.test.mjsnpm test+ npx bun scripts/i18n-translate.ts --check# The Vercel project sets site/ as its root directory. Run its CLI from# the repository root so both the build and upload resolve that directory.diff --git a/AGENTS.md b/AGENTS.mdindex 27679673..325cebe6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -20,6 +20,8 @@ Performance comes first. Everything we ship has to be fast on the machines peoplEvery UI addition or change accounts for dark mode. Read the [UI Quality skill](.claude/skills/ui-quality/SKILL.md) and verify text, icons, and control states in light and dark themes.+Every string a person reads comes from the English catalogs in `site/src/i18n/messages/en/`. After adding or changing one, run `npx bun scripts/i18n-translate.ts` in `site/` so every language updates in the same change; CI fails on stale translations. Super-user surfaces stay English. `docs/guides/i18n.md` is the guide.+## Site ProjectBefore changing `site/` UI, routes, API handlers, or data access patterns:diff --git a/CLAUDE.md b/CLAUDE.mdindex 27679673..325cebe6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,6 +20,8 @@ Performance comes first. Everything we ship has to be fast on the machines peoplEvery UI addition or change accounts for dark mode. Read the [UI Quality skill](.claude/skills/ui-quality/SKILL.md) and verify text, icons, and control states in light and dark themes.+Every string a person reads comes from the English catalogs in `site/src/i18n/messages/en/`. After adding or changing one, run `npx bun scripts/i18n-translate.ts` in `site/` so every language updates in the same change; CI fails on stale translations. Super-user surfaces stay English. `docs/guides/i18n.md` is the guide.+## Site ProjectBefore changing `site/` UI, routes, API handlers, or data access patterns:diff --git a/docs/guides/cut/ai-assistant.md b/docs/guides/cut/ai-assistant.mdindex b1e541ff..364f98a6 100644--- a/docs/guides/cut/ai-assistant.md+++ b/docs/guides/cut/ai-assistant.md@@ -1,6 +1,6 @@# Donkey Cut's AI Assistant-The assistant is the chat panel inside the Donkey Cut editor. It answers questions about the open project and edits it by calling typed tools against the live editor state, while the user watches the changes land. Three providers share one brain — the user's Claude Code login, the user's Codex login, and Gemini through Donkey's hosted inference — and all three get the same system prompt, tool catalog, and skills library; only the transport differs.+The assistant is the chat panel inside the Donkey Cut editor. It answers questions about the open project and edits it by calling typed tools against the live editor state, while the user watches the changes land. Three providers — Claude Code, Codex, and Gemini through Donkey's hosted inference — get the same system prompt, tool catalog, and skills library; only the transport differs.**The one rule: the model makes every decision.** No code inspects the user's words. A message goes to a model with the project state attached, and the harness acts only on the typed tool calls that come back. If you're tempted to write `if (text.includes("subtitles"))` anywhere in the chat path, that knowledge belongs in the system prompt, a tool description, or a skill.@@ -59,7 +59,7 @@ Every knowledge surface is defined once — the catalog file ships in the engine| Surface | Size today | When it enters context || --- | --- | --- |-| System prompt | ~13K chars (~3K tokens) | Claude: replaces the Agent SDK default. Codex: prepended to the first turn (a resumed session already has it). Gemini: the instructions field, every round. |+| System prompt | ~13K chars (~3K tokens) | Claude: replaces the Agent SDK default. Codex: prepended to a fresh session's first turn. Gemini: the instructions field, every round. Written for the page's language, which replies follow. || Tool catalog (127 tools in 19 areas) | ~140K chars (~35K tokens) whole | Core plus the routed areas; the whole catalog when unjudged. || Skills library (16 docs) | ~97K chars (~24K tokens) total | The judge's pick rides the turn; list-skills and read-skill cover the rest. || Editor snapshot | Grows with the project; media list and subtitle cues capped at 60 each | Attached to the newest user message as `<editor_state>`, rebuilt fresh every turn. |diff --git a/docs/guides/frontend-nextjs-guidelines.md b/docs/guides/frontend-nextjs-guidelines.mdindex 31055ffc..fdb2ff10 100644--- a/docs/guides/frontend-nextjs-guidelines.md+++ b/docs/guides/frontend-nextjs-guidelines.md@@ -15,9 +15,8 @@ inline, the call belongs in a hook.- Shared UI primitives live in `src/components`; route-specific UI stays nearthe route, such as `src/app/_components/landing` for the home page.- Server-only helpers live in `src/lib`.-- Split large route experiences into focused component files.-- Use absolute imports through the `@/*` alias; avoid barrel `index.ts` files- unless a package-level public API truly needs one.+- Use absolute imports through the `@/*` alias; avoid barrel `index.ts` files.+- Every string a person reads comes from a catalog; see [Translations](i18n.md).## Componentsdiff --git a/docs/guides/i18n.md b/docs/guides/i18n.mdnew file mode 100644index 00000000..6f9fa532--- /dev/null+++ b/docs/guides/i18n.md@@ -0,0 +1,73 @@+# Translations++Donkey Cut ships in English, Spanish, Brazilian Portuguese, French, German,+Japanese, Korean and Simplified Chinese, on the site, the Mac app and the iOS+app. People write English; a script writes every other language from it.++**The one rule:** every string a person reads comes from a catalog. Code that+writes `<span>Export</span>` ships English to a Japanese reader, and the lint+guard fails it.++## How it works++```text+request (no language in the URL)+ ↓+proxy: the language cookie, else the browser's Accept-Language+ ↓+rewrite to the hidden language segment of the route tree+ ↓+server renders <html lang> and hands each subtree only its catalogs+ ↓+picker or account change → write the cookie → reload+```++One URL serves every language, so pages stay static per language and caches+key on the URL. Crawlers send no cookie and get English. Only the footer+picker, the Settings picker and the account write the cookie; a detected+language never lands in the cookie.++A signed-in account carries its language. When the editor loads, a stored+language that differs from the page switches the page to it, and an account+with none takes the page's. Emails and headless chat turns read the account's+language.++## Catalogs++English lives in one JSON file per area, and its keys type every `t()` call,+so a missing key is a compile error. Messages use ICU: arguments for+interpolation, plurals for counts, one message per sentence. Never build a+sentence from translated fragments.++Registry labels (effects, transitions, looks) keep their English in the+registry for the model, and the UI looks each id up in the labels catalog. A+test keeps the two in step.++A failure a person reads is thrown as a coded error with its English message.+The page words it from the errors catalog by code; logs and the model keep the+English.++## What stays English++| Stays English | Why |+| --- | --- |+| Prompts, tool descriptions, model-facing errors | The model reads them |+| Privacy and Terms bodies | The English text is binding |+| Blog articles | Not translated yet; they will take a language prefix when they are |+| Brand names, shortcuts, file formats | The glossary holds them fixed |+| Super-user settings and flags | Only operators read them |++The chat answers in the interface language unless the person writes in+another.++## The translation script++`bun scripts/i18n-translate.ts` translates every key that is new or whose+English changed, using a lock file of English hashes per catalog. Each result+must keep its English's arguments, plurals and tags; one that drifts is+retried once and then fails the run. It also fills the Mac and iOS String+Catalogs and the back office's email catalogs (`--dir`), and `--check` fails+when anything is stale.++The code lives in the site's i18n folder, with the script beside the other+site scripts.diff --git a/docs/guides/swift.md b/docs/guides/swift.mdindex a8107a84..606a3724 100644--- a/docs/guides/swift.md+++ b/docs/guides/swift.md@@ -43,14 +43,15 @@ points through Accessibility; app minimum sizes appear in the controls.- Define a protocol where a seam needs testing or multiple conformers exist.Write `some Protocol` by default; `any Protocol` only for heterogeneousvalues. Models may depend on narrow provider protocols.-- Name methods so call sites read as phrases: `list.insert(element, at: index)`.+- Text a person reads comes from the target's String Catalog, through+ `String(localized:)` or a SwiftUI literal; `site/scripts/i18n-translate.ts`+ translates the catalogs.## Concurrency- Stay on the main actor and leave it deliberately. Projects set default actorisolation to the main actor, so views, models, and helpers agree by- construction — models publishing UI state and controllers touching AppKit- are covered with zero annotations.+ construction.- Mark CPU-heavy async work `@concurrent` to move it off the main actor:parsing, image work, encoding.- Use an actor for mutable state hit from many tasks: caches, download@@ -67,8 +68,8 @@ points through Accessibility; app minimum sizes appear in the controls.- State lives in `@Observable` classes. The view that creates a model owns itwith `@State`; app-wide services inject with `@Environment`; write access tosomeone else's state passes as `@Binding` or `@Bindable`.-- Models import Foundation only. A SwiftUI or AppKit import in a model means- view or controller concerns leaked in, and it costs headless testability.+- Models import Foundation only; a SwiftUI or AppKit import in a model costs+ headless testability.- Navigation: `NavigationStack` with typed path values for drill-down;`NavigationSplitView` for sidebar layouts, which collapse to a stack oniPhone.