Translations Manager UI

[stevenle]

Description

Add the translations manager ui that is capable of draft/published states, where translations files are tied to content docs. The translations manager ui can also store non-doc translations, such as for global ui strings.

DB storage is already written, so it's just a matter of wiring up the UI.

Note this issue is just for managing the translations stored in the system (creating strings, importing/exporting, editing and saving translations, etc.). The translations request flow would be handled in #480

Task is kicked off in claude code with the following prompt:

the current version of root's translations system makes it not possible to preview translations before publishing. i'd like to create a "v2" version of translations handling, managed through what i'd call the "translations manager".

we already have some code written for the translations manager's firestore db storage, i'd like to plan out more thoroughly and implement the ui for it. let's do it as an opt-in experimental version first so we can test out the kinks before making it the default.

some things about the ui:

- the ui should resemble similar to a filesystem hierarchy, where we have paths like <Collection>/<docSlug> (slugs with `--` should be treated as subfolders)
- users should be able to create special translations files that are not tied to a doc (like for "global" strings, e.g. header/footer strings or ui common strings like "Learn more")
- when the translations doc is clicked on, it should show the translations editor page for that translations doc and its corresponding doc (if it exists) - the translations page should automatically extract strings form the doc
- it should have draft editing and publishing options, the ability to import/export the translations to a translations service (like google sheets)
- publishing the doc should automatically publish the translations doc

[stevenle]

Translations Manager UI — Implementation Plan

Context

The current translations system (V1) stores translations in a flat Firestore collection with no draft/published — translations can't be previewed before going live. The V2 backend (TranslationsManager class in core/translations-manager.ts) already implements draft/published separation at Projects/{projectId}/TranslationsManager/{mode}/Translations/{id}:{locale}, but has no UI. This plan builds the CMS UI for it as an opt-in experiment gated behind experiments.translationsManager: true.

---

Phase 1: Experiment Flag & Routing Plumbing

1a. Add translationsManager to client-side experiments type

File: ui/ui.tsx:174

Add translationsManager?: boolean to window.__ROOT_CTX.experiments type (alongside existing ai field). The server already passes cmsConfig.experiments as-is to the client context (core/app.tsx:128), so no backend change needed.

File: core/plugin.ts:262

Add translationsManager?: boolean to the experiments type in CMSPluginOptions (alongside existing v2TranslationsManager which can remain for backwards compat).

1b. Conditionally route sidebar Translations button

File: ui/layout/Layout.tsx:143

When experiments.translationsManager is true, change the Translations sidebar link from /cms/translations to /cms/translations/manager. Keeps V1 UI untouched for non-opted-in users.

1c. Register new routes

File: ui/ui.tsx

Add lazy-loaded routes:

/cms/translations/manager                     → TranslationsManagerPage (folder view)
/cms/translations/manager/:collection/:slug   → TranslationsManagerDocPage (editor)

---

Phase 2: Client-Side Firestore Utilities

All reads and writes use the Firebase client SDK directly (no server-side API endpoints).

2a. Translations Manager client module

New file: ui/utils/translations-manager.ts

Functions:

• listTranslationsDocs(mode?) — Queries Firestore Projects/{projectId}/TranslationsManager/{mode}/Translations, groups results by id field (since each locale is a separate doc), returns TranslationsDocSummary[] (deduped by id, with metadata: locales, modifiedAt, publishedAt).

• loadTranslationsDoc(id, mode?) — Queries with where('id', '==', id), aggregates locale docs into MultiLocaleTranslationsMap ({source: {locale: translation}}).

• saveTranslationsDraft(id, strings, options?) — Client-side equivalent of TranslationsManager.saveTranslations(). For each locale found in the strings map, constructs a locale doc at TranslationsManager/draft/Translations/{normalizeSlug(id)}:{locale} and writes via writeBatch. Hashes source strings using hashStr() from shared/strings.ts.

• publishTranslationsDoc(id) — Reads all draft locale docs for the given id, copies them to the published collection with publishedAt/publishedBy timestamps in a batch write.

• createTranslationsDoc(id) — Creates an initial empty draft locale doc for each configured locale.

• deleteTranslationsDoc(id) — Deletes all locale docs (draft + published) for a given id.

Key type:

interface TranslationsDocSummary {
  id: string;           // e.g. "Pages/index", "Global/header"
  locales: string[];
  modifiedAt?: Timestamp;
  publishedAt?: Timestamp;
}

Note: hashStr() from shared/strings.ts uses fnv-plus. Verify the browser bundle includes it. The UI must use the same hash function as the server to produce matching doc keys.

2b. Translations tree builder

New file: ui/utils/translations-tree.ts

• buildTranslationsTree(cmsDocs, translationsDocs) — Takes both CMS collection docs (queried from Firestore Drafts subcollections) and existing V2 translations doc summaries. Merges them so every CMS doc appears in the tree, annotated with whether translations data exists. Groups by first path segment (collection name or "Global"), splits slugs on -- to create subfolder hierarchy.

• filterTranslationsTree(nodes, query) — Filters tree by search string.

Tree node type:

interface TranslationsTreeNode {
  id: string;            // full path: "Pages/about--team"
  name: string;          // display name: "team"
  isFolder: boolean;
  hasTranslations: boolean;  // true if V2 translations data exists
  children: TranslationsTreeNode[];
  docSummary?: TranslationsDocSummary;
}

Example: Pages/index, Pages/about--team, Pages/about--contact, Global/header produces:

Pages/
  index
  about/
    team
    contact
Global/
  header

---

Phase 3: Folder View Page (Translations Manager landing)

New directory: ui/pages/TranslationsManagerPage/

TranslationsManagerPage.tsx

A full-page folder/file browser (NOT a SplitPanel). Shows the translations tree hierarchy as the primary content.

TranslationsManagerPage
├── Layout
│   └── Header: "Translations" title + search input + "New Global File" button
│   └── Content: TranslationsTree (folder/file hierarchy)
│       ├── Collection groups (Pages, Blog, etc.) as expandable folders
│       ├── Global group as expandable folder
│       ├── Slug hierarchy (-- splits into subfolders)
│       └── Leaf nodes are clickable, linking to /cms/translations/manager/:collection/:slug

Behavior:

• Shows ALL CMS collection docs alongside Global entries and any existing translations docs
• Docs with existing translations data are visually distinguished (e.g., icon, badge, or different color)
• Docs without translations show as available but un-translated
• Clicking a leaf node navigates to /cms/translations/manager/{collection}/{slug} (the editor page)
• Search input filters the tree
• "+ New Global File" button opens a small modal to create a Global/{name} translations doc

TranslationsManagerPage.css — Styles following existing BEM conventions.

NewGlobalDocModal

• Text input for the doc name (e.g., "header", "footer", "common")
• Creates at Global/{name} via createTranslationsDoc()
• After creation, navigates to the editor for the new doc

---

Phase 4: Translations Doc Editor Page

New directory: ui/pages/TranslationsManagerDocPage/

TranslationsManagerDocPage.tsx

A full-page translations editor, navigated to when a doc is clicked in the folder view.

TranslationsManagerDocPage
├── Layout
│   └── Header
│   │   ├── Breadcrumbs (Translations > Collection > slug path)
│   │   ├── Status indicator (draft / published / has unpublished changes)
│   │   └── Buttons: Save Draft, Publish, Tools menu
│   └── Content: AG Grid translations table

String extraction:

• If id matches a CMS collection doc (e.g., Pages/index), auto-call extractStringsForDoc(id) to get source strings
• Merge extracted strings with existing translations data from Firestore
• For "Global" docs (no linked CMS doc), show an "Add String" button for manual string entry

AG Grid table:

• Use AG Grid (same dependency as existing TranslationsTable) for sorting, column resizing, virtual scrolling
• Columns: source string + one column per configured locale
• Inline cell editing for translation values
• Ability to show/hide locale columns
• Dirty state tracking via changes map

Save flow:

• "Save" calls saveTranslationsDraft() → writes to Firestore draft collection
• Shows notification via Mantine showNotification()

Publish flow:

• "Publish" opens a confirmation dialog, then calls publishTranslationsDoc()
• Shows notification on success

Tools menu:

• Prune unused strings (reuse PruneTranslationsModal pattern)
• Export to Google Sheet (future, post-MVP)
• Import from Google Sheet (future, post-MVP)

---

Phase 5: Auto-Publish Integration

File: ui/utils/doc.ts:129 — cmsPublishDocs()

After the existing batch commit succeeds, check window.__ROOT_CTX.experiments?.translationsManager. If enabled, for each published docId, fire a non-blocking call to publishTranslationsDoc(docId). Log errors but don't block the doc publish.

if (window.__ROOT_CTX.experiments?.translationsManager) {
  for (const docId of docIds) {
    publishTranslationsDoc(docId).catch((err) =>
      console.warn(`failed to publish translations for ${docId}`, err)
    );
  }
}

---

Phase 6: Import/Export (Post-MVP)

• Google Sheets export: "Export to Sheet" button in editor, reusing ExportSheetModal
• Google Sheets import: reusing ui/utils/gsheets.ts utilities
• Translation services: reusing existing /cms/api/translations.import and .export endpoints (data format is compatible)

Phase 7: V1 Migration (Post-MVP)

• "Import from V1" button shown when V2 collection is empty
• Calls TranslationsManager.importTranslationsFromV1() via a one-off API call or direct Firestore migration

---

Key Files to Modify

File	Change
core/plugin.ts	Add translationsManager to experiments type
ui/ui.tsx	Add translationsManager to experiments type, add 2 new routes
ui/layout/Layout.tsx	Conditionally route sidebar link
ui/utils/doc.ts	Hook auto-publish of translations in cmsPublishDocs()

Key Files to Create

File	Purpose
ui/pages/TranslationsManagerPage/TranslationsManagerPage.tsx	Folder view page
ui/pages/TranslationsManagerPage/TranslationsManagerPage.css	Folder view styles
ui/pages/TranslationsManagerDocPage/TranslationsManagerDocPage.tsx	Editor page
ui/pages/TranslationsManagerDocPage/TranslationsManagerDocPage.css	Editor styles
ui/utils/translations-manager.ts	Client-side Firestore operations for V2
ui/utils/translations-tree.ts	Tree builder from flat doc list + CMS docs

Existing Code to Reuse

What	Where
CollectionTree pattern (Accordion tree)	ui/components/CollectionTree/CollectionTree.tsx
AG Grid / TranslationsTable pattern	ui/components/TranslationsTable/TranslationsTable.tsx
extractStringsForDoc()	ui/utils/extract.ts
ExportSheetModal	ui/components/ExportSheetModal/ExportSheetModal.tsx
hashStr()	shared/strings.ts
normalizeSlug()	shared/slug.ts
Mantine notifications	showNotification() / updateNotification()

Verification

1. Enable experiment: experiments: { translationsManager: true } in root.config.ts
2. Sidebar link should route to /cms/translations/manager
3. Folder view should display all CMS collection docs + Global entries in tree hierarchy
4. Docs with existing translations should be visually distinguished
5. Clicking a doc navigates to the editor page
6. Editor auto-extracts strings from the linked CMS doc
7. Saving persists to Firestore draft collection
8. Publishing copies drafts to published collection
9. Publishing a CMS doc auto-publishes its translations
10. Creating a "Global" translations file works
11. V1 UI at /cms/translations remains unchanged

Implementation Order

Phases 1-4 form the MVP: experiment flag → client utilities → folder view → editor page → routes.
Phase 5 (auto-publish) is important for workflow, fast follow.
Phases 6-7 (import/export, V1 migration) are post-MVP.