From 053bb1c0e591aae2dcbcd558a799eb736903e1e6 Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Fri, 23 Aug 2024 16:47:49 -0700
Subject: [PATCH 01/14] feat: [v2] add "startup" hook to plugins (#411)

---
 .changeset/twelve-months-explain.md |  5 +++++
 packages/root/src/cli/build.ts      |  8 ++++++++
 packages/root/src/cli/dev.ts        |  7 +++++++
 packages/root/src/cli/preview.ts    |  8 ++++++++
 packages/root/src/cli/start.ts      |  8 ++++++++
 packages/root/src/core/plugin.ts    | 10 +++++++++-
 6 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/twelve-months-explain.md

diff --git a/.changeset/twelve-months-explain.md b/.changeset/twelve-months-explain.md
new file mode 100644
index 00000000..882ed4b2
--- /dev/null
+++ b/.changeset/twelve-months-explain.md
@@ -0,0 +1,5 @@
+---
+'@blinkk/root': patch
+---
+
+feat: [v2] add "startup" hook to plugins
diff --git a/packages/root/src/cli/build.ts b/packages/root/src/cli/build.ts
index 0130ea72..fd366015 100644
--- a/packages/root/src/cli/build.ts
+++ b/packages/root/src/cli/build.ts
@@ -82,6 +82,14 @@ export async function build(rootProjectDir?: string, options?: BuildOptions) {
   }
 
   const rootPlugins = rootConfig.plugins || [];
+
+  // Run any "startup" hooks.
+  for (const plugin of rootPlugins) {
+    if (typeof plugin.hooks?.startup === 'function') {
+      await plugin.hooks.startup({command: 'build', rootConfig});
+    }
+  }
+
   const viteConfig = rootConfig.vite || {};
   const vitePlugins = [
     ...(viteConfig.plugins || []),
diff --git a/packages/root/src/cli/dev.ts b/packages/root/src/cli/dev.ts
index d128f62a..ec613934 100644
--- a/packages/root/src/cli/dev.ts
+++ b/packages/root/src/cli/dev.ts
@@ -135,6 +135,13 @@ export async function createDevServer(options?: {
     {type: 'dev', rootConfig}
   );
 
+  // Run any "startup" hooks.
+  for (const plugin of plugins) {
+    if (typeof plugin.hooks?.startup === 'function') {
+      await plugin.hooks.startup({command: 'dev', rootConfig});
+    }
+  }
+
   return server;
 }
 
diff --git a/packages/root/src/cli/preview.ts b/packages/root/src/cli/preview.ts
index ac993814..aadf3b15 100644
--- a/packages/root/src/cli/preview.ts
+++ b/packages/root/src/cli/preview.ts
@@ -120,6 +120,14 @@ export async function createPreviewServer(options: {
     plugins,
     {type: 'preview', rootConfig}
   );
+
+  // Run any "startup" hooks.
+  for (const plugin of plugins) {
+    if (typeof plugin.hooks?.startup === 'function') {
+      await plugin.hooks.startup({command: 'preview', rootConfig});
+    }
+  }
+
   return server;
 }
 
diff --git a/packages/root/src/cli/start.ts b/packages/root/src/cli/start.ts
index 9245ad6d..11a7d597 100644
--- a/packages/root/src/cli/start.ts
+++ b/packages/root/src/cli/start.ts
@@ -115,6 +115,14 @@ export async function createProdServer(options: {
     plugins,
     {type: 'prod', rootConfig}
   );
+
+  // Run any "startup" hooks.
+  for (const plugin of plugins) {
+    if (typeof plugin.hooks?.startup === 'function') {
+      await plugin.hooks.startup({command: 'start', rootConfig});
+    }
+  }
+
   return server;
 }
 
diff --git a/packages/root/src/core/plugin.ts b/packages/root/src/core/plugin.ts
index cbb18f28..81770811 100644
--- a/packages/root/src/core/plugin.ts
+++ b/packages/root/src/core/plugin.ts
@@ -15,12 +15,20 @@ export interface ConfigureServerOptions {
 }
 
 export interface PluginHooks {
+  /**
+   * Startup hook called when root is initialized.
+   */
+  startup?: (options: {
+    command: string;
+    rootConfig: RootConfig;
+  }) => void | Promise<void>;
+
   /**
    * Post-render hook that's called before the HTML is rendered to the response
    * object. If a string is returned from this hook, it will replace the
    * rendered HTML.
    */
-  preRender: (html: string) => void | string | Promise<string>;
+  preRender?: (html: string) => void | string | Promise<string>;
 }
 
 export interface Plugin {

From f5bd04162d8da4afbd4485784c0c81f6abeebcf0 Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Sat, 24 Aug 2024 14:45:26 -0700
Subject: [PATCH 02/14] feat: [v2] add compatibility check for v2 translations
 (#412)

---
 .changeset/kind-pans-check.md           |   5 ++
 .changeset/strong-planes-float.md       |   6 ++
 packages/root-cms/core/client.ts        |  15 +---
 packages/root-cms/core/compatibility.ts | 102 ++++++++++++++++++++++++
 packages/root-cms/core/plugin.ts        |  25 +++++-
 packages/root/src/core/config.ts        |  10 ++-
 6 files changed, 147 insertions(+), 16 deletions(-)
 create mode 100644 .changeset/kind-pans-check.md
 create mode 100644 .changeset/strong-planes-float.md
 create mode 100644 packages/root-cms/core/compatibility.ts

diff --git a/.changeset/kind-pans-check.md b/.changeset/kind-pans-check.md
new file mode 100644
index 00000000..7186e830
--- /dev/null
+++ b/.changeset/kind-pans-check.md
@@ -0,0 +1,5 @@
+---
+'@blinkk/root-cms': patch
+---
+
+feat: [v2] store compatibility versions in db
diff --git a/.changeset/strong-planes-float.md b/.changeset/strong-planes-float.md
new file mode 100644
index 00000000..20b7ff3b
--- /dev/null
+++ b/.changeset/strong-planes-float.md
@@ -0,0 +1,6 @@
+---
+'@blinkk/root-cms': patch
+'@blinkk/root': patch
+---
+
+feat: [v2] add compatibility check for v2 translations
diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index 5b16ef65..d33a37c1 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import {Plugin, RootConfig} from '@blinkk/root';
+import {RootConfig} from '@blinkk/root';
 import {App} from 'firebase-admin/app';
 import {
   FieldValue,
@@ -8,7 +8,7 @@ import {
   Timestamp,
   WriteBatch,
 } from 'firebase-admin/firestore';
-import {CMSPlugin} from './plugin.js';
+import {CMSPlugin, getCmsPlugin} from './plugin.js';
 
 export interface Doc<Fields = any> {
   /** The id of the doc, e.g. "Pages/foo-bar". */
@@ -968,15 +968,6 @@ export function isRichTextData(data: any) {
   );
 }
 
-export function getCmsPlugin(rootConfig: RootConfig): CMSPlugin {
-  const plugins: Plugin[] = rootConfig.plugins || [];
-  const plugin = plugins.find((plugin) => plugin.name === 'root-cms');
-  if (!plugin) {
-    throw new Error('could not find root-cms plugin config in root.config.ts');
-  }
-  return plugin as CMSPlugin;
-}
-
 /**
  * Walks the data tree and converts any array of objects into "array objects"
  * for storage in firestore.
@@ -1178,3 +1169,5 @@ export function parseDocId(docId: string) {
   }
   return {collection, slug};
 }
+
+export {getCmsPlugin};
diff --git a/packages/root-cms/core/compatibility.ts b/packages/root-cms/core/compatibility.ts
new file mode 100644
index 00000000..71056394
--- /dev/null
+++ b/packages/root-cms/core/compatibility.ts
@@ -0,0 +1,102 @@
+import {RootConfig} from '@blinkk/root';
+import {FieldValue} from 'firebase-admin/firestore';
+import type {CMSPlugin} from './plugin.js';
+
+/**
+ * Runs compatibility checks to ensure the current version of root supports
+ * any backwards-incompatible db changes.
+ *
+ * Compatibility versions are stored in the db in Projects/<projectId> under
+ * the "compatibility" key. If the compatibility version is less than the
+ * latest version, a backwards-friendly "migration" is done to ensure
+ * compatibility on both the old and new versions.
+ */
+export async function runCompatibilityChecks(
+  rootConfig: RootConfig,
+  cmsPlugin: CMSPlugin
+) {
+  const projectId = cmsPlugin.getConfig().id || 'default';
+  const db = cmsPlugin.getFirestore();
+  const projectConfigDocRef = db.doc(`Projects/${projectId}`);
+  const projectConfigDoc = await projectConfigDocRef.get();
+  const projectConfig = projectConfigDoc.data() || {};
+
+  const compatibilityVersions = projectConfig.compatibility || {};
+  let versionsChanged = false;
+
+  const translationsVersion = compatibilityVersions.translations || 0;
+  if (translationsVersion < 2) {
+    await migrateTranslationsToV2(rootConfig, cmsPlugin);
+    compatibilityVersions.translations = 2;
+    versionsChanged = true;
+  }
+
+  if (versionsChanged) {
+    await projectConfigDocRef.update({compatibility: compatibilityVersions});
+    console.log('[root cms] updated db compatibility');
+  }
+}
+
+/**
+ * Migrates translations from the "v1" format to "v2".
+ */
+async function migrateTranslationsToV2(
+  rootConfig: RootConfig,
+  cmsPlugin: CMSPlugin
+) {
+  if (rootConfig.experiments?.rootCmsDisableTranslationsToV2Check) {
+    return;
+  }
+
+  const projectId = cmsPlugin.getConfig().id || 'default';
+  const db = cmsPlugin.getFirestore();
+  const dbPath = `Projects/${projectId}/Translations`;
+  const query = db.collection(dbPath);
+  const querySnapshot = await query.get();
+  if (querySnapshot.size === 0) {
+    return;
+  }
+
+  console.log('[root cms] updating translations v2 compatibility');
+  const translationsMemories: Record<string, Record<string, any>> = {};
+  querySnapshot.forEach((doc) => {
+    const hash = doc.id;
+    const translation = doc.data();
+    const tags = translation.tags || [];
+    delete translation.tags;
+    for (const tag of tags) {
+      if (tag.includes('/')) {
+        const translationsMemoryId = tag.replaceAll('/', '--');
+        translationsMemories[translationsMemoryId] ??= {};
+        translationsMemories[translationsMemoryId][hash] = translation;
+      }
+    }
+  });
+
+  const batch = db.batch();
+  Object.entries(translationsMemories).forEach(
+    ([translationsMemoryId, strings]) => {
+      const updates = {
+        sys: {
+          modifiedAt: FieldValue.serverTimestamp(),
+          modifiedBy: 'root-cms-client',
+        },
+        strings: strings,
+      };
+      const draftRef = db.doc(
+        `Projects/${projectId}/TranslationsMemory/draft/Translations/${translationsMemoryId}`
+      );
+      const publishedRef = db.doc(
+        `Projects/${projectId}/TranslationsMemory/published/Translations/${translationsMemoryId}`
+      );
+      batch.set(draftRef, updates, {merge: true});
+      batch.set(publishedRef, updates, {merge: true});
+      const len = Object.keys(strings).length;
+      console.log(
+        `[root cms] saving ${len} string(s) to ${translationsMemoryId}...`
+      );
+    }
+  );
+  await batch.commit();
+  console.log('[root cms] done migrating translations to v2');
+}
diff --git a/packages/root-cms/core/plugin.ts b/packages/root-cms/core/plugin.ts
index 4fe55128..dcba7f38 100644
--- a/packages/root-cms/core/plugin.ts
+++ b/packages/root-cms/core/plugin.ts
@@ -8,6 +8,7 @@ import {
   Plugin,
   Request,
   Response,
+  RootConfig,
   Server,
 } from '@blinkk/root';
 import bodyParser from 'body-parser';
@@ -21,9 +22,9 @@ import {getAuth, DecodedIdToken} from 'firebase-admin/auth';
 import {Firestore, getFirestore} from 'firebase-admin/firestore';
 import * as jsonwebtoken from 'jsonwebtoken';
 import sirv from 'sirv';
-import {generateTypes} from '../cli/generate-types.js';
 import {api} from './api.js';
 import {Action, RootCMSClient} from './client.js';
+import {runCompatibilityChecks} from './compatibility.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -439,6 +440,19 @@ export function cmsPlugin(options: CMSPluginOptions): CMSPlugin {
       cms: path.resolve(__dirname, './app.js'),
     }),
 
+    hooks: {
+      /**
+       * Startup hook. On `dev` and `build` commands, the plugin does
+       * compatibility checks.
+       */
+      startup: async ({command, rootConfig}) => {
+        if (command === 'dev' || command === 'build') {
+          const cmsPlugin = getCmsPlugin(rootConfig);
+          await runCompatibilityChecks(rootConfig, cmsPlugin);
+        }
+      },
+    },
+
     /**
      * Attaches CMS-specific middleware to the Root.js server.
      */
@@ -607,3 +621,12 @@ function fileExists(filepath: string): Promise<boolean> {
     .then(() => true)
     .catch(() => false);
 }
+
+export function getCmsPlugin(rootConfig: RootConfig): CMSPlugin {
+  const plugins: Plugin[] = rootConfig.plugins || [];
+  const plugin = plugins.find((plugin) => plugin.name === 'root-cms');
+  if (!plugin) {
+    throw new Error('could not find root-cms plugin config in root.config.ts');
+  }
+  return plugin as CMSPlugin;
+}
diff --git a/packages/root/src/core/config.ts b/packages/root/src/core/config.ts
index a6ba937e..c8c8fa7d 100644
--- a/packages/root/src/core/config.ts
+++ b/packages/root/src/core/config.ts
@@ -4,6 +4,11 @@ import {HtmlPrettyOptions} from '../render/html-pretty.js';
 import {Plugin} from './plugin.js';
 import {RequestMiddleware} from './types.js';
 
+export interface RootExperimentsConfig {
+  [name: string]: boolean | undefined;
+  enableScriptAsync?: boolean;
+}
+
 export interface RootUserConfig {
   /**
    * Canonical domain the website will serve on. Useful for things like the
@@ -83,10 +88,7 @@ export interface RootUserConfig {
   /**
    * Experimental config options. Note: these are subject to change at any time.
    */
-  experiments?: {
-    /** Whether to render `<script>` tags with `async`. */
-    enableScriptAsync?: boolean;
-  };
+  experiments?: RootExperimentsConfig;
 }
 
 export type RootConfig = RootUserConfig & {

From e4ae3bfb2c6b2fa06374b078ce16bff3fea90e00 Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Mon, 23 Sep 2024 12:17:25 -0700
Subject: [PATCH 03/14] feat: [v2] add batch requests to cms client (#415)

---
 docs/utils/cms-route.ts                    |  37 +-
 packages/root-cms/core/client.ts           | 388 ++++++++++++++++++++-
 packages/root-cms/core/compatibility.ts    |  51 ++-
 packages/root/src/core/config.ts           |  13 +
 packages/root/src/render/i18n-fallbacks.ts |   6 +-
 5 files changed, 439 insertions(+), 56 deletions(-)

diff --git a/docs/utils/cms-route.ts b/docs/utils/cms-route.ts
index b5dfd3c1..9419719f 100644
--- a/docs/utils/cms-route.ts
+++ b/docs/utils/cms-route.ts
@@ -85,7 +85,7 @@ export function cmsRoute(options: CMSRouteOptions) {
       return options.slug;
     }
     const slugParam = options.slugParam || 'slug';
-    return params[slugParam] || 'index';
+    return (params[slugParam] || 'index').replaceAll('/', '--');
   }
 
   async function fetchData(
@@ -180,22 +180,22 @@ export function cmsRoute(options: CMSRouteOptions) {
         res.setHeader('cache-control', 'private');
         return ctx.render404();
       }
+      const primaryDocId = `${options.collection}/${slug}`;
       const mode = String(req.query.preview) === 'true' ? 'draft' : 'published';
       const routeContext: CMSRouteContext = {req, slug, mode, cmsClient};
 
-      const translationsTags = ['common', `${options.collection}/${slug}`];
-      if (options.translations) {
-        const tags = options.translations(routeContext)?.tags || [];
-        translationsTags.push(...tags);
-      }
+      const batchRequest = cmsClient.createBatchRequest({
+        mode,
+        translate: true,
+      });
+      batchRequest.addDoc(primaryDocId);
 
-      const [doc, translationsMap, data] = await Promise.all([
-        cmsClient.getDoc<CMSDoc>(options.collection, slug, {
-          mode,
-        }),
-        cmsClient.loadTranslations({tags: translationsTags}),
+      const [batchRes, data] = await Promise.all([
+        batchRequest.fetch(),
         fetchData(routeContext),
       ]);
+      const doc = batchRes.docs[primaryDocId];
+
       if (!doc) {
         res.setHeader('cache-control', 'private');
         return ctx.render404();
@@ -215,8 +215,19 @@ export function cmsRoute(options: CMSRouteOptions) {
         req.get('x-country-code') ||
         req.get('x-appengine-country') ||
         null;
-      const translations = translationsForLocale(translationsMap, locale);
-      let props: any = {...data, req, locale, mode, slug, doc, country};
+
+      const i18nFallbacks = req.rootConfig.i18n?.fallbacks || {};
+      const translationFallbackLocales = i18nFallbacks[locale] || [locale];
+      const translations = batchRes.getTranslations(translationFallbackLocales);
+      let props: any = {
+        ...data,
+        req,
+        locale,
+        mode,
+        slug,
+        doc,
+        country,
+      };
       if (options.preRenderHook) {
         props = await options.preRenderHook(props, routeContext);
       }
diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index d33a37c1..d92ec9ec 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -37,6 +37,15 @@ export interface Doc<Fields = any> {
   fields: Fields;
 }
 
+export interface TranslationsDoc {
+  id: string;
+  sys: {
+    modifiedAt: Timestamp;
+    modifiedBy: string;
+  };
+  strings: TranslationsMap;
+}
+
 export type DocMode = 'draft' | 'published';
 
 export type UserRole = 'ADMIN' | 'EDITOR' | 'VIEWER';
@@ -222,11 +231,7 @@ export class RootCMSClient {
     options: GetDocOptions
   ): Promise<any | null> {
     const mode = options.mode;
-    const modeCollection = mode === 'draft' ? 'Drafts' : 'Published';
-    // Slugs with slashes are encoded as `--` in the DB.
-    slug = slug.replaceAll('/', '--');
-    const dbPath = `Projects/${this.projectId}/Collections/${collectionId}/${modeCollection}/${slug}`;
-    const docRef = this.db.doc(dbPath);
+    const docRef = this.dbDocRef(collectionId, slug, {mode});
     const doc = await docRef.get();
     if (doc.exists) {
       return doc.data();
@@ -234,6 +239,41 @@ export class RootCMSClient {
     return null;
   }
 
+  dbCollectionDocsPath(
+    collectionId: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    let modeCollection = '';
+    if (options.mode === 'draft') {
+      modeCollection = 'Drafts';
+    } else if (options.mode === 'published') {
+      modeCollection = 'Published';
+    } else {
+      throw new Error(`unknown mode: ${options.mode}`);
+    }
+    return `Projects/${this.projectId}/Collections/${collectionId}/${modeCollection}`;
+  }
+
+  dbDocPath(
+    collectionId: string,
+    slug: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    const collectionDocsPath = this.dbCollectionDocsPath(collectionId, options);
+    // Slugs with slashes are encoded as `--` in the DB.
+    const normalizedSlug = slug.replaceAll('/', '--');
+    return `${collectionDocsPath}/${normalizedSlug}`;
+  }
+
+  dbDocRef(
+    collectionId: string,
+    slug: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    const docPath = this.dbDocPath(collectionId, slug, options);
+    return this.db.doc(docPath);
+  }
+
   /**
    * Saves draft data to a doc.
    *
@@ -853,15 +893,8 @@ export class RootCMSClient {
     options?: {mode?: 'draft' | 'published'}
   ): Promise<DataSourceData<T> | null> {
     const mode = options?.mode || 'published';
-    if (!(mode === 'draft' || mode === 'published')) {
-      throw new Error(`invalid mode: ${mode}`);
-    }
-    if (!dataSourceId || dataSourceId.includes('/')) {
-      throw new Error(`invalid data source id: ${dataSourceId}`);
-    }
 
-    const dbPath = `Projects/${this.projectId}/DataSources/${dataSourceId}/Data/${mode}`;
-    const docRef = this.db.doc(dbPath);
+    const docRef = this.dbDataSourceDataRef(dataSourceId, {mode});
     const doc = await docRef.get();
     if (doc.exists) {
       return doc.data() as DataSourceData<T>;
@@ -869,6 +902,50 @@ export class RootCMSClient {
     return null;
   }
 
+  dbDataSourceDataPath(
+    dataSourceId: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    if (!dataSourceId || dataSourceId.includes('/')) {
+      throw new Error(`invalid data source id: ${dataSourceId}`);
+    }
+    const mode = options.mode;
+    if (!(mode === 'draft' || mode === 'published')) {
+      throw new Error(`invalid mode: ${mode}`);
+    }
+    const dbPath = `Projects/${this.projectId}/DataSources/${dataSourceId}/Data/${mode}`;
+    return dbPath;
+  }
+
+  dbDataSourceDataRef(
+    dataSourceId: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    const dbPath = this.dbDataSourceDataPath(dataSourceId, options);
+    return this.db.doc(dbPath);
+  }
+
+  dbTranslationsPath(
+    translationsId: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    const mode = options.mode;
+    if (!(mode === 'draft' || mode === 'published')) {
+      throw new Error(`invalid mode: ${mode}`);
+    }
+    const slug = translationsId.replaceAll('/', '--');
+    const dbPath = `Projects/${this.projectId}/TranslationsManager/${mode}/Translations/${slug}`;
+    return dbPath;
+  }
+
+  dbTranslationsRef(
+    translationsId: string,
+    options: {mode: 'draft' | 'published'}
+  ) {
+    const dbPath = this.dbTranslationsPath(translationsId, options);
+    return this.db.doc(dbPath);
+  }
+
   /**
    * Gets the user's role from the project's ACL.
    */
@@ -950,6 +1027,276 @@ export class RootCMSClient {
       }
     }
   }
+
+  createBatchRequest(options: BatchRequestOptions): BatchRequest {
+    return new BatchRequest(this, options);
+  }
+}
+
+export interface BatchRequestOptions {
+  mode: 'draft' | 'published';
+  /**
+   * Whether to automatically fetch translations for the docs retrieved in the
+   * request.
+   */
+  translate?: boolean;
+}
+
+export interface BatchRequestQuery {
+  queryId: string;
+  collectionId: string;
+  queryOptions?: BatchRequestQueryOptions;
+}
+
+export interface BatchRequestQueryOptions {
+  offset?: number;
+  limit?: number;
+  orderBy?: string;
+  orderByDirection?: 'asc' | 'desc';
+  query?: (query: Query) => Query;
+}
+
+export class BatchRequest {
+  cmsClient: RootCMSClient;
+  private options: BatchRequestOptions;
+  private db: Firestore;
+  private docIds: string[] = [];
+  private dataSourceIds: string[] = [];
+  private queries: BatchRequestQuery[] = [];
+  private translationsIds: string[] = [];
+
+  constructor(cmsClient: RootCMSClient, options: BatchRequestOptions) {
+    this.cmsClient = cmsClient;
+    this.db = cmsClient.db;
+    this.options = options;
+  }
+
+  /**
+   * Adds a doc to the batch request.
+   */
+  addDoc(docId: string) {
+    this.docIds.push(docId);
+  }
+
+  /**
+   * Adds a data source to the batch request.
+   */
+  addDataSource(dataSourceId: string) {
+    this.dataSourceIds.push(dataSourceId);
+  }
+
+  /**
+   * Adds a collection-based query to the batch request.
+   */
+  addQuery(
+    queryId: string,
+    collectionId: string,
+    queryOptions?: BatchRequestQueryOptions
+  ) {
+    this.queries.push({
+      queryId: queryId,
+      collectionId: collectionId,
+      queryOptions: queryOptions,
+    });
+  }
+
+  /**
+   * Adds a translation file to the request.
+   */
+  addTranslations(translationsId: string) {
+    this.translationsIds.push(translationsId);
+  }
+
+  /**
+   * Fetches data from the DB.
+   */
+  async fetch(): Promise<BatchResponse> {
+    const res = new BatchResponse();
+
+    const promises = [
+      this.fetchDocs(res),
+      this.fetchQueries(res),
+      this.fetchDataSources(res),
+    ];
+    // If `options.translate` is disabled and translations are requested,
+    // fetch the translations in parallel with the other docs.
+    if (!this.options.translate && this.translationsIds.length > 0) {
+      promises.push(this.fetchTranslations(res));
+    }
+
+    await Promise.all(promises);
+
+    // If `options.translate` is enabled, the fetchX() methods will
+    // automatically add each doc's translations id to the request, so
+    // translations should be fetched after all the other docs are fetched.
+    if (this.translationsIds.length > 0) {
+      await this.fetchTranslations(res);
+    }
+
+    return res;
+  }
+
+  private async fetchDocs(res: BatchResponse) {
+    if (this.docIds.length === 0) {
+      return;
+    }
+    const docRefs = this.docIds.map((docId) => {
+      const [collectionId, slug] = docId.split('/');
+      return this.cmsClient.dbDocRef(collectionId, slug, {
+        mode: this.options.mode,
+      });
+    });
+    const docs = await this.db.getAll(...docRefs);
+    this.docIds.forEach((docId, i) => {
+      const doc = docs[i];
+      if (!doc.exists) {
+        console.warn(`doc "${docId}" does not exist`);
+        return;
+      }
+      const docData = unmarshalData(doc.data()) as Doc;
+      res.docs[docId] = docData;
+
+      if (this.options.translate) {
+        this.addTranslations(docId);
+      }
+    });
+  }
+
+  private async fetchQueries(res: BatchResponse) {
+    if (this.queries.length === 0) {
+      return;
+    }
+    const mode = this.options.mode;
+
+    const handleQuery = async (queryItem: BatchRequestQuery) => {
+      const docsPath = this.cmsClient.dbCollectionDocsPath(
+        queryItem.collectionId,
+        {mode}
+      );
+      const queryOptions = queryItem.queryOptions || {};
+      let query: Query = this.db.collection(docsPath);
+      if (queryOptions.limit) {
+        query = query.limit(queryOptions.limit);
+      }
+      if (queryOptions.offset) {
+        query = query.offset(queryOptions.offset);
+      }
+      if (queryOptions.orderBy) {
+        query = query.orderBy(
+          queryOptions.orderBy,
+          queryOptions.orderByDirection
+        );
+      }
+      if (queryOptions.query) {
+        query = queryOptions.query(query);
+      }
+      const results = await query.get();
+      const docs: Doc[] = [];
+      results.forEach((result) => {
+        const doc = unmarshalData(result.data()) as Doc;
+        docs.push(doc);
+      });
+      res.queries[queryItem.queryId] = docs;
+    };
+
+    await Promise.all(this.queries.map((queryItem) => handleQuery(queryItem)));
+  }
+
+  private async fetchDataSources(res: BatchResponse) {
+    if (this.dataSourceIds.length === 0) {
+      return;
+    }
+    const docRefs = this.dataSourceIds.map((dataSourceId) => {
+      return this.cmsClient.dbDataSourceDataRef(dataSourceId, {
+        mode: this.options.mode,
+      });
+    });
+    const docs = await this.db.getAll(...docRefs);
+    this.dataSourceIds.forEach((dataSourceId, i) => {
+      const doc = docs[i];
+      if (!doc.exists) {
+        console.warn(`"data source "${dataSourceId}" does not exist`);
+        return;
+      }
+      res.dataSources[dataSourceId] = doc.data() as DataSourceData;
+    });
+  }
+
+  private async fetchTranslations(res: BatchResponse) {
+    if (this.translationsIds.length === 0) {
+      return;
+    }
+
+    const docRefs = this.translationsIds.map((translationsId) => {
+      return this.cmsClient.dbTranslationsRef(translationsId, {
+        mode: this.options.mode,
+      });
+    });
+    const docs = await this.db.getAll(...docRefs);
+    this.translationsIds.forEach((translationsId, i) => {
+      const doc = docs[i];
+      if (!doc.exists) {
+        // console.warn(`translations "${translationsId}" does not exist`);
+        return;
+      }
+      res.translations[translationsId] = doc.data() as TranslationsDoc;
+    });
+  }
+}
+
+export class BatchResponse {
+  docs: Record<string, Doc> = {};
+  queries: Record<string, Doc[]> = {};
+  dataSources: Record<string, DataSourceData> = {};
+  translations: Record<string, TranslationsDoc> = {};
+
+  /**
+   * Returns a map of translations for a given locale or locale fallbacks.
+   *
+   * The input is either a single locale (e.g. "de") or an array of locales
+   * representing the fallback tree, e.g. ["en-CA", "en-GB", "en"].
+   *
+   * The returned value is a flat map of source string to translated string,
+   * e.g.:
+   * {"<source>": "<translation>"}
+   */
+  getTranslations(locale: string | string[]): LocaleTranslations {
+    const translationsMap = this.getTranslationsMap();
+    const translations = translationsForLocale(translationsMap, locale);
+    return translations;
+  }
+
+  /**
+   * Merges the strings from all translations files retrieved in the request.
+   * The returned value is a map of string to translations, e.g.:
+   *
+   * {"<hash>": {"source": "<source>", "<locale>": "<translation>"}}
+   */
+  private getTranslationsMap(): TranslationsMap {
+    // Load translations in the following order:
+    // - generic translations (e.g. "global")
+    // - docs returned from queries (e.g. "list all blog posts")
+    // - specific docs (e.g. "Pages/index")
+    const translationsDocs = Object.values(this.translations).reverse();
+
+    // Consolidate the strings from all of the translations files.
+    // {"<hash>": {"source": "<source>", "<locale>": "<translation>"}}
+    const translationsMap: TranslationsMap = {};
+    for (const translationsDoc of translationsDocs) {
+      const strings = translationsDoc.strings || {};
+      for (const hash in strings) {
+        const translations = strings[hash];
+        translationsMap[hash] ??= {source: translations.source};
+        for (const locale in translations) {
+          if (locale !== 'source' && translations[locale]) {
+            translationsMap[hash][locale] = translations[locale];
+          }
+        }
+      }
+    }
+
+    return translationsMap;
+  }
 }
 
 /**
@@ -1117,12 +1464,23 @@ function randString(len: number): string {
  */
 export function translationsForLocale(
   translationsMap: TranslationsMap,
-  locale: string
+  locale: string | string[]
 ) {
   const localeTranslations: LocaleTranslations = {};
+
+  const fallbackLocales = Array.isArray(locale) ? locale : [locale];
+  if (!fallbackLocales.includes('en')) {
+    fallbackLocales.push('en');
+  }
+
   Object.values(translationsMap).forEach((string) => {
     const source = string.source;
-    const translation = string[locale] || string.en || string.source;
+    let translation = source;
+    for (const fallbackLocale of fallbackLocales) {
+      if (string[fallbackLocale]) {
+        translation = string[fallbackLocale];
+      }
+    }
     localeTranslations[source] = translation;
   });
   return localeTranslations;
diff --git a/packages/root-cms/core/compatibility.ts b/packages/root-cms/core/compatibility.ts
index 71056394..743e5735 100644
--- a/packages/root-cms/core/compatibility.ts
+++ b/packages/root-cms/core/compatibility.ts
@@ -58,7 +58,7 @@ async function migrateTranslationsToV2(
   }
 
   console.log('[root cms] updating translations v2 compatibility');
-  const translationsMemories: Record<string, Record<string, any>> = {};
+  const translationsFiles: Record<string, Record<string, any>> = {};
   querySnapshot.forEach((doc) => {
     const hash = doc.id;
     const translation = doc.data();
@@ -66,37 +66,34 @@ async function migrateTranslationsToV2(
     delete translation.tags;
     for (const tag of tags) {
       if (tag.includes('/')) {
-        const translationsMemoryId = tag.replaceAll('/', '--');
-        translationsMemories[translationsMemoryId] ??= {};
-        translationsMemories[translationsMemoryId][hash] = translation;
+        const translationsId = tag.replaceAll('/', '--');
+        translationsFiles[translationsId] ??= {};
+        translationsFiles[translationsId][hash] = translation;
       }
     }
   });
 
   const batch = db.batch();
-  Object.entries(translationsMemories).forEach(
-    ([translationsMemoryId, strings]) => {
-      const updates = {
-        sys: {
-          modifiedAt: FieldValue.serverTimestamp(),
-          modifiedBy: 'root-cms-client',
-        },
-        strings: strings,
-      };
-      const draftRef = db.doc(
-        `Projects/${projectId}/TranslationsMemory/draft/Translations/${translationsMemoryId}`
-      );
-      const publishedRef = db.doc(
-        `Projects/${projectId}/TranslationsMemory/published/Translations/${translationsMemoryId}`
-      );
-      batch.set(draftRef, updates, {merge: true});
-      batch.set(publishedRef, updates, {merge: true});
-      const len = Object.keys(strings).length;
-      console.log(
-        `[root cms] saving ${len} string(s) to ${translationsMemoryId}...`
-      );
-    }
-  );
+  Object.entries(translationsFiles).forEach(([translationsId, strings]) => {
+    const updates = {
+      id: translationsId.replaceAll('--', '/'),
+      sys: {
+        modifiedAt: FieldValue.serverTimestamp(),
+        modifiedBy: 'root-cms-client',
+      },
+      strings: strings,
+    };
+    const draftRef = db.doc(
+      `Projects/${projectId}/TranslationsManager/draft/Translations/${translationsId}`
+    );
+    const publishedRef = db.doc(
+      `Projects/${projectId}/TranslationsManager/published/Translations/${translationsId}`
+    );
+    batch.set(draftRef, updates, {merge: true});
+    batch.set(publishedRef, updates, {merge: true});
+    const len = Object.keys(strings).length;
+    console.log(`[root cms] saving ${len} string(s) to ${translationsId}...`);
+  });
   await batch.commit();
   console.log('[root cms] done migrating translations to v2');
 }
diff --git a/packages/root/src/core/config.ts b/packages/root/src/core/config.ts
index c8c8fa7d..ad1499bc 100644
--- a/packages/root/src/core/config.ts
+++ b/packages/root/src/core/config.ts
@@ -121,6 +121,19 @@ export interface RootI18nConfig {
    * locales.
    */
   groups?: Record<string, LocaleGroup>;
+
+  /**
+   * Fallback locales. When a translation doesn't exist for the requested
+   * locale, it will fall back to the locales as configured, e.g.:
+   *
+   * ```
+   * {
+   *   "en-CA": ["en-GB", "en"],
+   *   "es-MX": ["es-419", "es"]
+   * }
+   * ```
+   */
+  fallbacks?: Record<string, string[]>;
 }
 
 export interface RootRedirectConfig {
diff --git a/packages/root/src/render/i18n-fallbacks.ts b/packages/root/src/render/i18n-fallbacks.ts
index 038aa546..856ce669 100644
--- a/packages/root/src/render/i18n-fallbacks.ts
+++ b/packages/root/src/render/i18n-fallbacks.ts
@@ -63,9 +63,13 @@ export function getFallbackLocales(req: Request): string[] {
   // Add ALL_{country} locale.
   locales.add(`ALL_${countryCode}`);
 
-  // Add `{lang}_ALL` and `{lang}` locales.
+  // Add `{locale}-{country}`, `{lang}_ALL`, and `{lang}` locales.
   const isEs419Country = test419Country(countryCode);
   langs.forEach((langCode) => {
+    if (!langCode.includes('-')) {
+      locales.add(`${langCode}-${countryCode}_ALL`);
+      locales.add(`${langCode}-${countryCode}`);
+    }
     // For Spanish-speaking LATAM countries, also add es-419.
     if (langCode === 'es' && isEs419Country) {
       locales.add('es-419_ALL');

From 582531a7e1ac596cb025d5e8872021cd40c320f3 Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Tue, 8 Oct 2024 10:26:53 -0700
Subject: [PATCH 04/14] feat: [v2] cms ui updates for translations v2 (#422)

---
 docs/collections/PagesSandbox.schema.ts       |   8 +
 docs/layouts/BaseLayout.tsx                   |  12 +-
 docs/root-cms.d.ts                            |  21 +
 docs/routes/sandbox/[sandbox].tsx             |   9 +
 packages/root-cms/core/client.ts              |  75 ++-
 packages/root-cms/core/compatibility.ts       |  79 +--
 packages/root-cms/core/plugin.ts              |   3 +-
 .../EditTranslationsModal.tsx                 |  70 +--
 .../LocalizationModal/LocalizationModal.css   |  10 -
 .../LocalizationModal/LocalizationModal.tsx   | 234 ++-------
 .../TranslationsImportExportButtons.css       |   9 +
 .../TranslationsImportExportButtons.tsx       | 460 ++++++++++++++++++
 .../TranslationsStatusBadges.tsx              |  50 ++
 packages/root-cms/ui/db/translations.ts       | 239 +++++++++
 .../root-cms/ui/hooks/useTranslationsDoc.ts   | 164 +++++++
 .../DocTranslationsPage.css                   |  20 +-
 .../DocTranslationsPage.tsx                   | 158 +++---
 .../TranslationsPage/TranslationsPage.css     |  12 +-
 .../TranslationsPage/TranslationsPage.tsx     |  84 ++--
 packages/root-cms/ui/utils/doc.ts             |  53 +-
 packages/root-cms/ui/utils/time.ts            |  12 +
 21 files changed, 1282 insertions(+), 500 deletions(-)
 create mode 100644 docs/collections/PagesSandbox.schema.ts
 create mode 100644 docs/routes/sandbox/[sandbox].tsx
 create mode 100644 packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.css
 create mode 100644 packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx
 create mode 100644 packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx
 create mode 100644 packages/root-cms/ui/db/translations.ts
 create mode 100644 packages/root-cms/ui/hooks/useTranslationsDoc.ts

diff --git a/docs/collections/PagesSandbox.schema.ts b/docs/collections/PagesSandbox.schema.ts
new file mode 100644
index 00000000..765cf95d
--- /dev/null
+++ b/docs/collections/PagesSandbox.schema.ts
@@ -0,0 +1,8 @@
+import PagesSchema from './Pages.schema.js';
+
+export default {
+  ...PagesSchema,
+  name: 'Pages [SANDBOX]',
+  description: 'Sandbox Pages',
+  url: '/sandbox/[...slug]',
+};
diff --git a/docs/layouts/BaseLayout.tsx b/docs/layouts/BaseLayout.tsx
index c42e02c1..59f325cd 100644
--- a/docs/layouts/BaseLayout.tsx
+++ b/docs/layouts/BaseLayout.tsx
@@ -1,4 +1,11 @@
-import {Body, Head, Html, Script, useTranslations} from '@blinkk/root';
+import {
+  Body,
+  Head,
+  Html,
+  Script,
+  useRequestContext,
+  useTranslations,
+} from '@blinkk/root';
 import {ComponentChildren} from 'preact';
 import {GlobalFooter} from '@/components/GlobalFooter/GlobalFooter.js';
 import {GlobalHeader} from '@/components/GlobalHeader/GlobalHeader.js';
@@ -39,9 +46,10 @@ export function BaseLayout(props: BaseLayoutProps) {
     width: 1200,
     jpg: true,
   });
+  const ctx = useRequestContext();
 
   return (
-    <Html>
+    <Html lang={ctx.locale}>
       <Head>
         <title>{t(title)}</title>
         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
diff --git a/docs/root-cms.d.ts b/docs/root-cms.d.ts
index a50c4247..47b64cf8 100644
--- a/docs/root-cms.d.ts
+++ b/docs/root-cms.d.ts
@@ -196,6 +196,27 @@ export interface PagesFields {
 /** Generated from `/collections/Pages.schema.ts`. */
 export type PagesDoc = RootCMSDoc<PagesFields>;
 
+/** Generated from `/collections/PagesSandbox.schema.ts`. */
+export interface PagesSandboxFields {
+  /** Meta */
+  meta?: {
+    /** Title. Page title. */
+    title?: string;
+    /** Description. Description for SEO and social shares. */
+    description?: string;
+    /** Image. Meta image for social shares. Recommended: 1400x600 JPG. */
+    image?: RootCMSImage;
+  };
+  /** Content */
+  content?: {
+    /** Modules. Compose the page by adding one or more modules. */
+    modules?: RootCMSOneOf[];
+  };
+}
+
+/** Generated from `/collections/PagesSandbox.schema.ts`. */
+export type PagesSandboxDoc = RootCMSDoc<PagesSandboxFields>;
+
 /** Generated from `/components/Button/Button.schema.ts`. */
 export interface ButtonFields {
   /** Button Options */
diff --git a/docs/routes/sandbox/[sandbox].tsx b/docs/routes/sandbox/[sandbox].tsx
new file mode 100644
index 00000000..01c67972
--- /dev/null
+++ b/docs/routes/sandbox/[sandbox].tsx
@@ -0,0 +1,9 @@
+import {cmsRoute} from '@/utils/cms-route.js';
+import Page from '../[[...page]].js';
+
+export default Page;
+
+export const {handle} = cmsRoute({
+  collection: 'PagesSandbox',
+  slugParam: 'sandbox',
+});
diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index d92ec9ec..8c0126aa 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -42,6 +42,14 @@ export interface TranslationsDoc {
   sys: {
     modifiedAt: Timestamp;
     modifiedBy: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+    linkedSheet?: {
+      spreadsheetId: string;
+      gid: number;
+      linkedAt: Timestamp;
+      linkedBy: string;
+    };
   };
   strings: TranslationsMap;
 }
@@ -643,31 +651,39 @@ export class RootCMSClient {
   }
 
   /**
-   * Loads translations saved in the translations collection, optionally
-   * filtered by tag.
+   * Loads all published strings in the db.
    *
-   * Returns a map like:
    * ```
    * {
    *   "<hash>": {"source": "Hello", "es": "Hola", "fr": "Bonjour"},
    * }
    * ```
+   *
+   * @deprecated Use `createBatchRequest()` to fetch draft/published translations.
    */
   async loadTranslations(
     options?: LoadTranslationsOptions
   ): Promise<TranslationsMap> {
-    const dbPath = `Projects/${this.projectId}/Translations`;
-    let query: Query = this.db.collection(dbPath);
-    if (options?.tags) {
-      query = query.where('tags', 'array-contains-any', options.tags);
-    }
-
-    const querySnapshot = await query.get();
+    const dbPath = `Projects/${this.projectId}/TranslationsManager/published/Translations`;
+    const query: Query = this.db.collection(dbPath);
+    const snapshot = await query.get();
     const translationsMap: TranslationsMap = {};
-    querySnapshot.forEach((doc) => {
-      const hash = doc.id;
-      translationsMap[hash] = doc.data() as Translation;
+
+    const addTranslations = (hash: string, translations: Translation) => {
+      translationsMap[hash] = Object.assign(
+        translationsMap[hash] || {},
+        translations
+      );
+    };
+
+    snapshot.forEach((doc) => {
+      const data = doc.data();
+      const strings = (data.strings || {}) as Record<string, Translation>;
+      Object.entries(strings).forEach(([hash, translations]) => {
+        addTranslations(hash, translations);
+      });
     });
+
     return translationsMap;
   }
 
@@ -678,6 +694,9 @@ export class RootCMSClient {
    *   "Hello": {"es": "Hola", "fr": "Bonjour"},
    * });
    * ```
+   *
+   * @deprecated Use `saveDraftTranslations()` and `publishTranslations()`
+   * instead.
    */
   async saveTranslations(
     translations: {
@@ -707,6 +726,35 @@ export class RootCMSClient {
     await batch.commit();
   }
 
+  async saveDraftTranslations(
+    translationsId: string,
+    translations: {[source: string]: {[locale: string]: string}},
+    options?: {modifiedby?: string}
+  ) {
+    const docSlug = translationsId.replaceAll('/', '--');
+    const docPath = `Projects/${this.projectId}/TranslationsManager/draft/${docSlug}`;
+    const docRef = this.db.doc(docPath);
+
+    const snapshot = await docRef.get();
+    const data = snapshot.data() || {
+      id: translationsId.replaceAll('--', '/'),
+      sys: {},
+      strings: {},
+    };
+    data.sys.modifiedAt = Timestamp.now();
+    data.sys.modifiedBy = options?.modifiedby || 'root-cms-client';
+
+    const strings = data.strings || {};
+    Object.entries(translations).forEach(([source, row]) => {
+      const normalizedSource = this.normalizeString(source);
+      const hash = this.getTranslationKey(normalizedSource);
+      strings[hash] = {...strings[hash], ...row, source: normalizedSource};
+    });
+    data.strings = strings;
+    await docRef.set(data);
+    this.logAction('translations.save', {metadata: {translationsId}});
+  }
+
   /**
    * Returns the "key" used for a translation as stored in the db. Translations
    * are stored under `Projects/<project id>/Translations/<sha1 hash>`.
@@ -1479,6 +1527,7 @@ export function translationsForLocale(
     for (const fallbackLocale of fallbackLocales) {
       if (string[fallbackLocale]) {
         translation = string[fallbackLocale];
+        break;
       }
     }
     localeTranslations[source] = translation;
diff --git a/packages/root-cms/core/compatibility.ts b/packages/root-cms/core/compatibility.ts
index 743e5735..20ef9be6 100644
--- a/packages/root-cms/core/compatibility.ts
+++ b/packages/root-cms/core/compatibility.ts
@@ -1,6 +1,6 @@
 import {RootConfig} from '@blinkk/root';
-import {FieldValue} from 'firebase-admin/firestore';
-import type {CMSPlugin} from './plugin.js';
+import {Timestamp} from 'firebase-admin/firestore';
+import {RootCMSClient, Translation, TranslationsDoc} from './client.js';
 
 /**
  * Runs compatibility checks to ensure the current version of root supports
@@ -11,12 +11,10 @@ import type {CMSPlugin} from './plugin.js';
  * latest version, a backwards-friendly "migration" is done to ensure
  * compatibility on both the old and new versions.
  */
-export async function runCompatibilityChecks(
-  rootConfig: RootConfig,
-  cmsPlugin: CMSPlugin
-) {
-  const projectId = cmsPlugin.getConfig().id || 'default';
-  const db = cmsPlugin.getFirestore();
+export async function runCompatibilityChecks(rootConfig: RootConfig) {
+  const cmsClient = new RootCMSClient(rootConfig);
+  const projectId = cmsClient.projectId;
+  const db = cmsClient.db;
   const projectConfigDocRef = db.doc(`Projects/${projectId}`);
   const projectConfigDoc = await projectConfigDocRef.get();
   const projectConfig = projectConfigDoc.data() || {};
@@ -26,7 +24,7 @@ export async function runCompatibilityChecks(
 
   const translationsVersion = compatibilityVersions.translations || 0;
   if (translationsVersion < 2) {
-    await migrateTranslationsToV2(rootConfig, cmsPlugin);
+    await migrateTranslationsToV2(rootConfig, cmsClient);
     compatibilityVersions.translations = 2;
     versionsChanged = true;
   }
@@ -42,14 +40,14 @@ export async function runCompatibilityChecks(
  */
 async function migrateTranslationsToV2(
   rootConfig: RootConfig,
-  cmsPlugin: CMSPlugin
+  cmsClient: RootCMSClient
 ) {
   if (rootConfig.experiments?.rootCmsDisableTranslationsToV2Check) {
     return;
   }
 
-  const projectId = cmsPlugin.getConfig().id || 'default';
-  const db = cmsPlugin.getFirestore();
+  const projectId = cmsClient.projectId;
+  const db = cmsClient.db;
   const dbPath = `Projects/${projectId}/Translations`;
   const query = db.collection(dbPath);
   const querySnapshot = await query.get();
@@ -58,42 +56,65 @@ async function migrateTranslationsToV2(
   }
 
   console.log('[root cms] updating translations v2 compatibility');
-  const translationsFiles: Record<string, Record<string, any>> = {};
+
+  const translationsDocs: Record<string, TranslationsDoc> = {};
   querySnapshot.forEach((doc) => {
     const hash = doc.id;
-    const translation = doc.data();
+    const translation = doc.data() as Translation;
     const tags = translation.tags || [];
     delete translation.tags;
     for (const tag of tags) {
       if (tag.includes('/')) {
-        const translationsId = tag.replaceAll('/', '--');
-        translationsFiles[translationsId] ??= {};
-        translationsFiles[translationsId][hash] = translation;
+        const translationsId = tag;
+        translationsDocs[translationsId] ??= {
+          id: translationsId,
+          sys: {
+            modifiedAt: Timestamp.now(),
+            modifiedBy: 'root-cms-client',
+            publishedAt: Timestamp.now(),
+            publishedBy: 'root-cms-client',
+          },
+          strings: {},
+        };
+        translationsDocs[translationsId].strings[hash] = translation;
       }
     }
   });
 
+  if (Object.keys(translationsDocs).length === 0) {
+    console.log('[root cms] no translations to save');
+    return;
+  }
+
+  // Move the doc's "l10nSheet" to the translations doc's "linkedSheet".
+
+  for (const docId in translationsDocs) {
+    const [collection, slug] = docId.split('/');
+    if (collection && slug) {
+      const doc: any = await cmsClient.getDoc(collection, slug, {
+        mode: 'draft',
+      });
+      const linkedSheet = doc?.sys?.l10nSheet;
+      if (linkedSheet) {
+        translationsDocs[docId].sys.linkedSheet = linkedSheet;
+      }
+    }
+  }
+
   const batch = db.batch();
-  Object.entries(translationsFiles).forEach(([translationsId, strings]) => {
-    const updates = {
-      id: translationsId.replaceAll('--', '/'),
-      sys: {
-        modifiedAt: FieldValue.serverTimestamp(),
-        modifiedBy: 'root-cms-client',
-      },
-      strings: strings,
-    };
+  Object.entries(translationsDocs).forEach(([translationsId, data]) => {
     const draftRef = db.doc(
       `Projects/${projectId}/TranslationsManager/draft/Translations/${translationsId}`
     );
     const publishedRef = db.doc(
       `Projects/${projectId}/TranslationsManager/published/Translations/${translationsId}`
     );
-    batch.set(draftRef, updates, {merge: true});
-    batch.set(publishedRef, updates, {merge: true});
-    const len = Object.keys(strings).length;
+    batch.set(draftRef, data, {merge: true});
+    batch.set(publishedRef, data, {merge: true});
+    const len = Object.keys(data.strings).length;
     console.log(`[root cms] saving ${len} string(s) to ${translationsId}...`);
   });
   await batch.commit();
+
   console.log('[root cms] done migrating translations to v2');
 }
diff --git a/packages/root-cms/core/plugin.ts b/packages/root-cms/core/plugin.ts
index dcba7f38..6b95066c 100644
--- a/packages/root-cms/core/plugin.ts
+++ b/packages/root-cms/core/plugin.ts
@@ -447,8 +447,7 @@ export function cmsPlugin(options: CMSPluginOptions): CMSPlugin {
        */
       startup: async ({command, rootConfig}) => {
         if (command === 'dev' || command === 'build') {
-          const cmsPlugin = getCmsPlugin(rootConfig);
-          await runCompatibilityChecks(rootConfig, cmsPlugin);
+          await runCompatibilityChecks(rootConfig);
         }
       },
     },
diff --git a/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx b/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx
index 94174cad..11952cc2 100644
--- a/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx
+++ b/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx
@@ -4,10 +4,9 @@ import {showNotification, updateNotification} from '@mantine/notifications';
 import {ChangeEvent} from 'preact/compat';
 import {useEffect, useState} from 'preact/hooks';
 import {useModalTheme} from '../../hooks/useModalTheme.js';
+import {useTranslationsDoc} from '../../hooks/useTranslationsDoc.js';
 import {joinClassNames} from '../../utils/classes.js';
-import {CsvTranslation, cmsDocImportTranslations} from '../../utils/doc.js';
 import {GoogleSheetId, getSpreadsheetUrl} from '../../utils/gsheets.js';
-import {loadTranslations} from '../../utils/l10n.js';
 import {notifyErrors} from '../../utils/notifications.js';
 import {Heading} from '../Heading/Heading.js';
 import './EditTranslationsModal.css';
@@ -54,21 +53,22 @@ export function EditTranslationsModal(
   const [translationsMap, setTranslationsMap] = useState<
     Record<string, Record<string, string>>
   >({});
-  const [changedKeys, setChangedKeys] = useState<string[]>([]);
-  const [hasChanges, setHasChanges] = useState(false);
   const [saving, setSaving] = useState(false);
   const [loading, setLoading] = useState(true);
 
+  const translationsDoc = useTranslationsDoc(props.docId);
+
   useEffect(() => {
-    loadTranslations({tags: [props.docId]}).then((res) => {
-      const translationsMap: Record<string, Record<string, string>> = {};
-      Object.values(res).forEach((row) => {
-        translationsMap[row.source] = row;
-      });
-      setTranslationsMap(translationsMap);
-      setLoading(false);
+    if (translationsDoc.loading) {
+      return;
+    }
+    const translationsMap: Record<string, Record<string, string>> = {};
+    Object.entries(translationsDoc.strings).forEach(([hash, row]) => {
+      translationsMap[row.source] = {...row, hash};
     });
-  }, [props.docId]);
+    setTranslationsMap(translationsMap);
+    setLoading(false);
+  }, [translationsDoc.loading]);
 
   async function onSave() {
     setSaving(true);
@@ -83,12 +83,7 @@ export function EditTranslationsModal(
         autoClose: false,
         disallowClose: true,
       });
-      const changes: CsvTranslation[] = [];
-      changedKeys.forEach((changedKey) => {
-        const row = translationsMap[changedKey] as CsvTranslation;
-        changes.push(row);
-      });
-      await cmsDocImportTranslations(props.docId, changes);
+      await translationsDoc.saveTranslations();
       updateNotification({
         id: notificationId,
         title: 'Saved translations',
@@ -99,18 +94,8 @@ export function EditTranslationsModal(
     setSaving(false);
   }
 
-  function onChange(row: Record<string, string>) {
-    setTranslationsMap((current) => {
-      const newValue = {...current};
-      newValue[row.source] = row;
-      return newValue;
-    });
-    setChangedKeys((current) => {
-      const newValue = new Set(current);
-      newValue.add(row.source);
-      return Array.from(newValue);
-    });
-    setHasChanges(true);
+  function onChange(locale: string, source: string, translation: string) {
+    translationsDoc.setTranslation(locale, source, translation);
   }
 
   return (
@@ -195,7 +180,7 @@ export function EditTranslationsModal(
             size="xs"
             color="dark"
             onClick={() => onSave()}
-            disabled={!hasChanges}
+            disabled={!translationsDoc.hasPendingChanges}
             loading={saving}
           >
             Save
@@ -210,32 +195,21 @@ EditTranslationsModal.StringsEditor = (props: {
   source: string;
   locales: string[];
   translations: Record<string, string>;
-  onChange: (row: Record<string, string>) => void;
+  onChange: (locale: string, source: string, translation: string) => void;
 }) => {
   const locales = props.locales;
   const [translations, setTranslations] = useState<Record<string, string>>(
     props.translations || {}
   );
-  const [hasChanges, setHasChanges] = useState(false);
 
-  function updateTranslation(locale: string, value: string) {
-    setHasChanges(true);
-    setTranslations((current) => {
-      const newTranslations: Record<string, string> = {
-        ...current,
-        source: props.source,
-      };
-      newTranslations[locale] = value;
-      return newTranslations;
+  function updateTranslation(locale: string, translation: string) {
+    setTranslations((translations) => {
+      translations[locale] = translation;
+      return translations;
     });
+    props.onChange(locale, props.source, translation);
   }
 
-  useEffect(() => {
-    if (hasChanges) {
-      props.onChange(translations);
-    }
-  }, [hasChanges, translations]);
-
   return (
     <div className="EditTranslationsModal__StringsEditor">
       {locales.map((locale) => (
diff --git a/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.css b/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.css
index 13ca07c0..82ada891 100644
--- a/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.css
+++ b/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.css
@@ -42,12 +42,6 @@
   margin-bottom: 30px;
 }
 
-.LocalizationModal__translations__header__buttons {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-
 .LocalizationModal__translations__titleWrap {
   display: flex;
   align-items: center;
@@ -86,7 +80,3 @@
   gap: 8px;
   align-items: center;
 }
-
-.LocalizationModal__translations__menu__item .mantine-Menu-itemBody {
-  font-size: 13px;
-}
diff --git a/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx b/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx
index 6c06ac18..c1b254c7 100644
--- a/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx
+++ b/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx
@@ -24,27 +24,29 @@ import {
 } from '@tabler/icons-preact';
 import {useEffect, useMemo, useState} from 'preact/hooks';
 import * as schema from '../../../core/schema.js';
+import {TranslationsMap} from '../../db/translations.js';
 import {DraftController} from '../../hooks/useDraft.js';
 import {GapiClient, useGapiClient} from '../../hooks/useGapiClient.js';
 import {useModalTheme} from '../../hooks/useModalTheme.js';
+import {useTranslationsDoc} from '../../hooks/useTranslationsDoc.js';
 import {logAction} from '../../utils/actions.js';
 import {
   CsvTranslation,
   cmsDocImportTranslations,
   cmsGetLinkedGoogleSheetL10n,
+  cmsGetTranslations,
   cmsUnlinkGoogleSheetL10n,
 } from '../../utils/doc.js';
-import {extractStringsForDoc} from '../../utils/extract.js';
 import {
   GSheet,
   GSpreadsheet,
   GoogleSheetId,
   getSpreadsheetUrl,
 } from '../../utils/gsheets.js';
-import {TranslationsMap, loadTranslations} from '../../utils/l10n.js';
 import {useExportSheetModal} from '../ExportSheetModal/ExportSheetModal.js';
 import {Heading} from '../Heading/Heading.js';
 import './LocalizationModal.css';
+import {TranslationsImportExportButtons} from '../TranslationsImportExportButtons/TranslationsImportExportButtons.js';
 
 const MODAL_ID = 'LocalizationModal';
 
@@ -283,21 +285,32 @@ LocalizationModal.AllNoneButtons = (props: AllNoneButtonsProps) => {
   );
 };
 
-interface TranslationsProps {
-  collection: schema.Collection;
-  docId: string;
-}
-
-LocalizationModal.Translations = (props: TranslationsProps) => {
+LocalizationModal.Translations = (props: LocalizationModalProps) => {
   const [loading, setLoading] = useState(true);
   const [sourceStrings, setSourceStrings] = useState<string[]>([]);
-  const [selectedLocale, setSelectedLocale] = useState('en');
+  const [selectedLocale, setSelectedLocale] = useState(() => {
+    // Initialize with the first non-EN locale.
+    if (props.draft) {
+      const locales = props.draft.getLocales();
+      if (locales.length === 1) {
+        return locales[0];
+      }
+      if (locales.length > 1) {
+        for (const l of locales) {
+          if (l !== 'en') {
+            return l;
+          }
+        }
+      }
+    }
+    return 'en';
+  });
   const [localeTranslations, setLocaleTranslations] = useState<
     Record<string, string>
   >({});
   const [translationsMap, setTranslationsMap] = useState<TranslationsMap>({});
   const gapiClient = useGapiClient();
-  const [linkedSheet, setLinkedSheet] = useState<GoogleSheetId | null>(null);
+  // const [linkedSheet, setLinkedSheet] = useState<GoogleSheetId | null>(null);
   const exportSheetModal = useExportSheetModal();
 
   const sourceToTranslationsMap = useMemo(() => {
@@ -314,19 +327,23 @@ LocalizationModal.Translations = (props: TranslationsProps) => {
     label: getLocaleLabel(locale),
   }));
 
-  useEffect(() => {
+  const translationsDoc = useTranslationsDoc(props.docId);
+  const linkedSheet = translationsDoc.linkedSheet;
+
+  async function init() {
     setLoading(true);
-    Promise.all([
-      extractStringsForDoc(props.docId),
-      loadTranslations(),
-      cmsGetLinkedGoogleSheetL10n(props.docId),
-    ]).then(([sourceStrings, translationsMap, linkedSheet]) => {
-      setSourceStrings(sourceStrings);
-      setTranslationsMap(translationsMap);
-      setLinkedSheet(linkedSheet);
-      setLoading(false);
-    });
-  }, [props.docId]);
+    const translationsMap = translationsDoc?.strings || {};
+    const sourceStrings = Object.values(translationsMap)
+      .map((item) => item.source)
+      .filter((item) => !!item);
+    setSourceStrings(Array.from(sourceStrings));
+    setTranslationsMap(translationsMap);
+    setLoading(false);
+  }
+
+  useEffect(() => {
+    init();
+  }, [props.docId, translationsDoc.loading]);
 
   useEffect(() => {
     if (!selectedLocale) {
@@ -515,8 +532,7 @@ LocalizationModal.Translations = (props: TranslationsProps) => {
   }
 
   async function unlinkGoogleSheet() {
-    await cmsUnlinkGoogleSheetL10n(props.docId);
-    setLinkedSheet(null);
+    await translationsDoc.unlinkSheet();
     showNotification({
       title: 'Unlinked Google Sheet',
       message: `${props.docId} is no longer connected to a Google Sheet.`,
@@ -612,32 +628,10 @@ LocalizationModal.Translations = (props: TranslationsProps) => {
             Open Translations Editor
           </Button>
         </div>
-        <div className="LocalizationModal__translations__header__buttons">
-          {gapiClient.enabled && linkedSheet?.spreadsheetId && (
-            <Tooltip label="Open Google Sheet">
-              <ActionIcon<'a'>
-                component="a"
-                href={getSpreadsheetUrl(linkedSheet)}
-                target="_blank"
-                variant="filled"
-                color="green"
-                size="sm"
-              >
-                <IconTable size={16} strokeWidth={2.25} />
-              </ActionIcon>
-            </Tooltip>
-          )}
-          <ImportMenuButton
-            onAction={onAction}
-            gapiClient={gapiClient}
-            linkedSheet={linkedSheet}
-          />
-          <ExportMenuButton
-            onAction={onAction}
-            gapiClient={gapiClient}
-            linkedSheet={linkedSheet}
-          />
-        </div>
+        <TranslationsImportExportButtons
+          className="LocalizationModal__translations__header__buttons"
+          translationsDoc={translationsDoc}
+        />
       </div>
       <table className="LocalizationModal__translations__table">
         <tr className="LocalizationModal__translations__table__row LocalizationModal__translations__table__row--header">
@@ -703,146 +697,6 @@ LocalizationModal.Translations = (props: TranslationsProps) => {
   );
 };
 
-interface MenuButtonProps {
-  gapiClient: GapiClient;
-  linkedSheet: GoogleSheetId | null;
-  onAction?: (action: MenuAction) => void;
-}
-
-function ImportMenuButton(props: MenuButtonProps) {
-  function dispatch(action: MenuAction) {
-    if (props.onAction) {
-      props.onAction(action);
-    }
-  }
-
-  const linkedSheet = props.linkedSheet;
-
-  return (
-    <Menu
-      className="LocalizationModal__translations__menu"
-      position="bottom"
-      placement="end"
-      control={
-        <Button
-          variant="default"
-          color="dark"
-          size="xs"
-          leftIcon={<IconFileUpload size={16} strokeWidth={1.75} />}
-          rightIcon={<IconChevronDown size={16} strokeWidth={1.75} />}
-        >
-          Import
-        </Button>
-      }
-    >
-      {props.gapiClient.enabled && (
-        <>
-          <Menu.Label>Google Sheets</Menu.Label>
-          <Menu.Item
-            className="LocalizationModal__translations__menu__item"
-            disabled={!linkedSheet?.spreadsheetId}
-            onClick={() => dispatch(MenuAction.IMPORT_GOOGLE_SHEET_LINKED)}
-          >
-            Import Google Sheet
-          </Menu.Item>
-          <Divider />
-        </>
-      )}
-      <Menu.Label>File</Menu.Label>
-      <Menu.Item
-        className="LocalizationModal__translations__menu__item"
-        onClick={() => dispatch(MenuAction.IMPORT_CSV)}
-      >
-        Import .csv
-      </Menu.Item>
-    </Menu>
-  );
-}
-
-function ExportMenuButton(props: MenuButtonProps) {
-  async function dispatch(action: MenuAction) {
-    if (props.onAction) {
-      props.onAction(action);
-    }
-  }
-
-  const linkedSheet = props.linkedSheet;
-  const hasLinkedSheet = !!linkedSheet?.spreadsheetId;
-
-  return (
-    <Menu
-      className="LocalizationModal__translations__menu"
-      position="bottom"
-      placement="start"
-      control={
-        <Button
-          variant="default"
-          color="dark"
-          size="xs"
-          leftIcon={<IconFileDownload size={16} strokeWidth={1.75} />}
-          rightIcon={<IconChevronDown size={16} strokeWidth={1.75} />}
-        >
-          Export
-        </Button>
-      }
-    >
-      {props.gapiClient.enabled && (
-        <>
-          <Menu.Label>Google Sheets</Menu.Label>
-          {hasLinkedSheet ? (
-            <>
-              <Menu.Item
-                className="LocalizationModal__translations__menu__item"
-                onClick={() => dispatch(MenuAction.EXPORT_GOOGLE_SHEET_LINKED)}
-              >
-                Export to Google Sheet
-              </Menu.Item>
-            </>
-          ) : (
-            <>
-              <Menu.Item
-                className="LocalizationModal__translations__menu__item"
-                onClick={() =>
-                  dispatch(MenuAction.EXPORT_GOOGLE_SHEET_SHOW_OPTIONS)
-                }
-              >
-                Export to Google Sheet
-              </Menu.Item>
-              {/* <Menu.Item
-                className="LocalizationModal__translations__menu__item"
-                onClick={() => dispatch(MenuAction.EXPORT_GOOGLE_SHEET_ADD_TAB)}
-              >
-                Add tab in Google Sheet
-              </Menu.Item> */}
-            </>
-          )}
-          <Divider />
-        </>
-      )}
-      <Menu.Label>File</Menu.Label>
-      <Menu.Item
-        className="LocalizationModal__translations__menu__item"
-        onClick={() => dispatch(MenuAction.EXPORT_DOWNLOAD_CSV)}
-      >
-        Download .csv
-      </Menu.Item>
-      {hasLinkedSheet && (
-        <>
-          <Divider />
-          <Menu.Label>Danger zone</Menu.Label>
-          <Menu.Item
-            className="LocalizationModal__translations__menu__item"
-            onClick={() => dispatch(MenuAction.UNLINK_GOOGLE_SHEET)}
-            color="red"
-          >
-            Unlink Google Sheet
-          </Menu.Item>
-        </>
-      )}
-    </Menu>
-  );
-}
-
 function getLocaleLabel(locale: string) {
   const parts = locale.split('_');
   const langCode = parts[0];
diff --git a/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.css b/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.css
new file mode 100644
index 00000000..c4ca998a
--- /dev/null
+++ b/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.css
@@ -0,0 +1,9 @@
+.TranslationsImportExportButtons {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.TranslationsImportExportButtons__Menu__item .mantine-Menu-itemBody {
+  font-size: 13px;
+}
diff --git a/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx b/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx
new file mode 100644
index 00000000..b6a5f99b
--- /dev/null
+++ b/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx
@@ -0,0 +1,460 @@
+import {ActionIcon, Button, Divider, Menu, Tooltip} from '@mantine/core';
+import {showNotification} from '@mantine/notifications';
+import {
+  IconChevronDown,
+  IconFileDownload,
+  IconFileUpload,
+  IconTable,
+} from '@tabler/icons-preact';
+import {
+  csvToTranslationsMap,
+  Translations,
+  translationsIdToDocId,
+} from '../../db/translations.js';
+import {GapiClient, useGapiClient} from '../../hooks/useGapiClient.js';
+import {TranslationsDocController} from '../../hooks/useTranslationsDoc.js';
+import {logAction} from '../../utils/actions.js';
+import {joinClassNames} from '../../utils/classes.js';
+import {
+  getSpreadsheetUrl,
+  GoogleSheetId,
+  GSheet,
+  GSpreadsheet,
+} from '../../utils/gsheets.js';
+import {useExportSheetModal} from '../ExportSheetModal/ExportSheetModal.js';
+
+import './TranslationsImportExportButtons.css';
+
+enum MenuAction {
+  EXPORT_DOWNLOAD_CSV = 'EXPORT_DOWNLOAD_CSV',
+  EXPORT_GOOGLE_SHEET_CREATE = 'EXPORT_GOOGLE_SHEET_CREATE',
+  EXPORT_GOOGLE_SHEET_ADD_TAB = 'EXPORT_GOOGLE_SHEET_ADD_TAB',
+  EXPORT_GOOGLE_SHEET_LINKED = 'EXPORT_GOOGLE_SHEET_LINKED',
+  EXPORT_GOOGLE_SHEET_SHOW_OPTIONS = 'EXPORT_GOOGLE_SHEET_SHOW_OPTIONS',
+  IMPORT_CSV = 'IMPORT_CSV',
+  IMPORT_GOOGLE_SHEET_LINKED = 'IMPORT_GOOGLE_SHEET_LINKED',
+  UNLINK_GOOGLE_SHEET = 'UNLINK_GOOGLE_SHEET',
+}
+
+export interface TranslationsImportExportButtonsProps {
+  className?: string;
+  translationsDoc: TranslationsDocController;
+}
+
+export function TranslationsImportExportButtons(
+  props: TranslationsImportExportButtonsProps
+) {
+  const translationsDoc = props.translationsDoc;
+  const strings = translationsDoc.strings || {};
+  const linkedSheet = translationsDoc.linkedSheet;
+  const translationsId = translationsDoc.id;
+  const docId = translationsIdToDocId(translationsId);
+
+  const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
+  const locales = i18nConfig.locales || ['en'];
+
+  const gapiClient = useGapiClient();
+  const exportSheetModal = useExportSheetModal();
+
+  function formatCsvData() {
+    const nonEnLocales = locales.filter((locale) => locale !== 'en');
+    const headers = ['source', 'en', ...nonEnLocales];
+    const rows: Array<Record<string, string>> = [];
+    Object.values(strings).forEach((item) => {
+      if (!item.source) {
+        return;
+      }
+      const row: Record<string, string> = {
+        source: item.source,
+        en: item.en || item.source,
+      };
+      nonEnLocales.forEach((locale: string) => {
+        row[locale] = item[locale];
+      });
+      rows.push(row);
+    });
+    return {headers, rows};
+  }
+
+  async function downloadCsv() {
+    const {headers, rows} = formatCsvData();
+    const res = await window.fetch('/cms/api/csv.download', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({headers, rows}),
+    });
+    if (res.status !== 200) {
+      console.error('csv.download failed:');
+      const text = await res.text();
+      console.error(text);
+    }
+    const blob = await res.blob();
+    const file = window.URL.createObjectURL(blob);
+    window.location.assign(file);
+    window.URL.revokeObjectURL(file);
+  }
+
+  async function importCsv() {
+    const fileInput = document.createElement('input');
+    fileInput.type = 'file';
+    fileInput.accept = '.csv';
+    fileInput.addEventListener('change', async () => {
+      const file = fileInput.files?.[0];
+      if (file) {
+        const formData = new FormData();
+        formData.append('file', file);
+        try {
+          const res = await fetch('/cms/api/csv.import', {
+            method: 'POST',
+            body: formData,
+          });
+          if (res.status !== 200) {
+            const errorText = await res.text();
+            throw new Error(`RPCError: ${errorText}`);
+          }
+          const values = (await res.json()).data as Translations[];
+          const strings = await csvToTranslationsMap(values);
+          translationsDoc.importTranslations(strings);
+          await translationsDoc.saveTranslations();
+
+          showNotification({
+            title: 'Saved!',
+            message: `Imported translations for ${translationsId}.`,
+            autoClose: 5000,
+          });
+        } catch (err) {
+          console.error(err);
+          showNotification({
+            title: 'Failed to import CSV',
+            message: String(err),
+            color: 'red',
+            autoClose: false,
+          });
+        }
+      }
+    });
+    fileInput.click();
+  }
+
+  async function exportToLinkedSheet() {
+    if (!gapiClient.isLoggedIn()) {
+      await gapiClient.login();
+    }
+    if (!linkedSheet?.spreadsheetId) {
+      throw new Error('no sheet linked');
+    }
+    const gspreadsheet = new GSpreadsheet(linkedSheet.spreadsheetId);
+    const gsheet = await gspreadsheet.getSheet(linkedSheet.gid ?? 0);
+    if (!gsheet) {
+      throw new Error(`sheet not found: ${JSON.stringify(linkedSheet)}`);
+    }
+    await exportStringsToSheet(gsheet);
+    showNotification({
+      title: 'Exported strings to Google Sheet',
+      message: gsheet.getUrl(),
+      autoClose: false,
+    });
+  }
+
+  async function exportStringsToSheet(
+    gsheet: GSheet,
+    options?: {isNew?: boolean}
+  ) {
+    const isNew = options?.isNew || false;
+    const {headers, rows} = formatCsvData();
+    if (isNew) {
+      // Update sheet data.
+      await gsheet.replaceSheet(headers, rows);
+      // Apply the default styles to the sheet.
+      await gsheet.applyL10nTheme();
+    } else {
+      // Update existing sheet, replacing only cells as needed (keyed by the
+      // "source" column). New rows are added to the end of the sheet.
+      await gsheet.updateValuesMap(rows, {
+        keyedBy: 'source',
+        // When exporting strings, avoid overwriting cells where there is an
+        // existing translation. If users want to export translations from the
+        // CMS to the sheet, they should clear those cells first.
+        preserveColumns: locales,
+      });
+    }
+    logAction('doc.export_to_sheet', {
+      metadata: {
+        docId: docId,
+        sheetId: {
+          spreadsheetId: gsheet.spreadsheet.spreadsheetId,
+          gid: gsheet.gid,
+        },
+      },
+    });
+  }
+
+  async function importGoogleSheet() {
+    if (!gapiClient.isLoggedIn()) {
+      await gapiClient.login();
+    }
+    if (!linkedSheet?.spreadsheetId) {
+      throw new Error('no sheet linked');
+    }
+    const gspreadsheet = new GSpreadsheet(linkedSheet.spreadsheetId);
+    const gsheet = await gspreadsheet.getSheet(linkedSheet.gid ?? 0);
+    if (!gsheet) {
+      throw new Error(`sheet not found: ${JSON.stringify(linkedSheet)}`);
+    }
+
+    console.log('importing google sheet');
+    const values = (await gsheet.getValuesMap()) as Translations[];
+    const strings = await csvToTranslationsMap(values);
+    translationsDoc.importTranslations(strings);
+    await translationsDoc.saveTranslations();
+
+    showNotification({
+      title: 'Saved!',
+      message: `Imported translations for ${translationsId}.`,
+      autoClose: 5000,
+    });
+  }
+
+  async function unlinkGoogleSheet() {
+    await translationsDoc.unlinkSheet();
+    showNotification({
+      title: 'Unlinked Google Sheet',
+      message: `${translationsId} is no longer connected to a Google Sheet.`,
+      autoClose: 5000,
+    });
+  }
+
+  /**
+   * Wrapper that calls a function and shows a generic error notification if any
+   * exceptions occur.
+   */
+  async function notifyErrors(fn: () => Promise<void>) {
+    try {
+      await fn();
+    } catch (err) {
+      console.error(err);
+      let msg: string;
+      if (typeof err === 'object' && err.body) {
+        msg = String(err.body);
+      } else {
+        msg = String(err);
+      }
+      showNotification({
+        title: 'Error',
+        message: msg,
+        color: 'red',
+        autoClose: false,
+      });
+    }
+  }
+
+  function onAction(action: MenuAction) {
+    switch (action) {
+      case MenuAction.EXPORT_DOWNLOAD_CSV: {
+        notifyErrors(downloadCsv);
+        return;
+      }
+      case MenuAction.EXPORT_GOOGLE_SHEET_LINKED: {
+        notifyErrors(exportToLinkedSheet);
+        return;
+      }
+      case MenuAction.EXPORT_GOOGLE_SHEET_SHOW_OPTIONS: {
+        exportSheetModal.open({
+          docId: translationsId,
+          csvData: formatCsvData(),
+          locales: locales,
+        });
+        return;
+      }
+      case MenuAction.IMPORT_CSV: {
+        notifyErrors(importCsv);
+        return;
+      }
+      case MenuAction.IMPORT_GOOGLE_SHEET_LINKED: {
+        notifyErrors(importGoogleSheet);
+        return;
+      }
+      case MenuAction.UNLINK_GOOGLE_SHEET: {
+        notifyErrors(unlinkGoogleSheet);
+        return;
+      }
+      default: {
+        console.log('unhandled action: ' + action);
+      }
+    }
+  }
+
+  return (
+    <div
+      className={joinClassNames(
+        props.className,
+        'TranslationsImportExportButtons'
+      )}
+    >
+      {gapiClient.enabled && linkedSheet?.spreadsheetId && (
+        <Tooltip label="Open Google Sheet">
+          <ActionIcon<'a'>
+            component="a"
+            href={getSpreadsheetUrl(linkedSheet)}
+            target="_blank"
+            variant="filled"
+            color="green"
+            size="sm"
+          >
+            <IconTable size={16} strokeWidth={2.25} />
+          </ActionIcon>
+        </Tooltip>
+      )}
+      <ImportMenuButton
+        onAction={onAction}
+        gapiClient={gapiClient}
+        linkedSheet={linkedSheet}
+      />
+      <ExportMenuButton
+        onAction={onAction}
+        gapiClient={gapiClient}
+        linkedSheet={linkedSheet}
+      />
+    </div>
+  );
+}
+
+function ImportMenuButton(props: MenuButtonProps) {
+  function dispatch(action: MenuAction) {
+    if (props.onAction) {
+      props.onAction(action);
+    }
+  }
+
+  const linkedSheet = props.linkedSheet;
+
+  return (
+    <Menu
+      className="TranslationsImportExportButtons__Menu"
+      position="bottom"
+      placement="end"
+      control={
+        <Button
+          variant="default"
+          color="dark"
+          size="xs"
+          leftIcon={<IconFileUpload size={16} strokeWidth={1.75} />}
+          rightIcon={<IconChevronDown size={16} strokeWidth={1.75} />}
+        >
+          Import
+        </Button>
+      }
+    >
+      {props.gapiClient.enabled && (
+        <>
+          <Menu.Label>Google Sheets</Menu.Label>
+          <Menu.Item
+            className="TranslationsImportExportButtons__Menu__item"
+            disabled={!linkedSheet?.spreadsheetId}
+            onClick={() => dispatch(MenuAction.IMPORT_GOOGLE_SHEET_LINKED)}
+          >
+            Import Google Sheet
+          </Menu.Item>
+          <Divider />
+        </>
+      )}
+      <Menu.Label>File</Menu.Label>
+      <Menu.Item
+        className="TranslationsImportExportButtons__Menu__item"
+        onClick={() => dispatch(MenuAction.IMPORT_CSV)}
+      >
+        Import .csv
+      </Menu.Item>
+    </Menu>
+  );
+}
+
+interface MenuButtonProps {
+  gapiClient: GapiClient;
+  linkedSheet: GoogleSheetId | null;
+  onAction?: (action: MenuAction) => void;
+}
+
+function ExportMenuButton(props: MenuButtonProps) {
+  async function dispatch(action: MenuAction) {
+    if (props.onAction) {
+      props.onAction(action);
+    }
+  }
+
+  const linkedSheet = props.linkedSheet;
+  const hasLinkedSheet = !!linkedSheet?.spreadsheetId;
+
+  return (
+    <Menu
+      className="TranslationsImportExportButtons__Menu"
+      position="bottom"
+      placement="start"
+      control={
+        <Button
+          variant="default"
+          color="dark"
+          size="xs"
+          leftIcon={<IconFileDownload size={16} strokeWidth={1.75} />}
+          rightIcon={<IconChevronDown size={16} strokeWidth={1.75} />}
+        >
+          Export
+        </Button>
+      }
+    >
+      {props.gapiClient.enabled && (
+        <>
+          <Menu.Label>Google Sheets</Menu.Label>
+          {hasLinkedSheet ? (
+            <>
+              <Menu.Item
+                className="TranslationsImportExportButtons__Menu__item"
+                onClick={() => dispatch(MenuAction.EXPORT_GOOGLE_SHEET_LINKED)}
+              >
+                Export to Google Sheet
+              </Menu.Item>
+            </>
+          ) : (
+            <>
+              <Menu.Item
+                className="TranslationsImportExportButtons__Menu__item"
+                onClick={() =>
+                  dispatch(MenuAction.EXPORT_GOOGLE_SHEET_SHOW_OPTIONS)
+                }
+              >
+                Export to Google Sheet
+              </Menu.Item>
+              {/* <Menu.Item
+                className="TranslationsImportExportButtons__Menu__item"
+                onClick={() => dispatch(MenuAction.EXPORT_GOOGLE_SHEET_ADD_TAB)}
+              >
+                Add tab in Google Sheet
+              </Menu.Item> */}
+            </>
+          )}
+          <Divider />
+        </>
+      )}
+      <Menu.Label>File</Menu.Label>
+      <Menu.Item
+        className="TranslationsImportExportButtons__Menu__item"
+        onClick={() => dispatch(MenuAction.EXPORT_DOWNLOAD_CSV)}
+      >
+        Download .csv
+      </Menu.Item>
+      {hasLinkedSheet && (
+        <>
+          <Divider />
+          <Menu.Label>Danger zone</Menu.Label>
+          <Menu.Item
+            className="TranslationsImportExportButtons__Menu__item"
+            onClick={() => dispatch(MenuAction.UNLINK_GOOGLE_SHEET)}
+            color="red"
+          >
+            Unlink Google Sheet
+          </Menu.Item>
+        </>
+      )}
+    </Menu>
+  );
+}
diff --git a/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx b/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx
new file mode 100644
index 00000000..b26a02a6
--- /dev/null
+++ b/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx
@@ -0,0 +1,50 @@
+import {Badge, Tooltip} from '@mantine/core';
+import {TranslationsDoc} from '../../utils/doc.js';
+import {timeDiff} from '../../utils/time.js';
+
+interface TranslationsStatusBadgesProps {
+  translationsDoc: TranslationsDoc;
+  tooltipPosition?: 'bottom' | 'top';
+}
+
+export function TranslationsStatusBadges(props: TranslationsStatusBadgesProps) {
+  const tooltipProps = {
+    // position: props.tooltipPosition || 'bottom',
+    transition: 'pop',
+  };
+  const sys = props.translationsDoc?.sys || {};
+  return (
+    <div className="CollectionPage__collection__docsList__doc__content__header__badges">
+      {(!sys.publishedAt ||
+        !sys.modifiedAt ||
+        sys.modifiedAt > sys.publishedAt) && (
+        <Tooltip
+          {...tooltipProps}
+          label={`Modified ${timeDiff(sys.modifiedAt)} by ${sys.modifiedBy}`}
+        >
+          <Badge
+            size="xs"
+            variant="gradient"
+            gradient={{from: 'indigo', to: 'cyan'}}
+          >
+            Draft
+          </Badge>
+        </Tooltip>
+      )}
+      {!!sys.publishedAt && (
+        <Tooltip
+          {...tooltipProps}
+          label={`Published ${timeDiff(sys.publishedAt)} by ${sys.publishedBy}`}
+        >
+          <Badge
+            size="xs"
+            variant="gradient"
+            gradient={{from: 'teal', to: 'lime', deg: 105}}
+          >
+            Published
+          </Badge>
+        </Tooltip>
+      )}
+    </div>
+  );
+}
diff --git a/packages/root-cms/ui/db/translations.ts b/packages/root-cms/ui/db/translations.ts
new file mode 100644
index 00000000..16479ad9
--- /dev/null
+++ b/packages/root-cms/ui/db/translations.ts
@@ -0,0 +1,239 @@
+/**
+ * Utility functions for reading and writing translations from the db.
+ */
+
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  query,
+  serverTimestamp,
+  setDoc,
+  Timestamp,
+  writeBatch,
+  WriteBatch,
+} from 'firebase/firestore';
+import {logAction} from '../utils/actions.js';
+import {normalizeString, sourceHash} from '../utils/l10n.js';
+
+export interface Translations {
+  [locale: string]: string;
+  source: string;
+}
+
+export interface TranslationsMap {
+  [hash: string]: Translations;
+}
+
+export interface TranslationsLinkedSheet {
+  spreadsheetId: string;
+  gid: number;
+  linkedAt: Timestamp;
+  linkedBy: string;
+}
+
+export interface TranslationsDoc {
+  id: string;
+  sys: {
+    modifiedAt: Timestamp;
+    modifiedBy: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+    linkedSheet?: TranslationsLinkedSheet;
+  };
+  strings: TranslationsMap;
+}
+
+/**
+ * Saves translations to `/Projects/<project>/TranslationsManager/draft/<translationsId>`
+ * where the translations map is in the following format:
+ *
+ * ```
+ * {
+ *   "<source hash>": {"source": "...", "<locale>": "<translation>"}
+ * }
+ * ```
+ */
+export async function dbSaveTranslations(
+  translationsId: string,
+  translationsMap: TranslationsMap
+) {
+  const projectId = window.__ROOT_CTX.rootConfig.projectId;
+  const db = window.firebase.db;
+  const docRef = doc(
+    db,
+    'Projects',
+    projectId,
+    'TranslationsManager',
+    'draft',
+    'Translations',
+    translationsId.replaceAll('/', '--')
+  );
+  const snapshot = await getDoc(docRef);
+  const data = snapshot.data() || {
+    id: translationsId.replaceAll('--', '/'),
+    sys: {},
+    strings: {},
+  };
+  data.sys.modifiedAt = serverTimestamp();
+  data.sys.modifiedBy = window.firebase.user.email;
+
+  const strings = data.strings || {};
+  Object.entries(translationsMap).forEach(([hash, translations]) => {
+    strings[hash] = {...strings[hash], ...translations};
+  });
+  data.strings = strings;
+  await setDoc(docRef, data);
+  logAction('translations.save', {metadata: {translationsId}});
+  return strings;
+}
+
+/**
+ * Fetches the translations doc from `/Projects/<project>/TranslationsManager/draft/<translationsId>`.
+ */
+export async function dbGetTranslationsDoc(
+  translationsId: string
+): Promise<TranslationsDoc | null> {
+  const projectId = window.__ROOT_CTX.rootConfig.projectId;
+  const db = window.firebase.db;
+  const docRef = doc(
+    db,
+    'Projects',
+    projectId,
+    'TranslationsManager',
+    'draft',
+    'Translations',
+    translationsId.replaceAll('/', '--')
+  );
+  const snapshot = await getDoc(docRef);
+  if (!snapshot.exists()) {
+    return null;
+  }
+  return snapshot.data() as TranslationsDoc;
+}
+
+/**
+ * Gets translations from `/Projects/<project>/TranslationsManager/draft/<translationsId>`.
+ */
+export async function dbGetTranslations(
+  translationsId: string
+): Promise<TranslationsMap> {
+  const translationsDoc = await dbGetTranslationsDoc(translationsId);
+  return translationsDoc?.strings || {};
+}
+
+/**
+ * Publishes translations to `/Projects/<project>/TranslationsManager/published/<translationsId>`.
+ */
+export async function dbPublishTranslationsDoc(
+  translationsId: string,
+  options?: {batch?: WriteBatch}
+) {
+  const projectId = window.__ROOT_CTX.rootConfig.projectId;
+  const db = window.firebase.db;
+  const docSlug = translationsId.replaceAll('/', '--');
+  const draftRef = doc(
+    db,
+    'Projects',
+    projectId,
+    'TranslationsManager',
+    'draft',
+    'Translations',
+    docSlug
+  );
+  const snapshot = await getDoc(draftRef);
+  if (!snapshot.exists()) {
+    throw new Error(`translations doc ${translationsId} does not exist`);
+  }
+
+  // If the translations publishing is tied to another batch request (e.g. doc
+  // publishing), the batch request will be committed upstream.
+  const commitBatch = !options?.batch;
+
+  const batch = options?.batch || writeBatch(db);
+  batch.update(draftRef, {
+    'sys.publishedAt': serverTimestamp(),
+    'sys.publishedBy': window.firebase.user.email,
+  });
+
+  const publishedRef = doc(
+    db,
+    'Projects',
+    projectId,
+    'TranslationsManager',
+    'published',
+    'Translations',
+    docSlug
+  );
+  const data = {...snapshot.data()};
+  if (!data.sys) {
+    data.sys = {};
+  }
+  data.sys.publishedAt = serverTimestamp();
+  data.sys.publishedBy = window.firebase.user.email;
+  batch.set(publishedRef, data);
+  if (commitBatch) {
+    await setDoc(publishedRef, data);
+    logAction('translations.publish', {metadata: {translationsId}});
+  }
+}
+
+/**
+ * Lists translation docs in the TranslationsManager.
+ */
+export async function dbListTranslationsDocs(): Promise<TranslationsDoc[]> {
+  const projectId = window.__ROOT_CTX.rootConfig.projectId;
+  const db = window.firebase.db;
+  const versionsCollection = collection(
+    db,
+    'Projects',
+    projectId,
+    'TranslationsManager',
+    'draft',
+    'Translations'
+  );
+  const q = query(versionsCollection);
+  const querySnapshot = await getDocs(q);
+  const translationDocs: TranslationsDoc[] = [];
+  querySnapshot.forEach((doc) => {
+    translationDocs.push(doc.data() as TranslationsDoc);
+  });
+  return translationDocs;
+}
+
+/**
+ * Converts a translations id (e.g. `Pages--foo--bar`) to a doc id (e.g.
+ * `Pages/foo--bar`).
+ */
+export function translationsIdToDocId(translationsId: string): string {
+  let docId = translationsId;
+  if (!docId.includes('/') && translationsId.includes('--')) {
+    docId = translationsId.replace('--', '/');
+  }
+  return docId;
+}
+
+/**
+ * Converts an array of CSV data to a TranslationsMap.
+ */
+export async function csvToTranslationsMap(
+  rows: Translations[]
+): Promise<TranslationsMap> {
+  const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
+  const i18nLocales = i18nConfig.locales || ['en'];
+  const strings: TranslationsMap = {};
+  for (const row of rows) {
+    if (row.source) {
+      const hash = await sourceHash(row.source);
+      const cleanRows: Translations = {source: normalizeString(row.source)};
+      for (const locale of i18nLocales) {
+        if (row[locale]) {
+          cleanRows[locale] = normalizeString(row[locale]);
+        }
+      }
+      strings[hash] = cleanRows;
+    }
+  }
+  return strings;
+}
diff --git a/packages/root-cms/ui/hooks/useTranslationsDoc.ts b/packages/root-cms/ui/hooks/useTranslationsDoc.ts
new file mode 100644
index 00000000..fbb3e885
--- /dev/null
+++ b/packages/root-cms/ui/hooks/useTranslationsDoc.ts
@@ -0,0 +1,164 @@
+import {useEffect, useState} from 'preact/hooks';
+import {
+  TranslationsDoc,
+  TranslationsLinkedSheet,
+  TranslationsMap,
+  dbGetTranslationsDoc,
+  dbSaveTranslations,
+} from '../db/translations.js';
+import {extractStringsForDoc} from '../utils/extract.js';
+import {normalizeString, sourceHash} from '../utils/l10n.js';
+
+export interface TranslationsDocController {
+  id: string;
+  loading: boolean;
+  strings: TranslationsMap;
+  linkedSheet: TranslationsLinkedSheet | null;
+  setTranslation: (
+    locale: string,
+    source: string,
+    translation: string
+  ) => Promise<void>;
+  importTranslations: (strings: TranslationsMap) => void;
+  hasPendingChanges: boolean;
+  pendingChanges: TranslationsMap;
+  saveTranslations: () => Promise<void>;
+  unlinkSheet: () => Promise<void>;
+}
+
+/**
+ * Hook that fetches a translations doc and provides utility methods for
+ * updating the translations and configurations.
+ */
+export function useTranslationsDoc(
+  translationsId: string
+): TranslationsDocController {
+  const [loading, setLoading] = useState(true);
+  const [translationsDoc, setTranslationsDoc] =
+    useState<TranslationsDoc | null>(null);
+  const [strings, setStrings] = useState<TranslationsMap>({});
+  const [linkedSheet, setLinkedSheet] =
+    useState<TranslationsLinkedSheet | null>(null);
+  const [pendingChanges, setPendingChanges] = useState<TranslationsMap>({});
+  const hasPendingChanges = Object.keys(pendingChanges).length > 0;
+
+  async function init() {
+    setLoading(true);
+    const [docStrings, translationsDoc] = await Promise.all([
+      getTranslationsMapForDoc(translationsId),
+      dbGetTranslationsDoc(translationsId),
+    ]);
+    setTranslationsDoc(translationsDoc);
+    const strings = mergeTranslationsMaps(
+      docStrings,
+      translationsDoc?.strings || {}
+    );
+    setStrings(strings);
+    setLoading(false);
+  }
+
+  async function setTranslation(
+    locale: string,
+    source: string,
+    translation: string
+  ) {
+    const hash = await sourceHash(source);
+    const strings: TranslationsMap = {
+      [hash]: {
+        source: normalizeString(source),
+        [locale]: normalizeString(translation),
+      },
+    };
+    importTranslations(strings);
+  }
+
+  async function importTranslations(strings: TranslationsMap) {
+    setPendingChanges((oldValue) => {
+      const newValue = {...oldValue};
+      Object.entries(strings).forEach(([hash, translations]) => {
+        newValue[hash] = {
+          ...oldValue[hash],
+          ...translations,
+        };
+      });
+      return newValue;
+    });
+    setStrings((oldValue) => {
+      const newValue = {...oldValue};
+      Object.entries(strings).forEach(([hash, translations]) => {
+        newValue[hash] = {
+          ...oldValue[hash],
+          ...translations,
+        };
+      });
+      return newValue;
+    });
+  }
+
+  async function saveTranslations() {
+    if (!hasPendingChanges) {
+      return;
+    }
+    const newStrings = await dbSaveTranslations(translationsId, pendingChanges);
+    setStrings(newStrings);
+  }
+
+  async function unlinkSheet() {
+    setLinkedSheet(null);
+    // TODO(stevenle): impl dbTranslationsUnlinkSheet().
+  }
+
+  useEffect(() => {
+    init();
+  }, [translationsId]);
+
+  return {
+    id: translationsId,
+    loading,
+    strings,
+    linkedSheet,
+    unlinkSheet,
+    setTranslation,
+    importTranslations,
+    hasPendingChanges,
+    pendingChanges,
+    saveTranslations,
+  };
+}
+
+async function getTranslationsMapForDoc(
+  docId: string
+): Promise<TranslationsMap> {
+  if (!docId.includes('/') && docId.includes('--')) {
+    // Replace only the first instance of '--' to '/'.
+    docId = docId.replace('--', '/');
+  }
+  if (!docId.includes('/')) {
+    return {};
+  }
+  const collectionId = docId.split('/')[0];
+  if (!window.__ROOT_CTX.collections[collectionId]) {
+    return {};
+  }
+  const docStrings = await extractStringsForDoc(docId);
+  const translationsMap: TranslationsMap = {};
+  for (const source of docStrings) {
+    const hash = await sourceHash(source);
+    translationsMap[hash] = {source, en: source};
+  }
+  return translationsMap;
+}
+
+function mergeTranslationsMaps(
+  a: TranslationsMap,
+  b: TranslationsMap
+): TranslationsMap {
+  const merged: TranslationsMap = {};
+  Object.entries(a).forEach(([hash, translations]) => {
+    merged[hash] = {...translations};
+  });
+  Object.entries(b).forEach(([hash, translations]) => {
+    merged[hash] = {...merged[hash], ...translations};
+  });
+  return merged;
+}
diff --git a/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.css b/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.css
index fc431c00..340ae984 100644
--- a/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.css
+++ b/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.css
@@ -6,11 +6,16 @@
 }
 
 .DocTranslationsPage__header {
-  padding: 48px 60px 30px;
+  padding: 30px;
   position: sticky;
   left: 0;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 10px 40px;
 }
 
+
 .DocTranslationsPage__header__breadcrumbs {
   font-size: 12px;
   margin-bottom: 12px;
@@ -33,12 +38,6 @@
 
 .DocTranslationsPage__header__linkedSheet {
   margin-top: 10px;
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-
-.DocTranslationsPage__header__linkedSheet__label {
   font-size: 14px;
 }
 
@@ -99,12 +98,12 @@
 
 .DocTranslationsPage__Table__sourceCell {
   white-space: pre-wrap;
+  overflow: auto;
 }
 
 .DocTranslationsPage__Table__sourceCell,
 .DocTranslationsPage__Textarea {
   padding: 6px 10px;
-  height: 100%;
 }
 
 .DocTranslationsPage__Textarea {
@@ -117,6 +116,7 @@
   width: 100%;
   border: 1px solid transparent;
   border-radius: 0;
+  height: 100%;
   min-height: 100%;
 }
 
@@ -124,6 +124,10 @@
   background-color: #FFF5F5;
 }
 
+.DocTranslationsPage__Textarea--empty:focus {
+  background-color: transparent;
+}
+
 .DocTranslationsPage__Table td:has(.DocTranslationsPage__Textarea--hasChanges) {
   background-color: #FFF9DB;
 }
diff --git a/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.tsx b/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.tsx
index 14c1827e..ea2954eb 100644
--- a/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.tsx
+++ b/packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.tsx
@@ -1,27 +1,14 @@
-import {ActionIcon, Breadcrumbs, Button, Loader, Tooltip} from '@mantine/core';
+import {Breadcrumbs, Button, Loader} from '@mantine/core';
 import {showNotification, updateNotification} from '@mantine/notifications';
-import {
-  IconFileDownload,
-  IconFileUpload,
-  IconMoodLookDown,
-  IconTable,
-} from '@tabler/icons-preact';
+import {IconMoodLookDown} from '@tabler/icons-preact';
 import {useEffect, useMemo, useRef, useState} from 'preact/hooks';
 import {Heading} from '../../components/Heading/Heading.js';
+import {TranslationsImportExportButtons} from '../../components/TranslationsImportExportButtons/TranslationsImportExportButtons.js';
+import {TranslationsMap} from '../../db/translations.js';
+import {useTranslationsDoc} from '../../hooks/useTranslationsDoc.js';
 import {Layout} from '../../layout/Layout.js';
 import {joinClassNames} from '../../utils/classes.js';
-import {
-  CsvTranslation,
-  cmsDocImportTranslations,
-  cmsGetLinkedGoogleSheetL10n,
-} from '../../utils/doc.js';
-import {extractStringsForDoc} from '../../utils/extract.js';
-import {GoogleSheetId, getSpreadsheetUrl} from '../../utils/gsheets.js';
-import {
-  Translation,
-  TranslationsMap,
-  loadTranslations,
-} from '../../utils/l10n.js';
+import {getSpreadsheetUrl} from '../../utils/gsheets.js';
 import {notifyErrors} from '../../utils/notifications.js';
 import './DocTranslationsPage.css';
 
@@ -35,9 +22,6 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
   const [notFound, setNotFound] = useState(false);
   const [sourceStrings, setSourceStrings] = useState<string[]>([]);
   const [translationsMap, setTranslationsMap] = useState<TranslationsMap>({});
-  const [linkedSheet, setLinkedSheet] = useState<GoogleSheetId | null>(null);
-  const [hasChanges, setHasChanges] = useState(false);
-  const [changesMap, setChangesMap] = useState<Record<string, Translation>>({});
   const [saving, setSaving] = useState(false);
   const collection = props.collection;
   const slug = props.slug;
@@ -46,16 +30,20 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
   const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
   const i18nLocales = i18nConfig.locales || ['en'];
 
+  const translationsDoc = useTranslationsDoc(docId);
+  const linkedSheet = translationsDoc.linkedSheet;
+
   async function init() {
+    if (translationsDoc.loading) {
+      return;
+    }
     try {
-      const [sourceStrings, translationsMap, linkedSheet] = await Promise.all([
-        extractStringsForDoc(docId),
-        loadTranslations(),
-        cmsGetLinkedGoogleSheetL10n(docId),
-      ]);
-      setSourceStrings(sourceStrings);
+      const translationsMap = translationsDoc?.strings || {};
+      const sourceStrings = Object.values(translationsMap)
+        .map((item) => item.source)
+        .filter((item) => !!item);
+      setSourceStrings(Array.from(sourceStrings));
       setTranslationsMap(translationsMap);
-      setLinkedSheet(linkedSheet);
       setLoading(false);
     } catch (err) {
       console.error(err);
@@ -66,22 +54,14 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
 
   useEffect(() => {
     init();
-  }, []);
+  }, [translationsDoc.loading]);
 
   if (notFound) {
     return <DocTranslationsPage.NotFound docId={docId} />;
   }
 
-  function onChange(source: string, locale: string, translation: string) {
-    setHasChanges(true);
-    setChangesMap((current) => {
-      const newValue = {...current};
-      const translations = newValue[source] ?? {};
-      translations.source = source;
-      translations[locale] = translation;
-      newValue[source] = translations;
-      return newValue;
-    });
+  function onChange(locale: string, source: string, translation: string) {
+    translationsDoc.setTranslation(locale, source, translation);
   }
 
   async function onSave() {
@@ -97,17 +77,13 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
         autoClose: false,
         disallowClose: true,
       });
-      const changes: CsvTranslation[] = Object.values(changesMap);
-      console.log(changes);
-      await cmsDocImportTranslations(docId, changes);
+      await translationsDoc.saveTranslations();
       updateNotification({
         id: notificationId,
         title: 'Saved translations',
         message: `Updated translations for ${docId}!`,
         autoClose: true,
       });
-      setChangesMap({});
-      setHasChanges(false);
     });
     setSaving(false);
   }
@@ -116,50 +92,31 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
     <Layout>
       <div className="DocTranslationsPage">
         <div className="DocTranslationsPage__header">
-          <Breadcrumbs className="DocTranslationsPage__header__breadcrumbs">
-            <a href={`/cms/content/${collection}`}>{collection}</a>
-            <a href={`/cms/content/${collection}/${slug}`}>{slug}</a>
-            <div>translations</div>
-          </Breadcrumbs>
-          <div className="DocTranslationsPage__header__titleWrap">
-            <Heading size="h1">Translations: {docId}</Heading>
-          </div>
-          {linkedSheet && (
-            <div className="DocTranslationsPage__header__linkedSheet">
-              <div className="DocTranslationsPage__header__linkedSheet__label">
-                <strong>NOTE:</strong> Translations for this doc are managed in
-                Google Sheets.
-              </div>
-              <div className="DocTranslationsPage__header__linkedSheet__controls">
-                <Tooltip label="Open Google Sheet">
-                  <ActionIcon<'a'>
-                    component="a"
-                    href={getSpreadsheetUrl(linkedSheet)}
-                    target="_blank"
-                    variant="filled"
-                    color="green"
-                    size="sm"
-                  >
-                    <IconTable size={16} strokeWidth={2.25} />
-                  </ActionIcon>
-                </Tooltip>
-                <Button
-                  variant="default"
-                  size="xs"
-                  leftIcon={<IconFileUpload size={16} strokeWidth={1.75} />}
-                >
-                  Import from Sheet
-                </Button>
-                <Button
-                  variant="default"
-                  size="xs"
-                  leftIcon={<IconFileDownload size={16} strokeWidth={1.75} />}
-                >
-                  Export to Sheet
-                </Button>
-              </div>
+          <div className="DocTranslationsPage__header__content">
+            <Breadcrumbs className="DocTranslationsPage__header__breadcrumbs">
+              <a href={'/cms/translations'}>Translations</a>
+              <a href={`/cms/content/${collection}/${slug}`}>
+                {collection}/{slug}
+              </a>
+            </Breadcrumbs>
+            <div className="DocTranslationsPage__header__titleWrap">
+              <Heading size="h2">Translations: {docId}</Heading>
             </div>
-          )}
+            {linkedSheet && (
+              <div className="DocTranslationsPage__header__linkedSheet">
+                <strong>NOTE:</strong> Translations for this doc are managed in{' '}
+                <a href={getSpreadsheetUrl(linkedSheet)} target="_blank">
+                  Google Sheets
+                </a>
+                .
+              </div>
+            )}
+          </div>
+          <div className="DocTranslationsPage__header__controls">
+            <TranslationsImportExportButtons
+              translationsDoc={translationsDoc}
+            />
+          </div>
         </div>
 
         <div
@@ -176,7 +133,7 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
               sourceStrings={sourceStrings}
               translationsMap={translationsMap}
               onChange={onChange}
-              changesMap={changesMap}
+              pendingChanges={translationsDoc.pendingChanges}
             />
           )}
         </div>
@@ -186,7 +143,7 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
             <Button
               variant="filled"
               color="dark"
-              disabled={!hasChanges}
+              disabled={!translationsDoc.hasPendingChanges}
               loading={saving}
               onClick={() => onSave()}
             >
@@ -220,18 +177,16 @@ interface DocTranslationsPageTableProps {
   locales: string[];
   sourceStrings: string[];
   translationsMap: TranslationsMap;
-  onChange: (source: string, locale: string, translation: string) => void;
-  changesMap: Record<string, Translation>;
+  onChange: (locale: string, source: string, translation: string) => void;
+  pendingChanges: TranslationsMap;
 }
 
 DocTranslationsPage.Table = (props: DocTranslationsPageTableProps) => {
   const sourceToTranslationsMap = useMemo(() => {
     const results: {[source: string]: Record<string, string>} = {};
-    Object.values(props.translationsMap).forEach(
-      (row: Record<string, string>) => {
-        results[row.source] = row;
-      }
-    );
+    Object.entries(props.translationsMap).forEach(([hash, row]) => {
+      results[row.source] = {...row, hash};
+    });
     return results;
   }, [props.translationsMap]);
 
@@ -239,6 +194,7 @@ DocTranslationsPage.Table = (props: DocTranslationsPageTableProps) => {
     const sourceTranslations = sourceToTranslationsMap[source] || {};
     const translation = sourceTranslations[locale] || '';
     return {
+      hash: sourceTranslations.hash,
       translation: translation,
       hasChanges: false,
     };
@@ -272,7 +228,7 @@ DocTranslationsPage.Table = (props: DocTranslationsPageTableProps) => {
                       locale={locale}
                       value={data.translation}
                       onChange={props.onChange}
-                      changesMap={props.changesMap}
+                      changesMap={props.pendingChanges}
                     />
                   </td>
                 );
@@ -289,8 +245,8 @@ DocTranslationsPage.Textarea = (props: {
   value: string;
   source: string;
   locale: string;
-  onChange: (source: string, locale: string, translation: string) => void;
-  changesMap: Record<string, Translation>;
+  onChange: (locale: string, source: string, translation: string) => void;
+  changesMap: TranslationsMap;
 }) => {
   const textInputRef = useRef<HTMLTextAreaElement>(null);
   const [value, setValue] = useState(props.value);
@@ -328,7 +284,7 @@ DocTranslationsPage.Textarea = (props: {
       onChange={(e) => {
         const newValue = (e.target as HTMLTextAreaElement).value;
         setValue(newValue);
-        props.onChange(props.source, props.locale, newValue);
+        props.onChange(props.locale, props.source, newValue);
       }}
       value={value}
     ></textarea>
diff --git a/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.css b/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.css
index 71c2b90f..efbf179a 100644
--- a/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.css
+++ b/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.css
@@ -11,14 +11,16 @@
 }
 
 .TranslationsPage__TranslationsTable {
-  width: 100%;
+  display: inline-block;
+  width: auto;
+  max-width: 100%;
   overflow: auto;
 }
 
-.TranslationsPage__TranslationsTable td[data-col="hash"] {
-  max-width: 80px;
-  overflow: hidden;
-  text-overflow: ellipsis;
+.TranslationsPage__TranslationsTable__idCell {
+  display: flex;
+  gap: 4px;
+  align-items: center;
 }
 
 .TranslationsPage__TranslationsTable td[data-string-cell="true"] {
diff --git a/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.tsx b/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.tsx
index 29d9a0d6..c823408b 100644
--- a/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.tsx
+++ b/packages/root-cms/ui/pages/TranslationsPage/TranslationsPage.tsx
@@ -1,9 +1,15 @@
 import {Button, Loader, Table} from '@mantine/core';
+import {IconFile} from '@tabler/icons-preact';
 import {useEffect, useState} from 'preact/hooks';
 import {Heading} from '../../components/Heading/Heading.js';
+import {TranslationsStatusBadges} from '../../components/TranslationsStatusBadges/TranslationsStatusBadges.js';
+import {
+  dbListTranslationsDocs,
+  TranslationsDoc,
+} from '../../db/translations.js';
 import {Layout} from '../../layout/Layout.js';
-import {loadTranslations} from '../../utils/l10n.js';
 import {notifyErrors} from '../../utils/notifications.js';
+import {timeDiff} from '../../utils/time.js';
 import './TranslationsPage.css';
 
 export function TranslationsPage() {
@@ -31,39 +37,16 @@ export function TranslationsPage() {
 
 TranslationsPage.TranslationsTable = () => {
   const [loading, setLoading] = useState(true);
-  const [tableData, setTableData] = useState<string[][]>([]);
-  const locales = window.__ROOT_CTX.rootConfig.i18n?.locales || [];
-  const nonEnLocales = locales.filter((l) => l !== 'en');
-  const headers = ['hash', 'source', 'en', ...nonEnLocales, 'tags'];
+  const [translationsDocs, setTranslationsDocs] = useState<TranslationsDoc[]>(
+    []
+  );
+  const headers = ['id', 'status', 'last update'];
 
   async function init() {
     setLoading(true);
     await notifyErrors(async () => {
-      const translationsMap = await loadTranslations();
-      const tableData: any[] = [];
-      Object.entries(translationsMap).forEach(([hash, translations]) => {
-        const nonEnValues = nonEnLocales.map(
-          (locale) => translations[locale] || ''
-        );
-        tableData.push([
-          hash,
-          translations.source,
-          translations.en,
-          ...nonEnValues,
-          ((translations.tags as any as string[]) || []).join('\n'),
-        ]);
-      });
-      // Sort by the source string.
-      tableData.sort((a: string[], b: string[]) => {
-        if (a[1].toLowerCase() < b[1].toLowerCase()) {
-          return -1;
-        }
-        if (a[1].toLowerCase() > b[1].toLowerCase()) {
-          return 1;
-        }
-        return 0;
-      });
-      setTableData(tableData);
+      const translationsDocs = await dbListTranslationsDocs();
+      setTranslationsDocs(translationsDocs);
     });
     setLoading(false);
   }
@@ -76,7 +59,7 @@ TranslationsPage.TranslationsTable = () => {
     return <Loader color="gray" size="xl" />;
   }
 
-  if (tableData.length === 0) {
+  if (translationsDocs.length === 0) {
     return (
       <div className="TranslationsPage__TranslationsTable">
         <div className="TranslationsPage__TranslationsTable__empty">
@@ -86,6 +69,17 @@ TranslationsPage.TranslationsTable = () => {
     );
   }
 
+  function modifiedAtString(translationsDoc: TranslationsDoc) {
+    const sys = translationsDoc.sys;
+    if (
+      sys.publishedAt &&
+      sys.publishedAt.toMillis() >= sys.modifiedAt.toMillis()
+    ) {
+      return `published ${timeDiff(sys.publishedAt)} by ${sys.publishedBy}`;
+    }
+    return `updated ${timeDiff(sys.modifiedAt)} by ${sys.modifiedBy}`;
+  }
+
   return (
     <div className="TranslationsPage__TranslationsTable">
       <Table verticalSpacing="xs" striped highlightOnHover fontSize="xs">
@@ -97,20 +91,20 @@ TranslationsPage.TranslationsTable = () => {
           </tr>
         </thead>
         <tbody>
-          {tableData.map((cells) => (
-            <tr key={cells[0]}>
-              {cells.map((cell, colIndex) => (
-                <td
-                  data-col={headers[colIndex]}
-                  data-string-cell={![0, headers.length - 1].includes(colIndex)}
-                >
-                  {colIndex === 0 ? (
-                    <a href={`/cms/translations/${cell}`}>{cell}</a>
-                  ) : (
-                    cell
-                  )}
-                </td>
-              ))}
+          {translationsDocs.map((translationsDoc) => (
+            <tr key={translationsDoc.id}>
+              <td>
+                <div className="TranslationsPage__TranslationsTable__idCell">
+                  <IconFile width={20} strokeWidth={1.5} />
+                  <a href={`/cms/translations/${translationsDoc.id}`}>
+                    {translationsDoc.id}
+                  </a>
+                </div>
+              </td>
+              <td>
+                <TranslationsStatusBadges translationsDoc={translationsDoc} />
+              </td>
+              <td>{modifiedAtString(translationsDoc)}</td>
             </tr>
           ))}
         </tbody>
diff --git a/packages/root-cms/ui/utils/doc.ts b/packages/root-cms/ui/utils/doc.ts
index 0c133dd2..7e02fa09 100644
--- a/packages/root-cms/ui/utils/doc.ts
+++ b/packages/root-cms/ui/utils/doc.ts
@@ -7,7 +7,6 @@ import {
   Timestamp,
   deleteField,
   writeBatch,
-  arrayUnion,
   collection,
   query,
   orderBy,
@@ -21,11 +20,8 @@ import {
 import {logAction} from './actions.js';
 import {removeDocFromCache, removeDocsFromCache} from './doc-cache.js';
 import {GoogleSheetId} from './gsheets.js';
-import {
-  getTranslationsCollection,
-  normalizeString,
-  sourceHash,
-} from './l10n.js';
+import {normalizeString, sourceHash, TranslationsMap} from './l10n.js';
+import {TranslationsDoc} from './translations.js';
 
 export interface CMSDoc {
   id: string;
@@ -139,6 +135,7 @@ export async function cmsPublishDocs(
       throw new Error(`doc does not exist: ${docId}`);
     }
     updatePublishedDocDataInBatch(batch, docId, draftData);
+    cmsPublishTranslationsDoc(docId, {batch});
   });
   await batch.commit();
 
@@ -510,8 +507,7 @@ export interface CsvTranslation {
 
 export async function cmsDocImportTranslations(
   docId: string,
-  csvData: CsvTranslation[],
-  options?: {tags?: string[]}
+  csvData: CsvTranslation[]
 ) {
   const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
   const i18nLocales = i18nConfig.locales || ['en'];
@@ -548,45 +544,8 @@ export async function cmsDocImportTranslations(
     translationsMap[hash] = translation;
   }
 
-  // Tags are stored as key-value pairs so that we can call updateDoc() without
-  // having to read the actual document.
-  const collectionId = docId.split('/')[0];
-  const tags = [collectionId, docId];
-  if (options?.tags) {
-    tags.push(...options.tags);
-  }
-
-  // Save each string to `Projects/<project>/Translations/<hash>` in a batch
-  // request. Note: Firestore batches have limit of 500 writes.
-  const translationsCollection = getTranslationsCollection();
-  const db = window.firebase.db;
-  let batch = writeBatch(db);
-  let count = 0;
-  for (const hash in translationsMap) {
-    const translations = translationsMap[hash];
-    const stringDocRef = doc(translationsCollection, hash);
-    batch.set(
-      stringDocRef,
-      {
-        ...translations,
-        // Use arrayUnion to only add tags that don't already exist.
-        tags: arrayUnion(...tags),
-      },
-      {merge: true}
-    );
-    count += 1;
-    if (count >= 500) {
-      await batch.commit();
-      batch = writeBatch(db);
-      console.log(`saved ${count} strings`);
-      count = 0;
-    }
-  }
-  if (count > 0) {
-    await batch.commit();
-    console.log(`saved ${count} strings`);
-  }
-  logAction('doc.import_translations', {metadata: {docId}});
+  const translationsId = docId;
+  await cmsSaveTranslations(translationsId, translationsMap);
   return translationsMap;
 }
 
diff --git a/packages/root-cms/ui/utils/time.ts b/packages/root-cms/ui/utils/time.ts
index afa1f32f..82bfb727 100644
--- a/packages/root-cms/ui/utils/time.ts
+++ b/packages/root-cms/ui/utils/time.ts
@@ -1,3 +1,5 @@
+import {Timestamp} from 'firebase/firestore';
+
 /**
  * Converts a time unit to millis.
  */
@@ -56,3 +58,13 @@ export function formatDateTime(ts: Timestamp) {
     minute: '2-digit',
   });
 }
+
+export function timeDiff(ts: Timestamp | null) {
+  // Since we're using server timestamps, firestore doesn't always return the
+  // timestamp right away since the db save is happening asynchronously. In
+  // these cases, assume that the update happened very recently.
+  if (!ts) {
+    return getTimeAgo(new Date().getTime());
+  }
+  return getTimeAgo(ts.toMillis());
+}

From b001bdbc6d149d28c26fe64ee13b141f8f4d0c59 Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Sun, 13 Oct 2024 12:58:37 -0400
Subject: [PATCH 05/14] chore: [v2] code cleanup (#432)

---
 docs/layouts/base.tsx                         |   3 +-
 docs/root-cms.d.ts                            |   2 +-
 packages/eslint-config-root/index.js          |  12 +
 .../ui/components/ActionLogs/ActionLogs.tsx   |  31 +-
 .../AssetUploader/AssetUploader.tsx           |  48 ++-
 .../components/CopyDocModal/CopyDocModal.tsx  |  13 +-
 .../DataSourceForm/DataSourceForm.tsx         |  10 +-
 .../DataSourceStatusButton.tsx                |   6 +-
 .../DocActionsMenu/DocActionsMenu.tsx         |  28 +-
 .../DocDiffViewer/DocDiffViewer.tsx           |  14 +-
 .../ui/components/DocEditor/DocEditor.tsx     |  47 +--
 .../DocEditor/fields/BooleanField.tsx         |   2 +-
 .../components/DocEditor/fields/FieldProps.ts |   4 +-
 .../components/DocEditor/fields/FileField.tsx |   6 +-
 .../DocEditor/fields/ImageField.tsx           |   6 +-
 .../DocEditor/fields/MultiSelectField.tsx     |   2 +-
 .../DocEditor/fields/ReferenceField.tsx       |  10 +-
 .../DocEditor/fields/RichTextField.tsx        |   6 +-
 .../DocEditor/fields/SelectField.tsx          |   2 +-
 .../DocEditor/fields/StringField.tsx          |   2 +-
 .../DocPickerModal/DocPickerModal.tsx         |   8 +-
 .../DocPreviewCard/DocPreviewCard.tsx         |  12 +-
 .../DocSelectModal/DocSelectModal.tsx         |   8 +-
 .../DocStatusBadges/DocStatusBadges.tsx       |   4 +-
 .../EditJsonModal/EditJsonModal.tsx           |   2 +-
 .../EditTranslationsModal.tsx                 |  12 +-
 .../ExportSheetModal/ExportSheetModal.tsx     |  28 +-
 .../ui/components/Heading/Heading.tsx         |   3 +-
 .../LocalizationModal/LocalizationModal.tsx   | 332 +-----------------
 .../LockPublishingModal.tsx                   |  14 +-
 .../ui/components/Markdown/Markdown.tsx       |   5 +-
 .../ui/components/NewDocModal/NewDocModal.tsx |   9 +-
 .../PublishDocModal/PublishDocModal.tsx       |  14 +-
 .../ui/components/ReleaseForm/ReleaseForm.tsx |  15 +-
 .../ReleaseStatusBadge/ReleaseStatusBadge.tsx |   4 +-
 .../RichTextEditor/RichTextEditor.tsx         |   8 +-
 .../ScheduleReleaseModal.tsx                  |   6 +-
 .../ui/components/ShareBox/ShareBox.tsx       |  10 +-
 .../ui/components/SlugInput/SlugInput.tsx     |   8 +-
 .../ui/components/SplitPanel/SplitPanel.tsx   |   5 +-
 packages/root-cms/ui/components/Text/Text.tsx |   3 +-
 .../TimeSinceActionTooltip.tsx                |   2 +-
 .../TranslationsImportExportButtons.tsx       |  42 +--
 .../TranslationsStatusBadges.tsx              |   4 +-
 .../VersionHistoryModal.tsx                   |  22 +-
 .../ui/components/Viewers/Viewers.tsx         |  12 +-
 packages/root-cms/ui/{utils => db}/actions.ts |   3 +-
 .../data-source.ts => db/data-sources.ts}     |   2 +-
 .../root-cms/ui/{utils/doc.ts => db/docs.ts}  | 185 +++-------
 .../ui/{utils/release.ts => db/releases.ts}   |   4 +-
 packages/root-cms/ui/db/translations.ts       |  49 ++-
 packages/root-cms/ui/{utils => db}/users.ts   |   0
 packages/root-cms/ui/db/versions.ts           |  88 +++++
 packages/root-cms/ui/hooks/useDocsList.ts     |   4 +-
 packages/root-cms/ui/hooks/useDraft.ts        |  12 +-
 .../root-cms/ui/hooks/useTranslationsDoc.ts   |  10 +-
 packages/root-cms/ui/layout/Layout.tsx        |   6 +-
 .../root-cms/ui/pages/DataPage/DataPage.tsx   |   2 +-
 .../pages/DataSourcePage/DataSourcePage.tsx   |   4 +-
 .../EditDataSourcePage/EditDataSourcePage.tsx |   2 +-
 .../pages/EditReleasePage/EditReleasePage.tsx |   2 +-
 .../ui/pages/ReleasePage/ReleasePage.tsx      |   8 +-
 .../ui/pages/ReleasesPage/ReleasesPage.tsx    |   2 +-
 .../TranslationsArbPage.tsx                   |  14 +-
 packages/root-cms/ui/tsconfig.json            |   5 +-
 packages/root-cms/ui/utils/doc-cache.ts       |   2 +-
 packages/root-cms/ui/utils/extract.ts         |   4 +-
 packages/root-cms/ui/utils/gsheets.ts         |   2 +-
 packages/root-cms/ui/utils/l10n.ts            |   2 +-
 packages/root-cms/ui/utils/objects.ts         |  26 ++
 70 files changed, 487 insertions(+), 797 deletions(-)
 rename packages/root-cms/ui/{utils => db}/actions.ts (96%)
 rename packages/root-cms/ui/{utils/data-source.ts => db/data-sources.ts} (99%)
 rename packages/root-cms/ui/{utils/doc.ts => db/docs.ts} (80%)
 rename packages/root-cms/ui/{utils/release.ts => db/releases.ts} (98%)
 rename packages/root-cms/ui/{utils => db}/users.ts (100%)
 create mode 100644 packages/root-cms/ui/db/versions.ts

diff --git a/docs/layouts/base.tsx b/docs/layouts/base.tsx
index ad29fce1..0cd4cd8b 100644
--- a/docs/layouts/base.tsx
+++ b/docs/layouts/base.tsx
@@ -1,6 +1,7 @@
+/* eslint-disable import/order */
+
 import {Head} from '@blinkk/root';
 import {ComponentChildren} from 'preact';
-
 import {GlobalFooter} from '@/templates/global-footer/global-footer.js';
 import {GlobalHeader} from '@/templates/global-header/global-header.js';
 import '@/styles/global.scss';
diff --git a/docs/root-cms.d.ts b/docs/root-cms.d.ts
index 47b64cf8..3ebc3ace 100644
--- a/docs/root-cms.d.ts
+++ b/docs/root-cms.d.ts
@@ -350,4 +350,4 @@ export interface TemplatePoweredByFields {
   }[];
   /** Body copy */
   body?: RootCMSRichText;
-}
\ No newline at end of file
+}
diff --git a/packages/eslint-config-root/index.js b/packages/eslint-config-root/index.js
index 37bf0f2d..5a5423c4 100644
--- a/packages/eslint-config-root/index.js
+++ b/packages/eslint-config-root/index.js
@@ -57,14 +57,26 @@ module.exports = {
               'parent',
               'sibling',
               'index',
+              'unknown',
             ],
             pathGroups: [
               {
                 pattern: '@/**',
                 group: 'internal',
               },
+              {
+                pattern: '**/*.{css,scss}',
+                group: 'unknown',
+              },
+              {
+                pattern: '*.{css,scss}',
+                group: 'unknown',
+                patternOptions: {matchBase: true},
+                position: 'after',
+              },
             ],
             pathGroupsExcludedImportTypes: ['builtin'],
+            warnOnUnassignedImports: true,
             'newlines-between': 'ignore',
             alphabetize: {
               order: 'asc',
diff --git a/packages/root-cms/ui/components/ActionLogs/ActionLogs.tsx b/packages/root-cms/ui/components/ActionLogs/ActionLogs.tsx
index 4900b668..1bb84eb4 100644
--- a/packages/root-cms/ui/components/ActionLogs/ActionLogs.tsx
+++ b/packages/root-cms/ui/components/ActionLogs/ActionLogs.tsx
@@ -1,9 +1,10 @@
 import {Button, Loader, Table, Tooltip} from '@mantine/core';
 import {Timestamp} from 'firebase/firestore';
 import {useEffect, useState} from 'preact/hooks';
-import {Action, listActions} from '../../utils/actions.js';
+import {Action, listActions} from '@/db/actions.js';
+import {getSpreadsheetUrl} from '@/utils/gsheets.js';
+import {stringifyObj} from '@/utils/objects.js';
 import './ActionsLogs.css';
-import {getSpreadsheetUrl} from '../../utils/gsheets.js';
 
 export interface ActionLogsProps {
   className?: string;
@@ -145,29 +146,3 @@ function formatDate(timestamp: Timestamp) {
     timeStyle: 'medium',
   });
 }
-
-/** A pretty printer for JavaScript objects. */
-function stringifyObj(obj: any) {
-  function format(obj: any): string {
-    if (obj === null) {
-      return 'null';
-    }
-    if (typeof obj === 'undefined') {
-      return 'undefined';
-    }
-    if (typeof obj === 'string') {
-      return `"${obj.replaceAll('"', '\\"')}"`;
-    }
-    if (typeof obj !== 'object') {
-      return String(obj);
-    }
-    if (Array.isArray(obj)) {
-      return `[${obj.map(format).join(', ')}]`;
-    }
-    const entries: string[] = Object.entries(obj).map(([key, value]) => {
-      return `${key}: ${format(value)}`;
-    });
-    return `{${entries.join(', ')}}`;
-  }
-  return format(obj);
-}
diff --git a/packages/root-cms/ui/components/AssetUploader/AssetUploader.tsx b/packages/root-cms/ui/components/AssetUploader/AssetUploader.tsx
index a7d8e26e..9b427ac9 100644
--- a/packages/root-cms/ui/components/AssetUploader/AssetUploader.tsx
+++ b/packages/root-cms/ui/components/AssetUploader/AssetUploader.tsx
@@ -2,9 +2,9 @@ import {TextInput} from '@mantine/core';
 import {showNotification} from '@mantine/notifications';
 import {IconFileUpload} from '@tabler/icons-preact';
 import {useEffect, useRef, useState} from 'preact/hooks';
-import {Text} from '../../components/Text/Text.js';
-import {joinClassNames} from '../../utils/classes.js';
-import {UploadFileOptions, uploadFileToGCS} from '../../utils/gcs.js';
+import {Text} from '@/components/Text/Text.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {UploadFileOptions, uploadFileToGCS} from '@/utils/gcs.js';
 import './AssetUploader.css';
 
 export const IMAGE_MIMETYPES = [
@@ -62,30 +62,29 @@ export function AssetUploader(props: AssetUploaderProps) {
     }
   }
 
-  const handleDragEnter = (e: DragEvent) => {
-    e.preventDefault();
-    setIsDragging(true);
-  };
+  useEffect(() => {
+    const dropzone = ref.current;
+    const handleDragEnter = (e: DragEvent) => {
+      e.preventDefault();
+      setIsDragging(true);
+    };
 
-  const handleDragLeave = (e: DragEvent) => {
-    e.preventDefault();
-    setIsDragging(false);
-  };
+    const handleDragLeave = (e: DragEvent) => {
+      e.preventDefault();
+      setIsDragging(false);
+    };
 
-  const handleDrop = (e: DragEvent) => {
-    e.preventDefault();
-    setIsDragging(false);
+    const handleDrop = (e: DragEvent) => {
+      e.preventDefault();
+      setIsDragging(false);
 
-    const files = e.dataTransfer?.files || [];
-    const file = files[0];
-    if (file) {
-      console.log('file dropped:', file);
-      uploadFile(file);
-    }
-  };
-
-  useEffect(() => {
-    const dropzone = ref.current;
+      const files = e.dataTransfer?.files || [];
+      const file = files[0];
+      if (file) {
+        console.log('file dropped:', file);
+        uploadFile(file);
+      }
+    };
     document.addEventListener('dragenter', handleDragEnter);
     document.addEventListener('dragover', handleDragEnter);
     document.addEventListener('dragleave', handleDragLeave);
@@ -160,7 +159,6 @@ AssetUploader.FilePreview = (props: {asset: any}) => {
 
 AssetUploader.ImagePreview = (props: {asset: any}) => {
   const asset = props.asset;
-  console.log(asset);
   return (
     <div className="AssetUploader__ImagePreview">
       <div className="AssetUploader__ImagePreview__image">
diff --git a/packages/root-cms/ui/components/CopyDocModal/CopyDocModal.tsx b/packages/root-cms/ui/components/CopyDocModal/CopyDocModal.tsx
index d96aead6..b3a903fc 100644
--- a/packages/root-cms/ui/components/CopyDocModal/CopyDocModal.tsx
+++ b/packages/root-cms/ui/components/CopyDocModal/CopyDocModal.tsx
@@ -3,11 +3,12 @@ import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification} from '@mantine/notifications';
 import {useState} from 'preact/hooks';
 import {route} from 'preact-router';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {cmsCopyDoc} from '../../utils/doc.js';
-import {isSlugValid, normalizeSlug} from '../../utils/slug.js';
-import {SlugInput} from '../SlugInput/SlugInput.js';
-import {Text} from '../Text/Text.js';
+import {SlugInput} from '@/components/SlugInput/SlugInput.js';
+import {Text} from '@/components/Text/Text.js';
+import {dbCopyDoc} from '@/db/docs.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {isSlugValid, normalizeSlug} from '@/utils/slug.js';
+
 import './CopyDocModal.css';
 
 const MODAL_ID = 'CopyDocModal';
@@ -60,7 +61,7 @@ export function CopyDocModal(modalProps: ContextModalProps<CopyDocModalProps>) {
 
     const toDocId = `${toCollectionId}/${cleanSlug}`;
     try {
-      await cmsCopyDoc(fromDocId, toDocId, {overwrite: confirmOverwrite});
+      await dbCopyDoc(fromDocId, toDocId, {overwrite: confirmOverwrite});
       context.closeModal(id);
       showNotification({
         title: 'Copied!',
diff --git a/packages/root-cms/ui/components/DataSourceForm/DataSourceForm.tsx b/packages/root-cms/ui/components/DataSourceForm/DataSourceForm.tsx
index e63964e8..72c35dc6 100644
--- a/packages/root-cms/ui/components/DataSourceForm/DataSourceForm.tsx
+++ b/packages/root-cms/ui/components/DataSourceForm/DataSourceForm.tsx
@@ -8,7 +8,6 @@ import {
 import {showNotification} from '@mantine/notifications';
 import {useEffect, useRef, useState} from 'preact/hooks';
 import {route} from 'preact-router';
-import {useGapiClient} from '../../hooks/useGapiClient.js';
 import {
   DataSource,
   DataSourceType,
@@ -17,10 +16,11 @@ import {
   addDataSource,
   getDataSource,
   updateDataSource,
-} from '../../utils/data-source.js';
-import {parseSpreadsheetUrl} from '../../utils/gsheets.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {isSlugValid} from '../../utils/slug.js';
+} from '@/db/data-sources.js';
+import {useGapiClient} from '@/hooks/useGapiClient.js';
+import {parseSpreadsheetUrl} from '@/utils/gsheets.js';
+import {notifyErrors} from '@/utils/notifications.js';
+import {isSlugValid} from '@/utils/slug.js';
 import './DataSourceForm.css';
 
 const HTTP_URL_HELP = 'Enter the URL to make the HTTP request.';
diff --git a/packages/root-cms/ui/components/DataSourceStatusButton/DataSourceStatusButton.tsx b/packages/root-cms/ui/components/DataSourceStatusButton/DataSourceStatusButton.tsx
index 4f347137..369d9928 100644
--- a/packages/root-cms/ui/components/DataSourceStatusButton/DataSourceStatusButton.tsx
+++ b/packages/root-cms/ui/components/DataSourceStatusButton/DataSourceStatusButton.tsx
@@ -2,13 +2,13 @@ import {Button, Tooltip} from '@mantine/core';
 import {showNotification, updateNotification} from '@mantine/notifications';
 import {Timestamp} from 'firebase/firestore';
 import {useState} from 'preact/hooks';
-import {useGapiClient} from '../../hooks/useGapiClient.js';
+import {TimeSinceActionTooltip} from '@/components/TimeSinceActionTooltip/TimeSinceActionTooltip.js';
 import {
   DataSource,
   publishDataSource,
   syncDataSource,
-} from '../../utils/data-source.js';
-import {TimeSinceActionTooltip} from '../TimeSinceActionTooltip/TimeSinceActionTooltip.js';
+} from '@/db/data-sources.js';
+import {useGapiClient} from '@/hooks/useGapiClient.js';
 import './DataSourceStatusButton.css';
 
 export interface DataSourceStatusButtonProps {
diff --git a/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx b/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx
index c9487df2..8e4a9a87 100644
--- a/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx
+++ b/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx
@@ -12,20 +12,20 @@ import {
   IconLockOpen,
   IconTrash,
 } from '@tabler/icons-preact';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
+import {useCopyDocModal} from '@/components/CopyDocModal/CopyDocModal.js';
+import {useLockPublishingModal} from '@/components/LockPublishingModal/LockPublishingModal.js';
+import {Text} from '@/components/Text/Text.js';
+import {useVersionHistoryModal} from '@/components/VersionHistoryModal/VersionHistoryModal.js';
 import {
   CMSDoc,
-  cmsDeleteDoc,
-  cmsRevertDraft,
-  cmsUnpublishDoc,
-  cmsUnscheduleDoc,
+  dbDeleteDoc,
+  dbRevertDraft,
+  dbUnpublishDoc,
+  dbUnscheduleDoc,
   testIsScheduled,
   testPublishingLocked,
-} from '../../utils/doc.js';
-import {useCopyDocModal} from '../CopyDocModal/CopyDocModal.js';
-import {useLockPublishingModal} from '../LockPublishingModal/LockPublishingModal.js';
-import {Text} from '../Text/Text.js';
-import {useVersionHistoryModal} from '../VersionHistoryModal/VersionHistoryModal.js';
+} from '@/db/docs.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
 
 export interface DocActionEvent {
   action: 'copy' | 'delete' | 'revert-draft' | 'unpublish' | 'unschedule';
@@ -74,7 +74,7 @@ export function DocActionsMenu(props: DocActionsMenuProps) {
           loading: true,
           autoClose: false,
         });
-        await cmsRevertDraft(docId);
+        await dbRevertDraft(docId);
         updateNotification({
           id: notificationId,
           title: 'Discarded draft edited',
@@ -116,7 +116,7 @@ export function DocActionsMenu(props: DocActionsMenuProps) {
           loading: true,
           autoClose: false,
         });
-        await cmsUnpublishDoc(docId);
+        await dbUnpublishDoc(docId);
         updateNotification({
           id: notificationId,
           title: 'Unpublished!',
@@ -157,7 +157,7 @@ export function DocActionsMenu(props: DocActionsMenuProps) {
           loading: true,
           autoClose: false,
         });
-        await cmsUnscheduleDoc(docId);
+        await dbUnscheduleDoc(docId);
         updateNotification({
           id: notificationId,
           title: 'Unscheduled!',
@@ -199,7 +199,7 @@ export function DocActionsMenu(props: DocActionsMenuProps) {
           loading: true,
           autoClose: false,
         });
-        await cmsDeleteDoc(docId);
+        await dbDeleteDoc(docId);
         updateNotification({
           id: notificationId,
           title: 'Deleted!',
diff --git a/packages/root-cms/ui/components/DocDiffViewer/DocDiffViewer.tsx b/packages/root-cms/ui/components/DocDiffViewer/DocDiffViewer.tsx
index dd3de927..235eced3 100644
--- a/packages/root-cms/ui/components/DocDiffViewer/DocDiffViewer.tsx
+++ b/packages/root-cms/ui/components/DocDiffViewer/DocDiffViewer.tsx
@@ -1,13 +1,13 @@
 import {Button, Loader} from '@mantine/core';
 import {Differ, Viewer as JsonDiffViewer} from 'json-diff-kit';
 import {useEffect, useState} from 'preact/hooks';
-import {CMSDoc, cmsReadDocVersion, unmarshalData} from '../../utils/doc.js';
-
-import 'json-diff-kit/dist/viewer.css';
+import {CMSDoc, unmarshalData} from '@/db/docs.js';
+import {dbGetDocVersion} from '@/db/versions.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {getTimeAgo} from '@/utils/time.js';
 import 'json-diff-kit/dist/viewer-monokai.css';
+import 'json-diff-kit/dist/viewer.css';
 import './DocDiffViewer.css';
-import {getTimeAgo} from '../../utils/time.js';
-import {joinClassNames} from '../../utils/classes.js';
 
 export interface DocVersionId {
   /** Doc id, e.g. `Pages/foo`. */
@@ -44,8 +44,8 @@ export function DocDiffViewer(props: DocDiffViewerProps) {
   async function init() {
     setLoading(true);
     const [leftDoc, rightDoc] = await Promise.all([
-      cmsReadDocVersion(left.docId, left.versionId),
-      cmsReadDocVersion(right.docId, right.versionId),
+      dbGetDocVersion(left.docId, left.versionId),
+      dbGetDocVersion(right.docId, right.versionId),
     ]);
     setLeftDoc(leftDoc);
     setRightDoc(rightDoc);
diff --git a/packages/root-cms/ui/components/DocEditor/DocEditor.tsx b/packages/root-cms/ui/components/DocEditor/DocEditor.tsx
index 09ddce14..250bdf40 100644
--- a/packages/root-cms/ui/components/DocEditor/DocEditor.tsx
+++ b/packages/root-cms/ui/components/DocEditor/DocEditor.tsx
@@ -23,6 +23,7 @@ import {
   IconTrash,
   IconTriangleFilled,
 } from '@tabler/icons-preact';
+import {createContext} from 'preact';
 import {
   useContext,
   useEffect,
@@ -32,35 +33,25 @@ import {
   useState,
 } from 'preact/hooks';
 import {route} from 'preact-router';
-
-import * as schema from '../../../core/schema.js';
-import {
-  DraftController,
-  SaveState,
-  UseDraftHook,
-} from '../../hooks/useDraft.js';
-import {joinClassNames} from '../../utils/classes.js';
-import {
-  CMSDoc,
-  testIsScheduled,
-  testPublishingLocked,
-} from '../../utils/doc.js';
-import {extractField} from '../../utils/extract.js';
-import {getDefaultFieldValue} from '../../utils/fields.js';
-import {flattenNestedKeys} from '../../utils/objects.js';
-import {autokey} from '../../utils/rand.js';
-import {getPlaceholderKeys, strFormat} from '../../utils/str-format.js';
-import {formatDateTime} from '../../utils/time.js';
 import {
   DocActionEvent,
   DocActionsMenu,
-} from '../DocActionsMenu/DocActionsMenu.js';
-import {DocStatusBadges} from '../DocStatusBadges/DocStatusBadges.js';
-import {useEditJsonModal} from '../EditJsonModal/EditJsonModal.js';
-import {useLocalizationModal} from '../LocalizationModal/LocalizationModal.js';
-import {usePublishDocModal} from '../PublishDocModal/PublishDocModal.js';
-import './DocEditor.css';
-import {Viewers} from '../Viewers/Viewers.js';
+} from '@/components/DocActionsMenu/DocActionsMenu.js';
+import {DocStatusBadges} from '@/components/DocStatusBadges/DocStatusBadges.js';
+import {useEditJsonModal} from '@/components/EditJsonModal/EditJsonModal.js';
+import {useEditTranslationsModal} from '@/components/EditTranslationsModal/EditTranslationsModal.js';
+import {useLocalizationModal} from '@/components/LocalizationModal/LocalizationModal.js';
+import {usePublishDocModal} from '@/components/PublishDocModal/PublishDocModal.js';
+import {Viewers} from '@/components/Viewers/Viewers.js';
+import {CMSDoc, testIsScheduled, testPublishingLocked} from '@/db/docs.js';
+import {DraftController, SaveState, UseDraftHook} from '@/hooks/useDraft.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {extractField} from '@/utils/extract.js';
+import {getDefaultFieldValue} from '@/utils/fields.js';
+import {flattenNestedKeys} from '@/utils/objects.js';
+import {autokey} from '@/utils/rand.js';
+import {getPlaceholderKeys, strFormat} from '@/utils/str-format.js';
+import {formatDateTime} from '@/utils/time.js';
 import {BooleanField} from './fields/BooleanField.js';
 import {DateTimeField} from './fields/DateTimeField.js';
 import {FieldProps} from './fields/FieldProps.js';
@@ -71,8 +62,8 @@ import {ReferenceField} from './fields/ReferenceField.js';
 import {RichTextField} from './fields/RichTextField.js';
 import {SelectField} from './fields/SelectField.js';
 import {StringField} from './fields/StringField.js';
-import {createContext} from 'preact';
-import {useEditTranslationsModal} from '../EditTranslationsModal/EditTranslationsModal.js';
+import * as schema from '@/../core/schema.js';
+import './DocEditor.css';
 
 interface DocEditorProps {
   docId: string;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/BooleanField.tsx b/packages/root-cms/ui/components/DocEditor/fields/BooleanField.tsx
index b99e57ca..7f351de5 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/BooleanField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/BooleanField.tsx
@@ -1,7 +1,7 @@
 import {Checkbox} from '@mantine/core';
 import {useEffect, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export function BooleanField(props: FieldProps) {
   const field = props.field as schema.BooleanField;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/FieldProps.ts b/packages/root-cms/ui/components/DocEditor/fields/FieldProps.ts
index 9426ec1b..18f4ad18 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/FieldProps.ts
+++ b/packages/root-cms/ui/components/DocEditor/fields/FieldProps.ts
@@ -1,5 +1,5 @@
-import * as schema from '../../../../core/schema.js';
-import {DraftController} from '../../../hooks/useDraft.js';
+import {DraftController} from '@/hooks/useDraft.js';
+import * as schema from '@/../core/schema.js';
 
 export interface FieldProps {
   collection: schema.Collection;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/FileField.tsx b/packages/root-cms/ui/components/DocEditor/fields/FileField.tsx
index 42b5ea31..78360dc9 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/FileField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/FileField.tsx
@@ -2,10 +2,10 @@ import {ActionIcon, TextInput, Tooltip} from '@mantine/core';
 import {showNotification} from '@mantine/notifications';
 import {IconFileUpload, IconTrash} from '@tabler/icons-preact';
 import {useEffect, useRef, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
-import {joinClassNames} from '../../../utils/classes.js';
-import {VIDEO_EXTS, getFileExt, uploadFileToGCS} from '../../../utils/gcs.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {VIDEO_EXTS, getFileExt, uploadFileToGCS} from '@/utils/gcs.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export function FileField(props: FieldProps) {
   const field = props.field as schema.FileField;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/ImageField.tsx b/packages/root-cms/ui/components/DocEditor/fields/ImageField.tsx
index ea48c530..d657af4f 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/ImageField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/ImageField.tsx
@@ -3,10 +3,10 @@ import {showNotification} from '@mantine/notifications';
 import {IconPhotoUp, IconTrash} from '@tabler/icons-preact';
 import {ChangeEvent} from 'preact/compat';
 import {useEffect, useRef, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
-import {joinClassNames} from '../../../utils/classes.js';
-import {uploadFileToGCS} from '../../../utils/gcs.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {uploadFileToGCS} from '@/utils/gcs.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export const IMAGE_MIMETYPES = [
   'image/png',
diff --git a/packages/root-cms/ui/components/DocEditor/fields/MultiSelectField.tsx b/packages/root-cms/ui/components/DocEditor/fields/MultiSelectField.tsx
index 026d4349..135ba83b 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/MultiSelectField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/MultiSelectField.tsx
@@ -1,7 +1,7 @@
 import {MultiSelect} from '@mantine/core';
 import {useEffect, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export function MultiSelectField(props: FieldProps) {
   const field = props.field as schema.MultiSelectField;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/ReferenceField.tsx b/packages/root-cms/ui/components/DocEditor/fields/ReferenceField.tsx
index 05772bc7..e41d21d9 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/ReferenceField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/ReferenceField.tsx
@@ -1,12 +1,12 @@
 import {ActionIcon, Button, Image, Loader, Tooltip} from '@mantine/core';
 import {IconTrash} from '@tabler/icons-preact';
 import {useEffect, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
-import {getDocFromCacheOrFetch} from '../../../utils/doc-cache.js';
-import {notifyErrors} from '../../../utils/notifications.js';
-import {getNestedValue} from '../../../utils/objects.js';
-import {useDocPickerModal} from '../../DocPickerModal/DocPickerModal.js';
+import {useDocPickerModal} from '@/components/DocPickerModal/DocPickerModal.js';
+import {getDocFromCacheOrFetch} from '@/utils/doc-cache.js';
+import {notifyErrors} from '@/utils/notifications.js';
+import {getNestedValue} from '@/utils/objects.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 import './ReferenceField.css';
 
 export function ReferenceField(props: FieldProps) {
diff --git a/packages/root-cms/ui/components/DocEditor/fields/RichTextField.tsx b/packages/root-cms/ui/components/DocEditor/fields/RichTextField.tsx
index 44dc6180..4d623468 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/RichTextField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/RichTextField.tsx
@@ -1,11 +1,11 @@
 import {useEffect, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
-import {deepEqual} from '../../../utils/objects.js';
 import {
   RichTextData,
   RichTextEditor,
-} from '../../RichTextEditor/RichTextEditor.js';
+} from '@/components/RichTextEditor/RichTextEditor.js';
+import {deepEqual} from '@/utils/objects.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export function RichTextField(props: FieldProps) {
   const field = props.field as schema.RichTextField;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/SelectField.tsx b/packages/root-cms/ui/components/DocEditor/fields/SelectField.tsx
index 327c6d66..1ae76559 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/SelectField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/SelectField.tsx
@@ -1,7 +1,7 @@
 import {Select} from '@mantine/core';
 import {useEffect, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export function SelectField(props: FieldProps) {
   const field = props.field as schema.SelectField;
diff --git a/packages/root-cms/ui/components/DocEditor/fields/StringField.tsx b/packages/root-cms/ui/components/DocEditor/fields/StringField.tsx
index b8eb889c..21029732 100644
--- a/packages/root-cms/ui/components/DocEditor/fields/StringField.tsx
+++ b/packages/root-cms/ui/components/DocEditor/fields/StringField.tsx
@@ -1,8 +1,8 @@
 import {TextInput, Textarea} from '@mantine/core';
 import {ChangeEvent} from 'preact/compat';
 import {useEffect, useState} from 'preact/hooks';
-import * as schema from '../../../../core/schema.js';
 import {FieldProps} from './FieldProps.js';
+import * as schema from '@/../core/schema.js';
 
 export function StringField(props: FieldProps) {
   const field = props.field as schema.StringField;
diff --git a/packages/root-cms/ui/components/DocPickerModal/DocPickerModal.tsx b/packages/root-cms/ui/components/DocPickerModal/DocPickerModal.tsx
index 24d6ca55..125667b0 100644
--- a/packages/root-cms/ui/components/DocPickerModal/DocPickerModal.tsx
+++ b/packages/root-cms/ui/components/DocPickerModal/DocPickerModal.tsx
@@ -1,10 +1,10 @@
 import {Button, Image, Loader, Select} from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
 import {useState} from 'preact/hooks';
-import {useDocsList} from '../../hooks/useDocsList.js';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {getDocServingUrl} from '../../utils/doc-urls.js';
-import {getNestedValue} from '../../utils/objects.js';
+import {useDocsList} from '@/hooks/useDocsList.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {getDocServingUrl} from '@/utils/doc-urls.js';
+import {getNestedValue} from '@/utils/objects.js';
 import './DocPickerModal.css';
 
 const MODAL_ID = 'DocPickerModal';
diff --git a/packages/root-cms/ui/components/DocPreviewCard/DocPreviewCard.tsx b/packages/root-cms/ui/components/DocPreviewCard/DocPreviewCard.tsx
index 984c217d..c496b704 100644
--- a/packages/root-cms/ui/components/DocPreviewCard/DocPreviewCard.tsx
+++ b/packages/root-cms/ui/components/DocPreviewCard/DocPreviewCard.tsx
@@ -1,11 +1,11 @@
 import {Image, Loader} from '@mantine/core';
 import {useEffect, useState} from 'preact/hooks';
-import {joinClassNames} from '../../utils/classes.js';
-import {getDocFromCacheOrFetch} from '../../utils/doc-cache.js';
-import {getDocServingUrl} from '../../utils/doc-urls.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {getNestedValue} from '../../utils/objects.js';
-import {DocStatusBadges} from '../DocStatusBadges/DocStatusBadges.js';
+import {DocStatusBadges} from '@/components/DocStatusBadges/DocStatusBadges.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {getDocFromCacheOrFetch} from '@/utils/doc-cache.js';
+import {getDocServingUrl} from '@/utils/doc-urls.js';
+import {notifyErrors} from '@/utils/notifications.js';
+import {getNestedValue} from '@/utils/objects.js';
 import './DocPreviewCard.css';
 
 export interface DocPreviewCardProps {
diff --git a/packages/root-cms/ui/components/DocSelectModal/DocSelectModal.tsx b/packages/root-cms/ui/components/DocSelectModal/DocSelectModal.tsx
index 3b5725f3..add09ead 100644
--- a/packages/root-cms/ui/components/DocSelectModal/DocSelectModal.tsx
+++ b/packages/root-cms/ui/components/DocSelectModal/DocSelectModal.tsx
@@ -1,10 +1,10 @@
 import {Button, Image, Loader, Select} from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
 import {useState} from 'preact/hooks';
-import {useDocsList} from '../../hooks/useDocsList.js';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {getDocServingUrl} from '../../utils/doc-urls.js';
-import {getNestedValue} from '../../utils/objects.js';
+import {useDocsList} from '@/hooks/useDocsList.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {getDocServingUrl} from '@/utils/doc-urls.js';
+import {getNestedValue} from '@/utils/objects.js';
 import './DocSelectModal.css';
 
 const MODAL_ID = 'DocSelectModal';
diff --git a/packages/root-cms/ui/components/DocStatusBadges/DocStatusBadges.tsx b/packages/root-cms/ui/components/DocStatusBadges/DocStatusBadges.tsx
index b5edffbf..1b4a4155 100644
--- a/packages/root-cms/ui/components/DocStatusBadges/DocStatusBadges.tsx
+++ b/packages/root-cms/ui/components/DocStatusBadges/DocStatusBadges.tsx
@@ -1,7 +1,7 @@
 import {Badge, Tooltip} from '@mantine/core';
 import {Timestamp} from 'firebase/firestore';
-import {CMSDoc, testPublishingLocked} from '../../utils/doc.js';
-import {formatDateTime, getTimeAgo} from '../../utils/time.js';
+import {CMSDoc, testPublishingLocked} from '@/db/docs.js';
+import {formatDateTime, getTimeAgo} from '@/utils/time.js';
 
 interface DocStatusBadgesProps {
   doc: CMSDoc;
diff --git a/packages/root-cms/ui/components/EditJsonModal/EditJsonModal.tsx b/packages/root-cms/ui/components/EditJsonModal/EditJsonModal.tsx
index 49e7915e..83d099e4 100644
--- a/packages/root-cms/ui/components/EditJsonModal/EditJsonModal.tsx
+++ b/packages/root-cms/ui/components/EditJsonModal/EditJsonModal.tsx
@@ -2,7 +2,7 @@ import {Button, JsonInput} from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
 import {IconClipboard, IconDeviceFloppy} from '@tabler/icons-preact';
 import {useState} from 'preact/hooks';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
 import './EditJsonModal.css';
 
 const MODAL_ID = 'EditJsonModal';
diff --git a/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx b/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx
index 11952cc2..e58aed98 100644
--- a/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx
+++ b/packages/root-cms/ui/components/EditTranslationsModal/EditTranslationsModal.tsx
@@ -3,12 +3,12 @@ import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification, updateNotification} from '@mantine/notifications';
 import {ChangeEvent} from 'preact/compat';
 import {useEffect, useState} from 'preact/hooks';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {useTranslationsDoc} from '../../hooks/useTranslationsDoc.js';
-import {joinClassNames} from '../../utils/classes.js';
-import {GoogleSheetId, getSpreadsheetUrl} from '../../utils/gsheets.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {Heading} from '../Heading/Heading.js';
+import {Heading} from '@/components/Heading/Heading.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {useTranslationsDoc} from '@/hooks/useTranslationsDoc.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {GoogleSheetId, getSpreadsheetUrl} from '@/utils/gsheets.js';
+import {notifyErrors} from '@/utils/notifications.js';
 import './EditTranslationsModal.css';
 
 const MODAL_ID = 'EditTranslationsModal';
diff --git a/packages/root-cms/ui/components/ExportSheetModal/ExportSheetModal.tsx b/packages/root-cms/ui/components/ExportSheetModal/ExportSheetModal.tsx
index 27e2e1da..d68111e6 100644
--- a/packages/root-cms/ui/components/ExportSheetModal/ExportSheetModal.tsx
+++ b/packages/root-cms/ui/components/ExportSheetModal/ExportSheetModal.tsx
@@ -3,17 +3,17 @@ import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification, updateNotification} from '@mantine/notifications';
 import {ChangeEvent, forwardRef} from 'preact/compat';
 import {useState} from 'preact/hooks';
-import {useGapiClient} from '../../hooks/useGapiClient.js';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {cmsLinkGoogleSheetL10n} from '../../utils/doc.js';
+import {Text} from '@/components/Text/Text.js';
+import {dbTranslationsLinkGoogleSheet} from '@/db/translations.js';
+import {useGapiClient} from '@/hooks/useGapiClient.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
 import {
   GSheet,
   GSpreadsheet,
   getSpreadsheetUrl,
   parseSpreadsheetUrl,
-} from '../../utils/gsheets.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {Text} from '../Text/Text.js';
+} from '@/utils/gsheets.js';
+import {notifyErrors} from '@/utils/notifications.js';
 import './ExportSheetModal.css';
 
 const MODAL_ID = 'ExportSheetModal';
@@ -22,7 +22,7 @@ export type Action = 'new-sheet' | 'add-tab' | 'link-sheet';
 
 export interface ExportSheetModalProps {
   [key: string]: unknown;
-  docId: string;
+  translationsId: string;
   csvData: {headers: string[]; rows: Record<string, string>[]};
   locales: string[];
 }
@@ -133,8 +133,8 @@ export function ExportSheetModal(
       if (!gsheet) {
         throw new Error('could not find sheet gid=0');
       }
-      // Update tab name to the doc id.
-      gsheet.setTitle(props.docId);
+      // Update tab name to the translationsId.
+      gsheet.setTitle(props.translationsId);
     } catch (err) {
       console.error(err);
       let msg = err;
@@ -165,7 +165,7 @@ export function ExportSheetModal(
         spreadsheetId: gspreadsheet.spreadsheetId,
         gid: 0,
       };
-      await cmsLinkGoogleSheetL10n(props.docId, linkedSheet);
+      await dbTranslationsLinkGoogleSheet(props.translationsId, linkedSheet);
       setSheetUrl(gsheet.getUrl());
     } catch (err) {
       console.error(err);
@@ -238,7 +238,7 @@ export function ExportSheetModal(
         autoClose: false,
         disallowClose: true,
       });
-      gsheet = await gspreadsheet.createSheet({title: props.docId});
+      gsheet = await gspreadsheet.createSheet({title: props.translationsId});
     } catch (err) {
       console.error(err);
       let msg = err;
@@ -269,7 +269,7 @@ export function ExportSheetModal(
         spreadsheetId: gspreadsheet.spreadsheetId,
         gid: gsheet.gid,
       };
-      await cmsLinkGoogleSheetL10n(props.docId, linkedSheet);
+      await dbTranslationsLinkGoogleSheet(props.translationsId, linkedSheet);
     } catch (err) {
       console.error(err);
       updateNotification({
@@ -334,7 +334,7 @@ export function ExportSheetModal(
         autoClose: false,
         disallowClose: true,
       });
-      await cmsLinkGoogleSheetL10n(props.docId, gsheetId);
+      await dbTranslationsLinkGoogleSheet(props.translationsId, gsheetId);
     } catch (err) {
       console.error(err);
       updateNotification({
@@ -385,7 +385,7 @@ export function ExportSheetModal(
             <Select
               itemComponent={ExportSheetModal.SelectItem}
               data={selectItems}
-              onChange={(e) => {
+              onChange={(e: Action) => {
                 setAction(e);
                 if (e === 'new-sheet') {
                   setSheetUrl('');
diff --git a/packages/root-cms/ui/components/Heading/Heading.tsx b/packages/root-cms/ui/components/Heading/Heading.tsx
index ce8aae7c..e45f95de 100644
--- a/packages/root-cms/ui/components/Heading/Heading.tsx
+++ b/packages/root-cms/ui/components/Heading/Heading.tsx
@@ -1,6 +1,5 @@
 import {ComponentChildren} from 'preact';
-
-import {joinClassNames} from '../../utils/classes.js';
+import {joinClassNames} from '@/utils/classes.js';
 import './Heading.css';
 
 export interface HeadingProps {
diff --git a/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx b/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx
index c1b254c7..5d103cd1 100644
--- a/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx
+++ b/packages/root-cms/ui/components/LocalizationModal/LocalizationModal.tsx
@@ -1,66 +1,27 @@
 import {
-  ActionIcon,
   Box,
   Button,
   Checkbox,
-  Divider,
   Group,
   Loader,
-  Menu,
   Select,
   Stack,
   Text,
-  Tooltip,
 } from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
-import {showNotification} from '@mantine/notifications';
-import {
-  IconChevronDown,
-  IconFileDownload,
-  IconFileUpload,
-  IconLanguage,
-  IconMapPin,
-  IconTable,
-} from '@tabler/icons-preact';
-import {useEffect, useMemo, useState} from 'preact/hooks';
-import * as schema from '../../../core/schema.js';
-import {TranslationsMap} from '../../db/translations.js';
-import {DraftController} from '../../hooks/useDraft.js';
-import {GapiClient, useGapiClient} from '../../hooks/useGapiClient.js';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {useTranslationsDoc} from '../../hooks/useTranslationsDoc.js';
-import {logAction} from '../../utils/actions.js';
-import {
-  CsvTranslation,
-  cmsDocImportTranslations,
-  cmsGetLinkedGoogleSheetL10n,
-  cmsGetTranslations,
-  cmsUnlinkGoogleSheetL10n,
-} from '../../utils/doc.js';
-import {
-  GSheet,
-  GSpreadsheet,
-  GoogleSheetId,
-  getSpreadsheetUrl,
-} from '../../utils/gsheets.js';
-import {useExportSheetModal} from '../ExportSheetModal/ExportSheetModal.js';
-import {Heading} from '../Heading/Heading.js';
+import {IconLanguage, IconMapPin} from '@tabler/icons-preact';
+import {useEffect, useState} from 'preact/hooks';
+import {Heading} from '@/components/Heading/Heading.js';
+import {TranslationsImportExportButtons} from '@/components/TranslationsImportExportButtons/TranslationsImportExportButtons.js';
+import {DraftController} from '@/hooks/useDraft.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {useTranslationsDoc} from '@/hooks/useTranslationsDoc.js';
+import * as schema from '@/../core/schema.js';
+
 import './LocalizationModal.css';
-import {TranslationsImportExportButtons} from '../TranslationsImportExportButtons/TranslationsImportExportButtons.js';
 
 const MODAL_ID = 'LocalizationModal';
 
-enum MenuAction {
-  EXPORT_DOWNLOAD_CSV = 'EXPORT_DOWNLOAD_CSV',
-  EXPORT_GOOGLE_SHEET_CREATE = 'EXPORT_GOOGLE_SHEET_CREATE',
-  EXPORT_GOOGLE_SHEET_ADD_TAB = 'EXPORT_GOOGLE_SHEET_ADD_TAB',
-  EXPORT_GOOGLE_SHEET_LINKED = 'EXPORT_GOOGLE_SHEET_LINKED',
-  EXPORT_GOOGLE_SHEET_SHOW_OPTIONS = 'EXPORT_GOOGLE_SHEET_SHOW_OPTIONS',
-  IMPORT_CSV = 'IMPORT_CSV',
-  IMPORT_GOOGLE_SHEET_LINKED = 'IMPORT_GOOGLE_SHEET_LINKED',
-  UNLINK_GOOGLE_SHEET = 'UNLINK_GOOGLE_SHEET',
-}
-
 export interface LocalizationModalProps {
   [key: string]: unknown;
   draft: DraftController;
@@ -286,8 +247,6 @@ LocalizationModal.AllNoneButtons = (props: AllNoneButtonsProps) => {
 };
 
 LocalizationModal.Translations = (props: LocalizationModalProps) => {
-  const [loading, setLoading] = useState(true);
-  const [sourceStrings, setSourceStrings] = useState<string[]>([]);
   const [selectedLocale, setSelectedLocale] = useState(() => {
     // Initialize with the first non-EN locale.
     if (props.draft) {
@@ -308,19 +267,6 @@ LocalizationModal.Translations = (props: LocalizationModalProps) => {
   const [localeTranslations, setLocaleTranslations] = useState<
     Record<string, string>
   >({});
-  const [translationsMap, setTranslationsMap] = useState<TranslationsMap>({});
-  const gapiClient = useGapiClient();
-  // const [linkedSheet, setLinkedSheet] = useState<GoogleSheetId | null>(null);
-  const exportSheetModal = useExportSheetModal();
-
-  const sourceToTranslationsMap = useMemo(() => {
-    const results: {[source: string]: Record<string, string>} = {};
-    Object.values(translationsMap).forEach((row: Record<string, string>) => {
-      results[row.source] = row;
-    });
-    return results;
-  }, [translationsMap]);
-
   const locales = window.__ROOT_CTX.rootConfig.i18n?.locales || [];
   const localeOptions = locales.map((locale) => ({
     value: locale,
@@ -328,22 +274,12 @@ LocalizationModal.Translations = (props: LocalizationModalProps) => {
   }));
 
   const translationsDoc = useTranslationsDoc(props.docId);
-  const linkedSheet = translationsDoc.linkedSheet;
+  const loading = translationsDoc.loading;
 
-  async function init() {
-    setLoading(true);
-    const translationsMap = translationsDoc?.strings || {};
-    const sourceStrings = Object.values(translationsMap)
-      .map((item) => item.source)
-      .filter((item) => !!item);
-    setSourceStrings(Array.from(sourceStrings));
-    setTranslationsMap(translationsMap);
-    setLoading(false);
-  }
-
-  useEffect(() => {
-    init();
-  }, [props.docId, translationsDoc.loading]);
+  const translationsMap = translationsDoc?.strings || {};
+  const sourceStrings = Object.values(translationsMap)
+    .map((item) => item.source)
+    .filter((item) => !!item);
 
   useEffect(() => {
     if (!selectedLocale) {
@@ -360,246 +296,6 @@ LocalizationModal.Translations = (props: LocalizationModalProps) => {
     setLocaleTranslations(localeTranslations);
   }, [selectedLocale, translationsMap]);
 
-  function getTranslation(source: string, locale: string): string {
-    const row = sourceToTranslationsMap[source];
-    if (row) {
-      return row[locale] || '';
-    }
-    return '';
-  }
-
-  function formatCsvData() {
-    const nonEnLocales = locales.filter((l) => l !== 'en');
-    const headers = ['source', 'en', ...nonEnLocales];
-    const rows: Array<Record<string, string>> = [];
-    sourceStrings.forEach((source) => {
-      const row: Record<string, string> = {
-        source: source,
-        en: getTranslation(source, 'en') || source,
-      };
-      nonEnLocales.forEach((l) => {
-        row[l] = getTranslation(source, l);
-      });
-      rows.push(row);
-    });
-    return {headers, rows};
-  }
-
-  async function downloadCsv() {
-    const {headers, rows} = formatCsvData();
-    const res = await window.fetch('/cms/api/csv.download', {
-      method: 'POST',
-      headers: {'Content-Type': 'application/json'},
-      body: JSON.stringify({headers, rows}),
-    });
-    if (res.status !== 200) {
-      console.error('csv.download failed:');
-      const text = await res.text();
-      console.error(text);
-    }
-    const blob = await res.blob();
-    const file = window.URL.createObjectURL(blob);
-    window.location.assign(file);
-    window.URL.revokeObjectURL(file);
-  }
-
-  async function importCsv() {
-    const fileInput = document.createElement('input');
-    fileInput.type = 'file';
-    fileInput.accept = '.csv';
-    fileInput.addEventListener('change', async () => {
-      const file = fileInput.files?.[0];
-      if (file) {
-        const formData = new FormData();
-        formData.append('file', file);
-        try {
-          const res = await fetch('/cms/api/csv.import', {
-            method: 'POST',
-            body: formData,
-          });
-          if (res.status !== 200) {
-            const errorText = await res.text();
-            throw new Error(`RPCError: ${errorText}`);
-          }
-          const resData = (await res.json()).data;
-          const importedTranslations = await cmsDocImportTranslations(
-            props.docId,
-            resData
-          );
-          setTranslationsMap((currentTranslations) => {
-            return Object.assign({}, currentTranslations, importedTranslations);
-          });
-          showNotification({
-            title: 'Saved!',
-            message: `Imported translations for ${props.docId}.`,
-            autoClose: 5000,
-          });
-        } catch (err) {
-          console.error(err);
-          showNotification({
-            title: 'Failed to import CSV',
-            message: String(err),
-            color: 'red',
-            autoClose: false,
-          });
-        }
-      }
-    });
-    fileInput.click();
-  }
-
-  async function exportToLinkedSheet() {
-    if (!gapiClient.isLoggedIn()) {
-      await gapiClient.login();
-    }
-    if (!linkedSheet?.spreadsheetId) {
-      throw new Error('no sheet linked');
-    }
-    const gspreadsheet = new GSpreadsheet(linkedSheet.spreadsheetId);
-    const gsheet = await gspreadsheet.getSheet(linkedSheet.gid ?? 0);
-    if (!gsheet) {
-      throw new Error(`sheet not found: ${JSON.stringify(linkedSheet)}`);
-    }
-    await exportStringsToSheet(gsheet);
-    showNotification({
-      title: 'Exported strings to Google Sheet',
-      message: gsheet.getUrl(),
-      autoClose: false,
-    });
-  }
-
-  async function exportStringsToSheet(
-    gsheet: GSheet,
-    options?: {isNew?: boolean}
-  ) {
-    const isNew = options?.isNew || false;
-    const {headers, rows} = formatCsvData();
-    if (isNew) {
-      // Update sheet data.
-      await gsheet.replaceSheet(headers, rows);
-      // Apply the default styles to the sheet.
-      await gsheet.applyL10nTheme();
-    } else {
-      // Update existing sheet, replacing only cells as needed (keyed by the
-      // "source" column). New rows are added to the end of the sheet.
-      await gsheet.updateValuesMap(rows, {
-        keyedBy: 'source',
-        // When exporting strings, avoid overwriting cells where there is an
-        // existing translation. If users want to export translations from the
-        // CMS to the sheet, they should clear those cells first.
-        preserveColumns: locales,
-      });
-    }
-    logAction('doc.export_to_sheet', {
-      metadata: {
-        docId: props.docId,
-        sheetId: {
-          spreadsheetId: gsheet.spreadsheet.spreadsheetId,
-          gid: gsheet.gid,
-        },
-      },
-    });
-  }
-
-  async function importGoogleSheet() {
-    if (!gapiClient.isLoggedIn()) {
-      await gapiClient.login();
-    }
-    if (!linkedSheet?.spreadsheetId) {
-      throw new Error('no sheet linked');
-    }
-    const gspreadsheet = new GSpreadsheet(linkedSheet.spreadsheetId);
-    const gsheet = await gspreadsheet.getSheet(linkedSheet.gid ?? 0);
-    if (!gsheet) {
-      throw new Error(`sheet not found: ${JSON.stringify(linkedSheet)}`);
-    }
-
-    console.log('importing google sheet');
-    const values = (await gsheet.getValuesMap()) as CsvTranslation[];
-
-    const importedTranslations = await cmsDocImportTranslations(
-      props.docId,
-      values
-    );
-    setTranslationsMap((currentTranslations) => {
-      return Object.assign({}, currentTranslations, importedTranslations);
-    });
-    showNotification({
-      title: 'Saved!',
-      message: `Imported translations for ${props.docId}.`,
-      autoClose: 5000,
-    });
-  }
-
-  async function unlinkGoogleSheet() {
-    await translationsDoc.unlinkSheet();
-    showNotification({
-      title: 'Unlinked Google Sheet',
-      message: `${props.docId} is no longer connected to a Google Sheet.`,
-      autoClose: 5000,
-    });
-  }
-
-  /**
-   * Wrapper that calls a function and shows a generic error notification if any
-   * exceptions occur.
-   */
-  async function notifyErrors(fn: () => Promise<void>) {
-    try {
-      await fn();
-    } catch (err) {
-      console.error(err);
-      let msg: string;
-      if (typeof err === 'object' && err.body) {
-        msg = String(err.body);
-      } else {
-        msg = String(err);
-      }
-      showNotification({
-        title: 'Error',
-        message: msg,
-        color: 'red',
-        autoClose: false,
-      });
-    }
-  }
-
-  function onAction(action: MenuAction) {
-    switch (action) {
-      case MenuAction.EXPORT_DOWNLOAD_CSV: {
-        notifyErrors(downloadCsv);
-        return;
-      }
-      case MenuAction.EXPORT_GOOGLE_SHEET_LINKED: {
-        notifyErrors(exportToLinkedSheet);
-        return;
-      }
-      case MenuAction.EXPORT_GOOGLE_SHEET_SHOW_OPTIONS: {
-        exportSheetModal.open({
-          docId: props.docId,
-          csvData: formatCsvData(),
-          locales: locales,
-        });
-        return;
-      }
-      case MenuAction.IMPORT_CSV: {
-        notifyErrors(importCsv);
-        return;
-      }
-      case MenuAction.IMPORT_GOOGLE_SHEET_LINKED: {
-        notifyErrors(importGoogleSheet);
-        return;
-      }
-      case MenuAction.UNLINK_GOOGLE_SHEET: {
-        notifyErrors(unlinkGoogleSheet);
-        return;
-      }
-      default: {
-        console.log('unhandled action: ' + action);
-      }
-    }
-  }
-
   if (loading) {
     return (
       <div className="LocalizationModal__translations__loading">
diff --git a/packages/root-cms/ui/components/LockPublishingModal/LockPublishingModal.tsx b/packages/root-cms/ui/components/LockPublishingModal/LockPublishingModal.tsx
index 2883c81a..4483494d 100644
--- a/packages/root-cms/ui/components/LockPublishingModal/LockPublishingModal.tsx
+++ b/packages/root-cms/ui/components/LockPublishingModal/LockPublishingModal.tsx
@@ -1,13 +1,13 @@
-import {Button, InputWrapper, TextInput, Textarea} from '@mantine/core';
+import {Button, InputWrapper, TextInput} from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification} from '@mantine/notifications';
 import {IconLock, IconLockOpen} from '@tabler/icons-preact';
 import {ChangeEvent} from 'preact/compat';
 import {useState} from 'preact/hooks';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {cmsLockPublishing, cmsUnlockPublishing} from '../../utils/doc.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {Text} from '../Text/Text.js';
+import {Text} from '@/components/Text/Text.js';
+import {dbLockPublishing, dbUnlockPublishing} from '@/db/docs.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {notifyErrors} from '@/utils/notifications.js';
 import './LockPublishingModal.css';
 
 const MODAL_ID = 'LockPublishingModal';
@@ -68,7 +68,7 @@ LockPublishingModal.Lock = (
     e.preventDefault();
     setLoading(true);
     await notifyErrors(async () => {
-      await cmsLockPublishing(props.docId, {reason, until});
+      await dbLockPublishing(props.docId, {reason, until});
       showNotification({
         title: 'Locked!',
         message: `Publishing is locked for ${props.docId}.`,
@@ -157,7 +157,7 @@ LockPublishingModal.Unlock = (
   async function onSubmit() {
     setLoading(true);
     await notifyErrors(async () => {
-      await cmsUnlockPublishing(props.docId);
+      await dbUnlockPublishing(props.docId);
       showNotification({
         title: 'Unlocked!',
         message: `Publishing is unlocked for ${props.docId}.`,
diff --git a/packages/root-cms/ui/components/Markdown/Markdown.tsx b/packages/root-cms/ui/components/Markdown/Markdown.tsx
index c2cad609..7df7556c 100644
--- a/packages/root-cms/ui/components/Markdown/Markdown.tsx
+++ b/packages/root-cms/ui/components/Markdown/Markdown.tsx
@@ -1,6 +1,5 @@
 import {marked} from 'marked';
-
-import {joinClassNames} from '../../utils/classes.js';
+import {joinClassNames} from '@/utils/classes.js';
 
 interface MarkdownProps {
   className?: string;
@@ -15,7 +14,7 @@ export function Markdown(props: MarkdownProps) {
   return (
     <div
       className={joinClassNames('Markdown', props.className)}
-      dangerouslySetInnerHTML={{__html: html}}
+      dangerouslySetInnerHTML={{__html: html as string}}
     />
   );
 }
diff --git a/packages/root-cms/ui/components/NewDocModal/NewDocModal.tsx b/packages/root-cms/ui/components/NewDocModal/NewDocModal.tsx
index 8bc69d31..2962a318 100644
--- a/packages/root-cms/ui/components/NewDocModal/NewDocModal.tsx
+++ b/packages/root-cms/ui/components/NewDocModal/NewDocModal.tsx
@@ -1,11 +1,10 @@
 import {Button, Modal, useMantineTheme} from '@mantine/core';
 import {useState} from 'preact/hooks';
 import {route} from 'preact-router';
-import {cmsCreateDoc} from '../../utils/doc.js';
-import {getDefaultFieldValue} from '../../utils/fields.js';
-import {SlugInput} from '../SlugInput/SlugInput.js';
+import {SlugInput} from '@/components/SlugInput/SlugInput.js';
+import {dbCreateDoc} from '@/db/docs.js';
+import {getDefaultFieldValue} from '@/utils/fields.js';
 import './NewDocModal.css';
-import {logAction} from '../../utils/actions.js';
 
 interface NewDocModalProps {
   collection: string;
@@ -72,7 +71,7 @@ export function NewDocModal(props: NewDocModalProps) {
     const docId = `${collectionId}/${cleanSlug}`;
     try {
       const defaultValue = getDefaultFieldValue(rootCollection);
-      await cmsCreateDoc(docId, {fields: defaultValue});
+      await dbCreateDoc(docId, {fields: defaultValue});
     } catch (err) {
       setSlugError(String(err));
       setLoading(false);
diff --git a/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx b/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx
index ad525350..5e6e69b2 100644
--- a/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx
+++ b/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx
@@ -2,11 +2,11 @@ import {Accordion, Button, Loader} from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification} from '@mantine/notifications';
 import {useState, useRef} from 'preact/hooks';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {joinClassNames} from '../../utils/classes.js';
-import {cmsPublishDoc, cmsScheduleDoc} from '../../utils/doc.js';
-import {DocDiffViewer} from '../DocDiffViewer/DocDiffViewer.js';
-import {Text} from '../Text/Text.js';
+import {DocDiffViewer} from '@/components/DocDiffViewer/DocDiffViewer.js';
+import {Text} from '@/components/Text/Text.js';
+import {dbPublishDoc, dbScheduleDoc} from '@/db/docs.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {joinClassNames} from '@/utils/classes.js';
 import './PublishDocModal.css';
 
 const MODAL_ID = 'PublishDocModal';
@@ -49,7 +49,7 @@ export function PublishDocModal(
   async function publish() {
     try {
       setLoading(true);
-      await cmsPublishDoc(props.docId);
+      await dbPublishDoc(props.docId);
       setLoading(false);
       showNotification({
         title: 'Published!',
@@ -72,7 +72,7 @@ export function PublishDocModal(
     try {
       setLoading(true);
       const millis = Math.floor(new Date(scheduledDate).getTime());
-      await cmsScheduleDoc(props.docId, millis);
+      await dbScheduleDoc(props.docId, millis);
       setLoading(false);
       showNotification({
         title: 'Scheduled!',
diff --git a/packages/root-cms/ui/components/ReleaseForm/ReleaseForm.tsx b/packages/root-cms/ui/components/ReleaseForm/ReleaseForm.tsx
index aa2c7377..fd404d37 100644
--- a/packages/root-cms/ui/components/ReleaseForm/ReleaseForm.tsx
+++ b/packages/root-cms/ui/components/ReleaseForm/ReleaseForm.tsx
@@ -11,16 +11,11 @@ import {showNotification} from '@mantine/notifications';
 import {IconArrowUpRight, IconTrash} from '@tabler/icons-preact';
 import {useEffect, useRef, useState} from 'preact/hooks';
 import {route} from 'preact-router';
-import {notifyErrors} from '../../utils/notifications.js';
-import {
-  Release,
-  addRelease,
-  getRelease,
-  updateRelease,
-} from '../../utils/release.js';
-import {isSlugValid} from '../../utils/slug.js';
-import {DocPreviewCard} from '../DocPreviewCard/DocPreviewCard.js';
-import {useDocSelectModal} from '../DocSelectModal/DocSelectModal.js';
+import {DocPreviewCard} from '@/components/DocPreviewCard/DocPreviewCard.js';
+import {useDocSelectModal} from '@/components/DocSelectModal/DocSelectModal.js';
+import {Release, addRelease, getRelease, updateRelease} from '@/db/releases.js';
+import {notifyErrors} from '@/utils/notifications.js';
+import {isSlugValid} from '@/utils/slug.js';
 import './ReleaseForm.css';
 
 export interface ReleaseFormProps {
diff --git a/packages/root-cms/ui/components/ReleaseStatusBadge/ReleaseStatusBadge.tsx b/packages/root-cms/ui/components/ReleaseStatusBadge/ReleaseStatusBadge.tsx
index 3ff22559..ceb8db1c 100644
--- a/packages/root-cms/ui/components/ReleaseStatusBadge/ReleaseStatusBadge.tsx
+++ b/packages/root-cms/ui/components/ReleaseStatusBadge/ReleaseStatusBadge.tsx
@@ -1,7 +1,7 @@
 import {Badge, Tooltip} from '@mantine/core';
 import {Timestamp} from 'firebase/firestore';
-import {Release} from '../../utils/release.js';
-import {getTimeAgo} from '../../utils/time.js';
+import {Release} from '@/db/releases.js';
+import {getTimeAgo} from '@/utils/time.js';
 
 const TOOLTIP_PROPS = {
   transition: 'pop',
diff --git a/packages/root-cms/ui/components/RichTextEditor/RichTextEditor.tsx b/packages/root-cms/ui/components/RichTextEditor/RichTextEditor.tsx
index bb4af3da..2a68c61d 100644
--- a/packages/root-cms/ui/components/RichTextEditor/RichTextEditor.tsx
+++ b/packages/root-cms/ui/components/RichTextEditor/RichTextEditor.tsx
@@ -6,13 +6,13 @@ import NestedList from '@editorjs/nested-list';
 import RawHtmlTool from '@editorjs/raw';
 // import Table from '@editorjs/table';
 import {useEffect, useRef, useState} from 'preact/hooks';
-import {joinClassNames} from '../../utils/classes.js';
-import './RichTextEditor.css';
-import {uploadFileToGCS} from '../../utils/gcs.js';
-import {isObject} from '../../utils/objects.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {uploadFileToGCS} from '@/utils/gcs.js';
+import {isObject} from '@/utils/objects.js';
 import Strikethrough from './tools/Strikethrough.js';
 import Superscript from './tools/Superscript.js';
 import Underline from './tools/Underline.js';
+import './RichTextEditor.css';
 
 export interface RichTextEditorProps {
   className?: string;
diff --git a/packages/root-cms/ui/components/ScheduleReleaseModal/ScheduleReleaseModal.tsx b/packages/root-cms/ui/components/ScheduleReleaseModal/ScheduleReleaseModal.tsx
index 85c4bc9b..1e4716ae 100644
--- a/packages/root-cms/ui/components/ScheduleReleaseModal/ScheduleReleaseModal.tsx
+++ b/packages/root-cms/ui/components/ScheduleReleaseModal/ScheduleReleaseModal.tsx
@@ -3,9 +3,9 @@ import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification} from '@mantine/notifications';
 import {Timestamp} from 'firebase/firestore';
 import {useState, useRef} from 'preact/hooks';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {scheduleRelease} from '../../utils/release.js';
+import {scheduleRelease} from '@/db/releases.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
+import {notifyErrors} from '@/utils/notifications.js';
 import './ScheduleReleaseModal.css';
 
 const MODAL_ID = 'ScheduleReleaseModal';
diff --git a/packages/root-cms/ui/components/ShareBox/ShareBox.tsx b/packages/root-cms/ui/components/ShareBox/ShareBox.tsx
index 624b367c..df871e7d 100644
--- a/packages/root-cms/ui/components/ShareBox/ShareBox.tsx
+++ b/packages/root-cms/ui/components/ShareBox/ShareBox.tsx
@@ -7,11 +7,11 @@ import {
   deleteField,
 } from 'firebase/firestore';
 import {useEffect, useState} from 'preact/hooks';
-import {logAction} from '../../utils/actions.js';
-import {joinClassNames} from '../../utils/classes.js';
-import {notifyErrors} from '../../utils/notifications.js';
-import {sortByKey} from '../../utils/objects.js';
-import {Text} from '../Text/Text.js';
+import {Text} from '@/components/Text/Text.js';
+import {logAction} from '@/db/actions.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {notifyErrors} from '@/utils/notifications.js';
+import {sortByKey} from '@/utils/objects.js';
 import './ShareBox.css';
 
 export interface ShareBoxProps {
diff --git a/packages/root-cms/ui/components/SlugInput/SlugInput.tsx b/packages/root-cms/ui/components/SlugInput/SlugInput.tsx
index b13d0682..43ed3894 100644
--- a/packages/root-cms/ui/components/SlugInput/SlugInput.tsx
+++ b/packages/root-cms/ui/components/SlugInput/SlugInput.tsx
@@ -1,10 +1,10 @@
 import {Select, TextInput} from '@mantine/core';
 import {ChangeEvent} from 'preact/compat';
 import {useRef, useState} from 'preact/hooks';
-import {Text} from '../../components/Text/Text.js';
-import {joinClassNames} from '../../utils/classes.js';
-import {getDocServingUrl} from '../../utils/doc-urls.js';
-import {isSlugValid, normalizeSlug} from '../../utils/slug.js';
+import {Text} from '@/components/Text/Text.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {getDocServingUrl} from '@/utils/doc-urls.js';
+import {isSlugValid, normalizeSlug} from '@/utils/slug.js';
 import './SlugInput.css';
 
 export interface SlugInputProps {
diff --git a/packages/root-cms/ui/components/SplitPanel/SplitPanel.tsx b/packages/root-cms/ui/components/SplitPanel/SplitPanel.tsx
index 78ad8507..cec82704 100644
--- a/packages/root-cms/ui/components/SplitPanel/SplitPanel.tsx
+++ b/packages/root-cms/ui/components/SplitPanel/SplitPanel.tsx
@@ -1,9 +1,8 @@
 import {ComponentChild, ComponentChildren} from 'preact';
 import {CSSProperties} from 'preact/compat';
 import {useEffect, useRef, useState} from 'preact/hooks';
-
-import {useLocalStorage} from '../../hooks/useLocalStorage.js';
-import {joinClassNames} from '../../utils/classes.js';
+import {useLocalStorage} from '@/hooks/useLocalStorage.js';
+import {joinClassNames} from '@/utils/classes.js';
 import './SplitPanel.css';
 
 export interface SplitPanelProps {
diff --git a/packages/root-cms/ui/components/Text/Text.tsx b/packages/root-cms/ui/components/Text/Text.tsx
index a36f7292..d7048c97 100644
--- a/packages/root-cms/ui/components/Text/Text.tsx
+++ b/packages/root-cms/ui/components/Text/Text.tsx
@@ -1,6 +1,5 @@
 import {ComponentChildren} from 'preact';
-
-import {joinClassNames} from '../../utils/classes.js';
+import {joinClassNames} from '@/utils/classes.js';
 import './Text.css';
 
 export interface TextProps {
diff --git a/packages/root-cms/ui/components/TimeSinceActionTooltip/TimeSinceActionTooltip.tsx b/packages/root-cms/ui/components/TimeSinceActionTooltip/TimeSinceActionTooltip.tsx
index bc4ba5ab..9fde4f39 100644
--- a/packages/root-cms/ui/components/TimeSinceActionTooltip/TimeSinceActionTooltip.tsx
+++ b/packages/root-cms/ui/components/TimeSinceActionTooltip/TimeSinceActionTooltip.tsx
@@ -1,7 +1,7 @@
 import {Tooltip} from '@mantine/core';
 import {Timestamp} from 'firebase/firestore';
 import {useEffect, useState} from 'preact/hooks';
-import {getTimeAgo} from '../../utils/time.js';
+import {getTimeAgo} from '@/utils/time.js';
 
 export interface TimeSinceTooltipActionProps {
   timestamp?: number | Timestamp;
diff --git a/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx b/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx
index b6a5f99b..cdc89145 100644
--- a/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx
+++ b/packages/root-cms/ui/components/TranslationsImportExportButtons/TranslationsImportExportButtons.tsx
@@ -6,23 +6,23 @@ import {
   IconFileUpload,
   IconTable,
 } from '@tabler/icons-preact';
+import {useExportSheetModal} from '@/components/ExportSheetModal/ExportSheetModal.js';
+import {logAction} from '@/db/actions.js';
 import {
   csvToTranslationsMap,
   Translations,
   translationsIdToDocId,
-} from '../../db/translations.js';
-import {GapiClient, useGapiClient} from '../../hooks/useGapiClient.js';
-import {TranslationsDocController} from '../../hooks/useTranslationsDoc.js';
-import {logAction} from '../../utils/actions.js';
-import {joinClassNames} from '../../utils/classes.js';
+} from '@/db/translations.js';
+import {GapiClient, useGapiClient} from '@/hooks/useGapiClient.js';
+import {TranslationsDocController} from '@/hooks/useTranslationsDoc.js';
+import {joinClassNames} from '@/utils/classes.js';
 import {
   getSpreadsheetUrl,
   GoogleSheetId,
   GSheet,
   GSpreadsheet,
-} from '../../utils/gsheets.js';
-import {useExportSheetModal} from '../ExportSheetModal/ExportSheetModal.js';
-
+} from '@/utils/gsheets.js';
+import {notifyErrors} from '@/utils/notifications.js';
 import './TranslationsImportExportButtons.css';
 
 enum MenuAction {
@@ -224,30 +224,6 @@ export function TranslationsImportExportButtons(
     });
   }
 
-  /**
-   * Wrapper that calls a function and shows a generic error notification if any
-   * exceptions occur.
-   */
-  async function notifyErrors(fn: () => Promise<void>) {
-    try {
-      await fn();
-    } catch (err) {
-      console.error(err);
-      let msg: string;
-      if (typeof err === 'object' && err.body) {
-        msg = String(err.body);
-      } else {
-        msg = String(err);
-      }
-      showNotification({
-        title: 'Error',
-        message: msg,
-        color: 'red',
-        autoClose: false,
-      });
-    }
-  }
-
   function onAction(action: MenuAction) {
     switch (action) {
       case MenuAction.EXPORT_DOWNLOAD_CSV: {
@@ -260,7 +236,7 @@ export function TranslationsImportExportButtons(
       }
       case MenuAction.EXPORT_GOOGLE_SHEET_SHOW_OPTIONS: {
         exportSheetModal.open({
-          docId: translationsId,
+          translationsId: translationsId,
           csvData: formatCsvData(),
           locales: locales,
         });
diff --git a/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx b/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx
index b26a02a6..92229a22 100644
--- a/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx
+++ b/packages/root-cms/ui/components/TranslationsStatusBadges/TranslationsStatusBadges.tsx
@@ -1,6 +1,6 @@
 import {Badge, Tooltip} from '@mantine/core';
-import {TranslationsDoc} from '../../utils/doc.js';
-import {timeDiff} from '../../utils/time.js';
+import {TranslationsDoc} from '@/db/translations.js';
+import {timeDiff} from '@/utils/time.js';
 
 interface TranslationsStatusBadgesProps {
   translationsDoc: TranslationsDoc;
diff --git a/packages/root-cms/ui/components/VersionHistoryModal/VersionHistoryModal.tsx b/packages/root-cms/ui/components/VersionHistoryModal/VersionHistoryModal.tsx
index 02f6725b..7a9df332 100644
--- a/packages/root-cms/ui/components/VersionHistoryModal/VersionHistoryModal.tsx
+++ b/packages/root-cms/ui/components/VersionHistoryModal/VersionHistoryModal.tsx
@@ -3,10 +3,10 @@ import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification} from '@mantine/notifications';
 import {IconArrowUpRight, IconHistory} from '@tabler/icons-preact';
 import {useEffect, useState} from 'preact/hooks';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {Version, cmsListVersions, cmsRestoreVersion} from '../../utils/doc.js';
-import {Heading} from '../Heading/Heading.js';
-import {Text} from '../Text/Text.js';
+import {Heading} from '@/components/Heading/Heading.js';
+import {Text} from '@/components/Text/Text.js';
+import {VersionDoc, dbListVersions, dbRestoreVersion} from '@/db/versions.js';
+import {useModalTheme} from '@/hooks/useModalTheme.js';
 import './VersionHistoryModal.css';
 
 const MODAL_ID = 'VersionHistoryModal';
@@ -14,7 +14,7 @@ const MODAL_ID = 'VersionHistoryModal';
 export interface VersionHistoryModalProps {
   [key: string]: unknown;
   docId: string;
-  onRestore?: (data: {version: Version}) => any;
+  onRestore?: (data: {version: VersionDoc}) => any;
 }
 
 export function useVersionHistoryModal(props: VersionHistoryModalProps) {
@@ -37,7 +37,7 @@ export function VersionHistoryModal(
   const {innerProps: props} = modalProps;
   const docId = props.docId;
   const [loading, setLoading] = useState(true);
-  const [versions, setVersions] = useState<Version[]>([]);
+  const [versions, setVersions] = useState<VersionDoc[]>([]);
 
   const dateFormat = new Intl.DateTimeFormat('en-US', {
     year: 'numeric',
@@ -49,13 +49,13 @@ export function VersionHistoryModal(
 
   async function fetchVersions() {
     setLoading(true);
-    const versions = await cmsListVersions(docId);
+    const versions = await dbListVersions(docId);
     setLoading(false);
     setVersions(versions);
   }
 
-  async function restore(version: Version) {
-    await cmsRestoreVersion(docId, version);
+  async function restore(version: VersionDoc) {
+    await dbRestoreVersion(docId, version);
     showNotification({
       title: 'Saved!',
       message: `Restored ${docId} to ${dateFormat.format(
@@ -68,7 +68,7 @@ export function VersionHistoryModal(
     }
   }
 
-  function getCompareUrl(version: Version) {
+  function getCompareUrl(version: VersionDoc) {
     const left = toUrlParam(docId, version._versionId);
     const right = toUrlParam(docId, 'draft');
     return `/cms/compare?left=${left}&right=${right}`;
@@ -109,7 +109,7 @@ export function VersionHistoryModal(
           </thead>
           <tbody>
             {versions.map((version, i) => (
-              <tr>
+              <tr key={i}>
                 <td>
                   <Text size="body-sm">
                     {dateFormat.format(version.sys.modifiedAt.toDate())}
diff --git a/packages/root-cms/ui/components/Viewers/Viewers.tsx b/packages/root-cms/ui/components/Viewers/Viewers.tsx
index c5ff3195..ea48d4d5 100644
--- a/packages/root-cms/ui/components/Viewers/Viewers.tsx
+++ b/packages/root-cms/ui/components/Viewers/Viewers.tsx
@@ -10,12 +10,12 @@ import {
   updateDoc,
 } from 'firebase/firestore';
 import {useEffect, useState} from 'preact/hooks';
-import {joinClassNames} from '../../utils/classes.js';
-import {EventListener} from '../../utils/events.js';
-import {normalizeSlug} from '../../utils/slug.js';
-import {throttle} from '../../utils/throttle.js';
-import {TIME_UNITS} from '../../utils/time.js';
-import {Timer} from '../../utils/timer.js';
+import {joinClassNames} from '@/utils/classes.js';
+import {EventListener} from '@/utils/events.js';
+import {normalizeSlug} from '@/utils/slug.js';
+import {throttle} from '@/utils/throttle.js';
+import {TIME_UNITS} from '@/utils/time.js';
+import {Timer} from '@/utils/timer.js';
 import './Viewers.css';
 
 // Frequency to update.
diff --git a/packages/root-cms/ui/utils/actions.ts b/packages/root-cms/ui/db/actions.ts
similarity index 96%
rename from packages/root-cms/ui/utils/actions.ts
rename to packages/root-cms/ui/db/actions.ts
index 9ea8d46c..fb709548 100644
--- a/packages/root-cms/ui/utils/actions.ts
+++ b/packages/root-cms/ui/db/actions.ts
@@ -6,8 +6,7 @@ import {
   orderBy,
   query,
 } from 'firebase/firestore';
-import {DataSource} from './data-source.js';
-import {TIME_UNITS, timestamp} from './time.js';
+import {TIME_UNITS, timestamp} from '@/utils/time.js';
 
 /** A map of when an action was last called. */
 const ACTION_TIMESTAMPS: Record<string, number> = {};
diff --git a/packages/root-cms/ui/utils/data-source.ts b/packages/root-cms/ui/db/data-sources.ts
similarity index 99%
rename from packages/root-cms/ui/utils/data-source.ts
rename to packages/root-cms/ui/db/data-sources.ts
index fc31b326..ae287cb4 100644
--- a/packages/root-cms/ui/utils/data-source.ts
+++ b/packages/root-cms/ui/db/data-sources.ts
@@ -10,8 +10,8 @@ import {
   updateDoc,
   writeBatch,
 } from 'firebase/firestore';
+import {GSpreadsheet, parseSpreadsheetUrl} from '@/utils/gsheets.js';
 import {logAction} from './actions.js';
-import {GSpreadsheet, parseSpreadsheetUrl} from './gsheets.js';
 
 export type DataSourceType = 'http' | 'gsheet';
 
diff --git a/packages/root-cms/ui/utils/doc.ts b/packages/root-cms/ui/db/docs.ts
similarity index 80%
rename from packages/root-cms/ui/utils/doc.ts
rename to packages/root-cms/ui/db/docs.ts
index 7e02fa09..a2f93282 100644
--- a/packages/root-cms/ui/utils/doc.ts
+++ b/packages/root-cms/ui/db/docs.ts
@@ -9,19 +9,16 @@ import {
   writeBatch,
   collection,
   query,
-  orderBy,
   getDocs,
   updateDoc,
   documentId,
   where,
   WriteBatch,
-  DocumentReference,
 } from 'firebase/firestore';
+import {dbPublishTranslationsDoc} from '@/db/translations.js';
+import {removeDocFromCache, removeDocsFromCache} from '@/utils/doc-cache.js';
+import {GoogleSheetId} from '@/utils/gsheets.js';
 import {logAction} from './actions.js';
-import {removeDocFromCache, removeDocsFromCache} from './doc-cache.js';
-import {GoogleSheetId} from './gsheets.js';
-import {normalizeString, sourceHash, TranslationsMap} from './l10n.js';
-import {TranslationsDoc} from './translations.js';
 
 export interface CMSDoc {
   id: string;
@@ -55,11 +52,7 @@ export interface CMSDoc {
   fields: any;
 }
 
-export type Version = CMSDoc & {
-  _versionId: string;
-};
-
-export async function cmsDeleteDoc(docId: string) {
+export async function dbDeleteDoc(docId: string) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
   const [collectionId, slug] = docId.split('/');
@@ -103,14 +96,14 @@ export async function cmsDeleteDoc(docId: string) {
   logAction('doc.delete', {metadata: {docId}});
 }
 
-export async function cmsPublishDoc(docId: string) {
-  await cmsPublishDocs([docId]);
+export async function dbPublishDoc(docId: string) {
+  await dbPublishDocs([docId]);
 }
 
 /**
  * Batch publishes a group of docs.
  */
-export async function cmsPublishDocs(
+export async function dbPublishDocs(
   docIds: string[],
   options?: {batch?: WriteBatch}
 ) {
@@ -135,7 +128,7 @@ export async function cmsPublishDocs(
       throw new Error(`doc does not exist: ${docId}`);
     }
     updatePublishedDocDataInBatch(batch, docId, draftData);
-    cmsPublishTranslationsDoc(docId, {batch});
+    dbPublishTranslationsDoc(docId, {batch});
   });
   await batch.commit();
 
@@ -223,7 +216,7 @@ function updatePublishedDocDataInBatch(
 /**
  * Schedules a CMS doc to be published at some time in the future.
  */
-export async function cmsScheduleDoc(docId: string, millis: number) {
+export async function dbScheduleDoc(docId: string, millis: number) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
   const [collectionId, slug] = docId.split('/');
@@ -268,7 +261,7 @@ export async function cmsScheduleDoc(docId: string, millis: number) {
   logAction('doc.schedule', {metadata: {docId, scheduledAt: millis}});
 }
 
-export async function cmsUnpublishDoc(docId: string) {
+export async function dbUnpublishDoc(docId: string) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
   const [collectionId, slug] = docId.split('/');
@@ -319,7 +312,10 @@ export async function cmsUnpublishDoc(docId: string) {
   removeDocFromCache(docId);
 }
 
-export async function cmsRevertDraft(docId: string) {
+/**
+ * Reverts a doc to its published state.
+ */
+export async function dbRevertDraft(docId: string) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
   const [collectionId, slug] = docId.split('/');
@@ -353,7 +349,10 @@ export async function cmsRevertDraft(docId: string) {
   logAction('doc.revert', {metadata: {docId}});
 }
 
-export async function cmsUnscheduleDoc(docId: string) {
+/**
+ * Unschedules a previously scheduled doc.
+ */
+export async function dbUnscheduleDoc(docId: string) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
   const [collectionId, slug] = docId.split('/');
@@ -390,7 +389,10 @@ export async function cmsUnscheduleDoc(docId: string) {
   logAction('doc.unschedule', {metadata: {docId}});
 }
 
-export async function cmsLockPublishing(
+/**
+ * Adds a lock to disable a doc from being published.
+ */
+export async function dbLockPublishing(
   docId: string,
   options: {reason: string; until?: number}
 ) {
@@ -415,7 +417,10 @@ export async function cmsLockPublishing(
   logAction('doc.lock_publishing', {metadata});
 }
 
-export async function cmsUnlockPublishing(docId: string) {
+/**
+ * Removes a lock to allow a doc from being published.
+ */
+export async function dbUnlockPublishing(docId: string) {
   const docRef = getDraftDocRef(docId);
   const updates = {
     'sys.publishingLocked': deleteField(),
@@ -448,7 +453,10 @@ export function testPublishingLocked(docData: CMSDoc) {
   return false;
 }
 
-export async function cmsCopyDoc(
+/**
+ * Copies a doc from one id to another.
+ */
+export async function dbCopyDoc(
   fromDocId: string,
   toDocId: string,
   options?: {overwrite?: boolean}
@@ -459,10 +467,13 @@ export async function cmsCopyDoc(
     throw new Error(`doc ${fromDocId} does not exist`);
   }
   const fields = fromDoc.data().fields ?? {};
-  await cmsCreateDoc(toDocId, {fields, overwrite: options?.overwrite});
+  await dbCreateDoc(toDocId, {fields, overwrite: options?.overwrite});
 }
 
-export async function cmsCreateDoc(
+/**
+ * Adds a new doc.
+ */
+export async function dbCreateDoc(
   docId: string,
   options?: {fields?: Record<string, any>; overwrite?: boolean}
 ) {
@@ -500,55 +511,9 @@ export async function cmsCreateDoc(
   logAction('doc.create', {metadata: {docId}});
 }
 
-export interface CsvTranslation {
-  [key: string]: string;
-  source: string;
-}
-
-export async function cmsDocImportTranslations(
-  docId: string,
-  csvData: CsvTranslation[]
-) {
-  const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
-  const i18nLocales = i18nConfig.locales || ['en'];
-
-  function normalizeLocale(locale: string) {
-    for (const l of i18nLocales) {
-      if (String(l).toLowerCase() === locale.toLowerCase()) {
-        return l;
-      }
-    }
-    // Ignore locales that are not in the root config.
-    return null;
-  }
-
-  const translationsMap: Record<string, CsvTranslation> = {};
-  for (const row of csvData) {
-    if (!row.source) {
-      continue;
-    }
-    const translation: CsvTranslation = {
-      source: normalizeString(row.source),
-    };
-    Object.entries(row).forEach(([column, str]) => {
-      if (column === 'source') {
-        return;
-      }
-      const locale = normalizeLocale(column);
-      if (locale) {
-        translation[locale] = normalizeString(str || '');
-      }
-    });
-
-    const hash = await sourceHash(translation.source);
-    translationsMap[hash] = translation;
-  }
-
-  const translationsId = docId;
-  await cmsSaveTranslations(translationsId, translationsMap);
-  return translationsMap;
-}
-
+/**
+ * Returns the "draft" firestore doc ref for a CMS doc.
+ */
 export function getDraftDocRef(docId: string) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
@@ -564,6 +529,9 @@ export function getDraftDocRef(docId: string) {
   );
 }
 
+/**
+ * Returns the "published" firestore doc ref for a CMS doc.
+ */
 export function getPublishedDocRef(docId: string) {
   const projectId = window.__ROOT_CTX.rootConfig.projectId;
   const db = window.firebase.db;
@@ -579,23 +547,6 @@ export function getPublishedDocRef(docId: string) {
   );
 }
 
-export function getVersionDocRef(docId: string, versionId: string) {
-  const projectId = window.__ROOT_CTX.rootConfig.projectId;
-  const db = window.firebase.db;
-  const [collectionId, slug] = docId.split('/');
-  return doc(
-    db,
-    'Projects',
-    projectId,
-    'Collections',
-    collectionId,
-    'Drafts',
-    slug,
-    'Versions',
-    versionId
-  );
-}
-
 export async function getDraftDocs(
   docIds: string[]
 ): Promise<Record<string, CMSDoc>> {
@@ -632,60 +583,6 @@ export async function getDraftDocs(
   return drafts;
 }
 
-export async function cmsListVersions(docId: string) {
-  const db = window.firebase.db;
-  const docRef = getDraftDocRef(docId);
-  const versionsCollection = collection(db, docRef.path, 'Versions');
-  const q = query(versionsCollection, orderBy('sys.modifiedAt', 'desc'));
-  const querySnapshot = await getDocs(q);
-  const versions: Version[] = [];
-  querySnapshot.forEach((doc) => {
-    const version = {
-      ...(doc.data() as Version),
-      _versionId: doc.id,
-    };
-    versions.push(version);
-  });
-  return versions;
-}
-
-export async function cmsRestoreVersion(docId: string, version: Version) {
-  const docRef = getDraftDocRef(docId);
-  const updates = {
-    'sys.modifiedAt': serverTimestamp(),
-    'sys.modifiedBy': window.firebase.user.email,
-    fields: version.fields || {},
-  };
-  await updateDoc(docRef, updates);
-  logAction('doc.restore_version', {
-    metadata: {
-      docId,
-      versionModifiedAt: version.sys?.modifiedAt,
-      versionModifiedBy: version.sys?.modifiedBy,
-    },
-  });
-}
-
-export async function cmsReadDocVersion(
-  docId: string,
-  versionId: string | 'draft' | 'published'
-): Promise<CMSDoc | null> {
-  let docRef: DocumentReference;
-  if (versionId === 'draft') {
-    docRef = getDraftDocRef(docId);
-  } else if (versionId === 'published') {
-    docRef = getPublishedDocRef(docId);
-  } else {
-    docRef = getVersionDocRef(docId, versionId);
-  }
-
-  const snapshot = await getDoc(docRef);
-  if (snapshot.exists()) {
-    return snapshot.data() as CMSDoc;
-  }
-  return null;
-}
-
 /**
  * Links a Google Sheet to a doc for localization.
  */
diff --git a/packages/root-cms/ui/utils/release.ts b/packages/root-cms/ui/db/releases.ts
similarity index 98%
rename from packages/root-cms/ui/utils/release.ts
rename to packages/root-cms/ui/db/releases.ts
index ba873399..4c695b58 100644
--- a/packages/root-cms/ui/utils/release.ts
+++ b/packages/root-cms/ui/db/releases.ts
@@ -14,7 +14,7 @@ import {
   writeBatch,
 } from 'firebase/firestore';
 import {logAction} from './actions.js';
-import {cmsPublishDocs} from './doc.js';
+import {dbPublishDocs} from './docs.js';
 
 export interface Release {
   id: string;
@@ -117,7 +117,7 @@ export async function publishRelease(id: string) {
     scheduledAt: deleteField(),
     scheduledBy: deleteField(),
   });
-  await cmsPublishDocs(docIds, {batch});
+  await dbPublishDocs(docIds, {batch});
   console.log(`published release: ${id}`);
   logAction('release.publish', {metadata: {releaseId: id, docIds: docIds}});
 }
diff --git a/packages/root-cms/ui/db/translations.ts b/packages/root-cms/ui/db/translations.ts
index 16479ad9..599b19c1 100644
--- a/packages/root-cms/ui/db/translations.ts
+++ b/packages/root-cms/ui/db/translations.ts
@@ -11,11 +11,14 @@ import {
   serverTimestamp,
   setDoc,
   Timestamp,
+  updateDoc,
   writeBatch,
   WriteBatch,
 } from 'firebase/firestore';
-import {logAction} from '../utils/actions.js';
-import {normalizeString, sourceHash} from '../utils/l10n.js';
+import {GoogleSheetId} from '@/utils/gsheets.js';
+import {normalizeString, sourceHash} from '@/utils/l10n.js';
+import {logAction} from './actions.js';
+import {getDraftDocRef} from './docs.js';
 
 export interface Translations {
   [locale: string]: string;
@@ -143,8 +146,11 @@ export async function dbPublishTranslationsDoc(
     docSlug
   );
   const snapshot = await getDoc(draftRef);
+
   if (!snapshot.exists()) {
-    throw new Error(`translations doc ${translationsId} does not exist`);
+    // Ignore missing translations.
+    console.warn(`translations ${translationsId} does not exist`);
+    return;
   }
 
   // If the translations publishing is tied to another batch request (e.g. doc
@@ -174,7 +180,7 @@ export async function dbPublishTranslationsDoc(
   data.sys.publishedBy = window.firebase.user.email;
   batch.set(publishedRef, data);
   if (commitBatch) {
-    await setDoc(publishedRef, data);
+    await batch.commit();
     logAction('translations.publish', {metadata: {translationsId}});
   }
 }
@@ -237,3 +243,38 @@ export async function csvToTranslationsMap(
   }
   return strings;
 }
+
+/**
+ * Links a Google Sheet to a doc for localization.
+ */
+export async function dbTranslationsLinkGoogleSheet(
+  translationsId: string,
+  sheetId: GoogleSheetId
+) {
+  if (!sheetId?.spreadsheetId) {
+    throw new Error('no spreadsheet id');
+  }
+  const projectId = window.__ROOT_CTX.rootConfig.projectId;
+  const db = window.firebase.db;
+  const docRef = doc(
+    db,
+    'Projects',
+    projectId,
+    'TranslationsManager',
+    'draft',
+    'Translations',
+    translationsId.replaceAll('/', '--')
+  );
+  const updates = {
+    'sys.linkedSheet': {
+      spreadsheetId: sheetId.spreadsheetId,
+      gid: sheetId.gid || 0,
+      linkedAt: serverTimestamp(),
+      linkedBy: window.firebase.user.email,
+    },
+  };
+  await updateDoc(docRef, updates);
+  logAction('translations.link_sheet', {
+    metadata: {translationsId: translationsId, sheetId: sheetId},
+  });
+}
diff --git a/packages/root-cms/ui/utils/users.ts b/packages/root-cms/ui/db/users.ts
similarity index 100%
rename from packages/root-cms/ui/utils/users.ts
rename to packages/root-cms/ui/db/users.ts
diff --git a/packages/root-cms/ui/db/versions.ts b/packages/root-cms/ui/db/versions.ts
new file mode 100644
index 00000000..79d29eaa
--- /dev/null
+++ b/packages/root-cms/ui/db/versions.ts
@@ -0,0 +1,88 @@
+import {
+  DocumentReference,
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  orderBy,
+  query,
+  serverTimestamp,
+  updateDoc,
+} from 'firebase/firestore';
+import {logAction} from './actions.js';
+import {CMSDoc, getDraftDocRef, getPublishedDocRef} from './docs.js';
+
+export type VersionDoc = CMSDoc & {
+  _versionId: string;
+};
+
+export async function dbListVersions(docId: string) {
+  const db = window.firebase.db;
+  const docRef = getDraftDocRef(docId);
+  const versionsCollection = collection(db, docRef.path, 'Versions');
+  const q = query(versionsCollection, orderBy('sys.modifiedAt', 'desc'));
+  const querySnapshot = await getDocs(q);
+  const versions: VersionDoc[] = [];
+  querySnapshot.forEach((doc) => {
+    const version = {
+      ...(doc.data() as VersionDoc),
+      _versionId: doc.id,
+    };
+    versions.push(version);
+  });
+  return versions;
+}
+
+export async function dbRestoreVersion(docId: string, version: VersionDoc) {
+  const docRef = getDraftDocRef(docId);
+  const updates = {
+    'sys.modifiedAt': serverTimestamp(),
+    'sys.modifiedBy': window.firebase.user.email,
+    fields: version.fields || {},
+  };
+  await updateDoc(docRef, updates);
+  logAction('doc.restore_version', {
+    metadata: {
+      docId,
+      versionModifiedAt: version.sys?.modifiedAt,
+      versionModifiedBy: version.sys?.modifiedBy,
+    },
+  });
+}
+
+export async function dbGetDocVersion(
+  docId: string,
+  versionId: string | 'draft' | 'published'
+): Promise<CMSDoc | null> {
+  let docRef: DocumentReference;
+  if (versionId === 'draft') {
+    docRef = getDraftDocRef(docId);
+  } else if (versionId === 'published') {
+    docRef = getPublishedDocRef(docId);
+  } else {
+    docRef = getVersionDocRef(docId, versionId);
+  }
+
+  const snapshot = await getDoc(docRef);
+  if (snapshot.exists()) {
+    return snapshot.data() as CMSDoc;
+  }
+  return null;
+}
+
+export function getVersionDocRef(docId: string, versionId: string) {
+  const projectId = window.__ROOT_CTX.rootConfig.projectId;
+  const db = window.firebase.db;
+  const [collectionId, slug] = docId.split('/');
+  return doc(
+    db,
+    'Projects',
+    projectId,
+    'Collections',
+    collectionId,
+    'Drafts',
+    slug,
+    'Versions',
+    versionId
+  );
+}
diff --git a/packages/root-cms/ui/hooks/useDocsList.ts b/packages/root-cms/ui/hooks/useDocsList.ts
index bc187121..f8f93674 100644
--- a/packages/root-cms/ui/hooks/useDocsList.ts
+++ b/packages/root-cms/ui/hooks/useDocsList.ts
@@ -7,8 +7,8 @@ import {
   documentId,
 } from 'firebase/firestore';
 import {useEffect, useState} from 'preact/hooks';
-import {setDocToCache} from '../utils/doc-cache.js';
-import {notifyErrors} from '../utils/notifications.js';
+import {setDocToCache} from '@/utils/doc-cache.js';
+import {notifyErrors} from '@/utils/notifications.js';
 import {useFirebase} from './useFirebase.js';
 
 export function useDocsList(collectionId: string, options: {orderBy: string}) {
diff --git a/packages/root-cms/ui/hooks/useDraft.ts b/packages/root-cms/ui/hooks/useDraft.ts
index 352ebfd5..cc0d283e 100644
--- a/packages/root-cms/ui/hooks/useDraft.ts
+++ b/packages/root-cms/ui/hooks/useDraft.ts
@@ -9,12 +9,12 @@ import {
   deleteField,
 } from 'firebase/firestore';
 import {useEffect, useMemo, useState} from 'preact/hooks';
-import {logAction} from '../utils/actions.js';
-import {debounce} from '../utils/debounce.js';
-import {setDocToCache} from '../utils/doc-cache.js';
-import {EventListener} from '../utils/events.js';
-import {getNestedValue, isObject} from '../utils/objects.js';
-import {TIME_UNITS} from '../utils/time.js';
+import {logAction} from '@/db/actions.js';
+import {debounce} from '@/utils/debounce.js';
+import {setDocToCache} from '@/utils/doc-cache.js';
+import {EventListener} from '@/utils/events.js';
+import {getNestedValue, isObject} from '@/utils/objects.js';
+import {TIME_UNITS} from '@/utils/time.js';
 
 const SAVE_DELAY = 3 * TIME_UNITS.second;
 const SAVE_ACTION_LOG_THROTTLE = 5 * TIME_UNITS.minute;
diff --git a/packages/root-cms/ui/hooks/useTranslationsDoc.ts b/packages/root-cms/ui/hooks/useTranslationsDoc.ts
index fbb3e885..e3e34c87 100644
--- a/packages/root-cms/ui/hooks/useTranslationsDoc.ts
+++ b/packages/root-cms/ui/hooks/useTranslationsDoc.ts
@@ -1,13 +1,12 @@
 import {useEffect, useState} from 'preact/hooks';
 import {
-  TranslationsDoc,
   TranslationsLinkedSheet,
   TranslationsMap,
   dbGetTranslationsDoc,
   dbSaveTranslations,
-} from '../db/translations.js';
-import {extractStringsForDoc} from '../utils/extract.js';
-import {normalizeString, sourceHash} from '../utils/l10n.js';
+} from '@/db/translations.js';
+import {extractStringsForDoc} from '@/utils/extract.js';
+import {normalizeString, sourceHash} from '@/utils/l10n.js';
 
 export interface TranslationsDocController {
   id: string;
@@ -34,8 +33,6 @@ export function useTranslationsDoc(
   translationsId: string
 ): TranslationsDocController {
   const [loading, setLoading] = useState(true);
-  const [translationsDoc, setTranslationsDoc] =
-    useState<TranslationsDoc | null>(null);
   const [strings, setStrings] = useState<TranslationsMap>({});
   const [linkedSheet, setLinkedSheet] =
     useState<TranslationsLinkedSheet | null>(null);
@@ -48,7 +45,6 @@ export function useTranslationsDoc(
       getTranslationsMapForDoc(translationsId),
       dbGetTranslationsDoc(translationsId),
     ]);
-    setTranslationsDoc(translationsDoc);
     const strings = mergeTranslationsMaps(
       docStrings,
       translationsDoc?.strings || {}
diff --git a/packages/root-cms/ui/layout/Layout.tsx b/packages/root-cms/ui/layout/Layout.tsx
index 6aeb686f..a10649ee 100644
--- a/packages/root-cms/ui/layout/Layout.tsx
+++ b/packages/root-cms/ui/layout/Layout.tsx
@@ -12,9 +12,9 @@ import {
 } from '@tabler/icons-preact';
 import {ComponentChildren} from 'preact';
 import {useRouter} from 'preact-router';
-import packageJson from '../../package.json' assert {type: 'json'};
-import {RootCMSLogo} from '../components/RootCMSLogo/RootCMSLogo.js';
-import {joinClassNames} from '../utils/classes.js';
+import {RootCMSLogo} from '@/components/RootCMSLogo/RootCMSLogo.js';
+import {joinClassNames} from '@/utils/classes.js';
+import packageJson from '@/../package.json' assert {type: 'json'};
 import './Layout.css';
 
 const ICON_STROKE = '1.5';
diff --git a/packages/root-cms/ui/pages/DataPage/DataPage.tsx b/packages/root-cms/ui/pages/DataPage/DataPage.tsx
index ad769f19..552294ae 100644
--- a/packages/root-cms/ui/pages/DataPage/DataPage.tsx
+++ b/packages/root-cms/ui/pages/DataPage/DataPage.tsx
@@ -3,8 +3,8 @@ import {useEffect, useState} from 'preact/hooks';
 import {DataSourceStatusButton} from '../../components/DataSourceStatusButton/DataSourceStatusButton.js';
 import {Heading} from '../../components/Heading/Heading.js';
 import {Text} from '../../components/Text/Text.js';
+import {DataSource, listDataSources} from '../../db/data-sources.js';
 import {Layout} from '../../layout/Layout.js';
-import {DataSource, listDataSources} from '../../utils/data-source.js';
 import './DataPage.css';
 
 export function DataPage() {
diff --git a/packages/root-cms/ui/pages/DataSourcePage/DataSourcePage.tsx b/packages/root-cms/ui/pages/DataSourcePage/DataSourcePage.tsx
index dd926f71..17062eda 100644
--- a/packages/root-cms/ui/pages/DataSourcePage/DataSourcePage.tsx
+++ b/packages/root-cms/ui/pages/DataSourcePage/DataSourcePage.tsx
@@ -14,13 +14,13 @@ import {useEffect, useState} from 'preact/hooks';
 import {DataSourceStatusButton} from '../../components/DataSourceStatusButton/DataSourceStatusButton.js';
 import {Heading} from '../../components/Heading/Heading.js';
 import {Text} from '../../components/Text/Text.js';
-import {Layout} from '../../layout/Layout.js';
 import {
   DataSourceData,
   DataSource,
   getFromDataSource,
   getDataSource,
-} from '../../utils/data-source.js';
+} from '../../db/data-sources.js';
+import {Layout} from '../../layout/Layout.js';
 import './DataSourcePage.css';
 
 export function DataSourcePage(props: {id: string}) {
diff --git a/packages/root-cms/ui/pages/EditDataSourcePage/EditDataSourcePage.tsx b/packages/root-cms/ui/pages/EditDataSourcePage/EditDataSourcePage.tsx
index 52a65b63..fdedccfd 100644
--- a/packages/root-cms/ui/pages/EditDataSourcePage/EditDataSourcePage.tsx
+++ b/packages/root-cms/ui/pages/EditDataSourcePage/EditDataSourcePage.tsx
@@ -6,9 +6,9 @@ import {route} from 'preact-router';
 import {DataSourceForm} from '../../components/DataSourceForm/DataSourceForm.js';
 import {Heading} from '../../components/Heading/Heading.js';
 import {Text} from '../../components/Text/Text.js';
+import {deleteDataSource} from '../../db/data-sources.js';
 import {useModalTheme} from '../../hooks/useModalTheme.js';
 import {Layout} from '../../layout/Layout.js';
-import {deleteDataSource} from '../../utils/data-source.js';
 import './EditDataSourcePage.css';
 
 export function EditDataSourcePage(props: {id: string}) {
diff --git a/packages/root-cms/ui/pages/EditReleasePage/EditReleasePage.tsx b/packages/root-cms/ui/pages/EditReleasePage/EditReleasePage.tsx
index 0a61afba..db432bca 100644
--- a/packages/root-cms/ui/pages/EditReleasePage/EditReleasePage.tsx
+++ b/packages/root-cms/ui/pages/EditReleasePage/EditReleasePage.tsx
@@ -6,10 +6,10 @@ import {route} from 'preact-router';
 import {Heading} from '../../components/Heading/Heading.js';
 import {ReleaseForm} from '../../components/ReleaseForm/ReleaseForm.js';
 import {Text} from '../../components/Text/Text.js';
+import {deleteRelease} from '../../db/releases.js';
 import {useModalTheme} from '../../hooks/useModalTheme.js';
 import {Layout} from '../../layout/Layout.js';
 import './EditReleasePage.css';
-import {deleteRelease} from '../../utils/release.js';
 
 export function EditReleasePage(props: {id: string}) {
   const modals = useModals();
diff --git a/packages/root-cms/ui/pages/ReleasePage/ReleasePage.tsx b/packages/root-cms/ui/pages/ReleasePage/ReleasePage.tsx
index d26f6d61..5890e6ce 100644
--- a/packages/root-cms/ui/pages/ReleasePage/ReleasePage.tsx
+++ b/packages/root-cms/ui/pages/ReleasePage/ReleasePage.tsx
@@ -15,15 +15,15 @@ import {Heading} from '../../components/Heading/Heading.js';
 import {ReleaseStatusBadge} from '../../components/ReleaseStatusBadge/ReleaseStatusBadge.js';
 import {useScheduleReleaseModal} from '../../components/ScheduleReleaseModal/ScheduleReleaseModal.js';
 import {Text} from '../../components/Text/Text.js';
-import {useModalTheme} from '../../hooks/useModalTheme.js';
-import {Layout} from '../../layout/Layout.js';
-import {notifyErrors} from '../../utils/notifications.js';
 import {
   Release,
   cancelScheduledRelease,
   getRelease,
   publishRelease,
-} from '../../utils/release.js';
+} from '../../db/releases.js';
+import {useModalTheme} from '../../hooks/useModalTheme.js';
+import {Layout} from '../../layout/Layout.js';
+import {notifyErrors} from '../../utils/notifications.js';
 import {timestamp} from '../../utils/time.js';
 import './ReleasePage.css';
 
diff --git a/packages/root-cms/ui/pages/ReleasesPage/ReleasesPage.tsx b/packages/root-cms/ui/pages/ReleasesPage/ReleasesPage.tsx
index ed2d111f..658de353 100644
--- a/packages/root-cms/ui/pages/ReleasesPage/ReleasesPage.tsx
+++ b/packages/root-cms/ui/pages/ReleasesPage/ReleasesPage.tsx
@@ -3,8 +3,8 @@ import {useEffect, useState} from 'preact/hooks';
 import {Heading} from '../../components/Heading/Heading.js';
 import {ReleaseStatusBadge} from '../../components/ReleaseStatusBadge/ReleaseStatusBadge.js';
 import {Text} from '../../components/Text/Text.js';
+import {Release, listReleases} from '../../db/releases.js';
 import {Layout} from '../../layout/Layout.js';
-import {Release, listReleases} from '../../utils/release.js';
 import './ReleasesPage.css';
 
 export function ReleasesPage() {
diff --git a/packages/root-cms/ui/pages/TranslationsArbPage/TranslationsArbPage.tsx b/packages/root-cms/ui/pages/TranslationsArbPage/TranslationsArbPage.tsx
index 759c9d03..c0a0af1f 100644
--- a/packages/root-cms/ui/pages/TranslationsArbPage/TranslationsArbPage.tsx
+++ b/packages/root-cms/ui/pages/TranslationsArbPage/TranslationsArbPage.tsx
@@ -1,13 +1,13 @@
 import {Breadcrumbs, Button, Textarea} from '@mantine/core';
 import {ChangeEvent, useState} from 'preact/compat';
-import {Heading} from '../../components/Heading/Heading.js';
-import {Text} from '../../components/Text/Text.js';
-import {Layout} from '../../layout/Layout.js';
+import {Heading} from '@/components/Heading/Heading.js';
+import {Text} from '@/components/Text/Text.js';
+import {getDraftDocs} from '@/db/docs.js';
+import {Layout} from '@/layout/Layout.js';
+import {Arb} from '@/utils/arb.js';
+import {extractFields} from '@/utils/extract.js';
+import {sourceHash} from '@/utils/l10n.js';
 import './TranslationsArbPage.css';
-import {Arb} from '../../utils/arb.js';
-import {getDraftDocs} from '../../utils/doc.js';
-import {extractFields} from '../../utils/extract.js';
-import {sourceHash} from '../../utils/l10n.js';
 
 export function TranslationsArbPage() {
   return (
diff --git a/packages/root-cms/ui/tsconfig.json b/packages/root-cms/ui/tsconfig.json
index 7595ebb4..e55e4eba 100644
--- a/packages/root-cms/ui/tsconfig.json
+++ b/packages/root-cms/ui/tsconfig.json
@@ -26,7 +26,10 @@
     "resolveJsonModule": true,
     "moduleResolution": "nodenext",
     "jsx": "react-jsx",
-    "jsxImportSource": "preact"
+    "jsxImportSource": "preact",
+    "paths": {
+      "@/*": ["./*"]
+    }
   },
   "include": [
     "*.ts",
diff --git a/packages/root-cms/ui/utils/doc-cache.ts b/packages/root-cms/ui/utils/doc-cache.ts
index f592f873..667c83b0 100644
--- a/packages/root-cms/ui/utils/doc-cache.ts
+++ b/packages/root-cms/ui/utils/doc-cache.ts
@@ -1,5 +1,5 @@
 import {getDoc} from 'firebase/firestore';
-import {getDraftDocRef} from './doc.js';
+import {getDraftDocRef} from '@/db/docs.js';
 
 const DOC_CACHE: Map<string, any> = new Map();
 
diff --git a/packages/root-cms/ui/utils/extract.ts b/packages/root-cms/ui/utils/extract.ts
index fce21cc9..56cfd141 100644
--- a/packages/root-cms/ui/utils/extract.ts
+++ b/packages/root-cms/ui/utils/extract.ts
@@ -1,7 +1,7 @@
 import {doc, getDoc} from 'firebase/firestore';
-import * as schema from '../../core/schema.js';
-import {RichTextData} from '../components/RichTextEditor/RichTextEditor.js';
+import {RichTextData} from '@/components/RichTextEditor/RichTextEditor.js';
 import {normalizeString} from './l10n.js';
+import * as schema from '@/../core/schema.js';
 
 export async function extractStringsForDoc(docId: string) {
   const db = window.firebase.db;
diff --git a/packages/root-cms/ui/utils/gsheets.ts b/packages/root-cms/ui/utils/gsheets.ts
index 757164f8..eb929d48 100644
--- a/packages/root-cms/ui/utils/gsheets.ts
+++ b/packages/root-cms/ui/utils/gsheets.ts
@@ -1,4 +1,4 @@
-import {getAllEditors} from './users.js';
+import {getAllEditors} from '@/db/users.js';
 
 export interface GoogleSheetId {
   spreadsheetId: string;
diff --git a/packages/root-cms/ui/utils/l10n.ts b/packages/root-cms/ui/utils/l10n.ts
index e623a6c6..1f710c5d 100644
--- a/packages/root-cms/ui/utils/l10n.ts
+++ b/packages/root-cms/ui/utils/l10n.ts
@@ -7,7 +7,7 @@ import {
   updateDoc,
   where,
 } from 'firebase/firestore';
-import {logAction} from './actions.js';
+import {logAction} from '@/db/actions.js';
 import {TIME_UNITS} from './time.js';
 
 export interface Translation {
diff --git a/packages/root-cms/ui/utils/objects.ts b/packages/root-cms/ui/utils/objects.ts
index 60bd2d35..a7fe6436 100644
--- a/packages/root-cms/ui/utils/objects.ts
+++ b/packages/root-cms/ui/utils/objects.ts
@@ -110,3 +110,29 @@ export function deepEqual(obj1: any, obj2: any) {
 
   return true;
 }
+
+/** A pretty printer for JavaScript objects. */
+export function stringifyObj(obj: any) {
+  function format(obj: any): string {
+    if (obj === null) {
+      return 'null';
+    }
+    if (typeof obj === 'undefined') {
+      return 'undefined';
+    }
+    if (typeof obj === 'string') {
+      return `"${obj.replaceAll('"', '\\"')}"`;
+    }
+    if (typeof obj !== 'object') {
+      return String(obj);
+    }
+    if (Array.isArray(obj)) {
+      return `[${obj.map(format).join(', ')}]`;
+    }
+    const entries: string[] = Object.entries(obj).map(([key, value]) => {
+      return `${key}: ${format(value)}`;
+    });
+    return `{${entries.join(', ')}}`;
+  }
+  return format(obj);
+}

From 2f9ab14a0101509e044050629ab4b40c63f980aa Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Mon, 14 Oct 2024 12:52:11 -0400
Subject: [PATCH 06/14] feat: [v2] add translations doc publishing to cms
 client

---
 packages/root-cms/core/client.ts        | 56 ++++++++++++++++++++++++-
 packages/root-cms/core/compatibility.ts |  3 +-
 packages/root-cms/ui/db/translations.ts |  1 -
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index 8c0126aa..cfd02ed0 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -50,6 +50,7 @@ export interface TranslationsDoc {
       linkedAt: Timestamp;
       linkedBy: string;
     };
+    tags?: string[];
   };
   strings: TranslationsMap;
 }
@@ -482,6 +483,9 @@ export class RootCMSClient {
       });
       batchCount += 1;
 
+      this.publishTranslationsDoc(doc.id, {batch});
+      batchCount += 2;
+
       publishedDocs.push(doc);
 
       if (batchCount >= 400) {
@@ -594,6 +598,9 @@ export class RootCMSClient {
       });
       batchCount += 1;
 
+      this.publishTranslationsDoc(doc.id, {batch});
+      batchCount += 2;
+
       publishedDocs.push(doc);
 
       if (batchCount >= 400) {
@@ -635,6 +642,48 @@ export class RootCMSClient {
     }
   }
 
+  async publishTranslationsDoc(
+    translationsId: string,
+    options?: {batch?: WriteBatch; publishedBy?: string}
+  ) {
+    const docSlug = translationsId.replaceAll('/', '--');
+    const draftRef = this.db.doc(
+      `Projects/${this.projectId}/TranslationsManager/draft/Translations/${docSlug}`
+    );
+    const snapshot = await draftRef.get();
+
+    if (!snapshot.exists) {
+      // Ignore missing translations.
+      console.warn(`translations ${translationsId} does not exist`);
+      return;
+    }
+
+    // If the translations publishing is tied to another batch request (e.g. doc
+    // publishing), the batch request will be committed upstream.
+    const commitBatch = !options?.batch;
+
+    const batch = options?.batch || this.db.batch();
+    batch.update(draftRef, {
+      'sys.publishedAt': Timestamp.now(),
+      'sys.publishedBy': options?.publishedBy || 'root-cms-client',
+    });
+
+    const publishedRef = this.db.doc(
+      `Projects/${this.projectId}/TranslationsManager/published/Translations/${docSlug}`
+    );
+    const data = {...snapshot.data()};
+    if (!data.sys) {
+      data.sys = {};
+    }
+    data.sys.publishedAt = Timestamp.now();
+    data.sys.publishedBy = options?.publishedBy || 'root-cms-client';
+    batch.set(publishedRef, data);
+    if (commitBatch) {
+      await batch.commit();
+      this.logAction('translations.publish', {metadata: {translationsId}});
+    }
+  }
+
   /**
    * Checks if a doc is currently "locked" for publishing.
    */
@@ -665,8 +714,6 @@ export class RootCMSClient {
     options?: LoadTranslationsOptions
   ): Promise<TranslationsMap> {
     const dbPath = `Projects/${this.projectId}/TranslationsManager/published/Translations`;
-    const query: Query = this.db.collection(dbPath);
-    const snapshot = await query.get();
     const translationsMap: TranslationsMap = {};
 
     const addTranslations = (hash: string, translations: Translation) => {
@@ -676,6 +723,11 @@ export class RootCMSClient {
       );
     };
 
+    let query: Query = this.db.collection(dbPath);
+    if (options?.tags && options.tags.length > 0) {
+      query = query.where('sys.tags', 'array-contains-any', options.tags);
+    }
+    const snapshot = await query.get();
     snapshot.forEach((doc) => {
       const data = doc.data();
       const strings = (data.strings || {}) as Record<string, Translation>;
diff --git a/packages/root-cms/core/compatibility.ts b/packages/root-cms/core/compatibility.ts
index 20ef9be6..87c0aadc 100644
--- a/packages/root-cms/core/compatibility.ts
+++ b/packages/root-cms/core/compatibility.ts
@@ -61,7 +61,7 @@ async function migrateTranslationsToV2(
   querySnapshot.forEach((doc) => {
     const hash = doc.id;
     const translation = doc.data() as Translation;
-    const tags = translation.tags || [];
+    const tags = (translation.tags || []) as string[];
     delete translation.tags;
     for (const tag of tags) {
       if (tag.includes('/')) {
@@ -73,6 +73,7 @@ async function migrateTranslationsToV2(
             modifiedBy: 'root-cms-client',
             publishedAt: Timestamp.now(),
             publishedBy: 'root-cms-client',
+            tags: tags,
           },
           strings: {},
         };
diff --git a/packages/root-cms/ui/db/translations.ts b/packages/root-cms/ui/db/translations.ts
index 599b19c1..4fa5c51b 100644
--- a/packages/root-cms/ui/db/translations.ts
+++ b/packages/root-cms/ui/db/translations.ts
@@ -18,7 +18,6 @@ import {
 import {GoogleSheetId} from '@/utils/gsheets.js';
 import {normalizeString, sourceHash} from '@/utils/l10n.js';
 import {logAction} from './actions.js';
-import {getDraftDocRef} from './docs.js';
 
 export interface Translations {
   [locale: string]: string;

From 9639f5936fbec3d9c3b5a1a71bc55574d1d57619 Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Wed, 16 Oct 2024 20:30:00 -0700
Subject: [PATCH 07/14] feat: [v2] prevent scheduled publishing with past
 date/time

---
 .../DocActionsMenu/DocActionsMenu.tsx         |  2 +-
 .../PublishDocModal/PublishDocModal.tsx       | 28 +++++++++++++++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx b/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx
index 8e4a9a87..5ab96b71 100644
--- a/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx
+++ b/packages/root-cms/ui/components/DocActionsMenu/DocActionsMenu.tsx
@@ -238,7 +238,7 @@ export function DocActionsMenu(props: DocActionsMenuProps) {
         icon={<IconCopy size={20} />}
         onClick={() => copyDocModal.open()}
       >
-        Copy
+        Copy to...
       </Menu.Item>
       {sys.modifiedAt &&
         sys.publishedAt &&
diff --git a/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx b/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx
index 5e6e69b2..9c25d8da 100644
--- a/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx
+++ b/packages/root-cms/ui/components/PublishDocModal/PublishDocModal.tsx
@@ -1,7 +1,7 @@
 import {Accordion, Button, Loader} from '@mantine/core';
 import {ContextModalProps, useModals} from '@mantine/modals';
 import {showNotification} from '@mantine/notifications';
-import {useState, useRef} from 'preact/hooks';
+import {useState, useRef, useEffect} from 'preact/hooks';
 import {DocDiffViewer} from '@/components/DocDiffViewer/DocDiffViewer.js';
 import {Text} from '@/components/Text/Text.js';
 import {dbPublishDoc, dbScheduleDoc} from '@/db/docs.js';
@@ -44,6 +44,19 @@ export function PublishDocModal(
   const modals = useModals();
   const modalTheme = useModalTheme();
 
+  const [currentDateTime, setCurrentDateTime] = useState('');
+
+  // This will update the current date and time every time the component renders.
+  useEffect(() => {
+    const now = new Date();
+    const localISOTime = new Date(
+      now.getTime() - now.getTimezoneOffset() * 60000
+    )
+      .toISOString()
+      .slice(0, 16); // Format to "YYYY-MM-DDTHH:mm"
+    setCurrentDateTime(localISOTime);
+  }, []);
+
   const buttonLabel = publishType === 'scheduled' ? 'Schedule' : 'Publish';
 
   async function publish() {
@@ -70,8 +83,18 @@ export function PublishDocModal(
 
   async function schedule() {
     try {
-      setLoading(true);
       const millis = Math.floor(new Date(scheduledDate).getTime());
+      const now = Math.floor(new Date().getTime());
+      if (millis <= now) {
+        showNotification({
+          title: 'Schedule failed',
+          message: `Failed to schedule ${props.docId}. Please choose a date/time in the future when using the scheduled publishing.`,
+          color: 'red',
+          autoClose: false,
+        });
+        return;
+      }
+      setLoading(true);
       await dbScheduleDoc(props.docId, millis);
       setLoading(false);
       showNotification({
@@ -182,6 +205,7 @@ export function PublishDocModal(
                     ref={dateTimeRef}
                     type="datetime-local"
                     disabled={publishType !== 'scheduled'}
+                    min={currentDateTime}
                     value={scheduledDate}
                     onChange={(e: Event) => {
                       const target = e.target as HTMLInputElement;

From 890485f98f82de594c501fb6e1841cfe8998eb8f Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Thu, 17 Oct 2024 12:18:43 -0700
Subject: [PATCH 08/14] feat: [v2] add cmsRoute() for defining ssg/ssr handlers
 (#435)

---
 docs/routes/[[...page]].tsx                   |   8 +-
 docs/routes/blog.tsx                          |   4 +-
 docs/routes/blog/[...blog].tsx                |  14 +-
 docs/routes/guide/[[...guide]].tsx            |   2 +-
 docs/routes/sandbox/[sandbox].tsx             |   2 +-
 packages/root-cms/core/client.ts              |   2 +-
 .../root-cms/core}/cms-route.ts               | 170 ++++++++++--------
 packages/root-cms/core/core.ts                |   1 +
 packages/root-cms/core/plugin.ts              |   3 +-
 9 files changed, 115 insertions(+), 91 deletions(-)
 rename {docs/utils => packages/root-cms/core}/cms-route.ts (64%)

diff --git a/docs/routes/[[...page]].tsx b/docs/routes/[[...page]].tsx
index 008abda2..df0559a7 100644
--- a/docs/routes/[[...page]].tsx
+++ b/docs/routes/[[...page]].tsx
@@ -1,10 +1,10 @@
+import {cmsRoute} from '@blinkk/root-cms';
 import {
   PageModuleFields,
   PageModules,
-} from '@/components/PageModules/PageModules';
-import {BaseLayout} from '@/layouts/BaseLayout';
-import {PagesDoc} from '@/root-cms';
-import {cmsRoute} from '@/utils/cms-route';
+} from '@/components/PageModules/PageModules.js';
+import {BaseLayout} from '@/layouts/BaseLayout.js';
+import {PagesDoc} from '@/root-cms.js';
 
 export interface PageProps {
   doc: PagesDoc;
diff --git a/docs/routes/blog.tsx b/docs/routes/blog.tsx
index 56292189..25a8f875 100644
--- a/docs/routes/blog.tsx
+++ b/docs/routes/blog.tsx
@@ -1,5 +1,5 @@
-import {cmsRoute} from '@/utils/cms-route';
-import {default as Page} from './blog/[...blog]';
+import {cmsRoute} from '@blinkk/root-cms';
+import {default as Page} from './blog/[...blog].js';
 
 // TODO(stevenle): Create a blog listing page when we have more than 1 post.
 export default Page;
diff --git a/docs/routes/blog/[...blog].tsx b/docs/routes/blog/[...blog].tsx
index 0861b012..5b0b59f5 100644
--- a/docs/routes/blog/[...blog].tsx
+++ b/docs/routes/blog/[...blog].tsx
@@ -1,10 +1,10 @@
-import {CopyBlock} from '@/blocks/CopyBlock/CopyBlock';
-import Block from '@/components/Block/Block';
-import {Container} from '@/components/Container/Container';
-import {Text} from '@/components/Text/Text';
-import {BaseLayout} from '@/layouts/BaseLayout';
-import {BlogPostsDoc} from '@/root-cms';
-import {cmsRoute} from '@/utils/cms-route';
+import {cmsRoute} from '@blinkk/root-cms';
+import {CopyBlock} from '@/blocks/CopyBlock/CopyBlock.js';
+import Block from '@/components/Block/Block.js';
+import {Container} from '@/components/Container/Container.js';
+import {Text} from '@/components/Text/Text.js';
+import {BaseLayout} from '@/layouts/BaseLayout.js';
+import {BlogPostsDoc} from '@/root-cms.js';
 import styles from './[...blog].module.scss';
 
 export interface PageProps {
diff --git a/docs/routes/guide/[[...guide]].tsx b/docs/routes/guide/[[...guide]].tsx
index 62cbd581..140e4d6a 100644
--- a/docs/routes/guide/[[...guide]].tsx
+++ b/docs/routes/guide/[[...guide]].tsx
@@ -1,4 +1,5 @@
 import {RequestContext, useRequestContext, useTranslations} from '@blinkk/root';
+import {cmsRoute} from '@blinkk/root-cms';
 import {IconLayoutSidebarLeftExpand} from '@tabler/icons-preact';
 import Block from '@/components/Block/Block.js';
 import {RichText} from '@/components/RichText/RichText.js';
@@ -8,7 +9,6 @@ import {LogoToggle} from '@/islands/LogoToggle/LogoToggle.js';
 import {BaseLayout} from '@/layouts/BaseLayout.js';
 import {GuideDoc} from '@/root-cms.js';
 import {joinClassNames} from '@/utils/classes.js';
-import {cmsRoute} from '@/utils/cms-route.js';
 import styles from './[[...guide]].module.scss';
 
 const GUIDE_LINKS = [
diff --git a/docs/routes/sandbox/[sandbox].tsx b/docs/routes/sandbox/[sandbox].tsx
index 01c67972..71f89422 100644
--- a/docs/routes/sandbox/[sandbox].tsx
+++ b/docs/routes/sandbox/[sandbox].tsx
@@ -1,4 +1,4 @@
-import {cmsRoute} from '@/utils/cms-route.js';
+import {cmsRoute} from '@blinkk/root-cms';
 import Page from '../[[...page]].js';
 
 export default Page;
diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index cfd02ed0..fa67693e 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import {RootConfig} from '@blinkk/root';
+import type {RootConfig} from '@blinkk/root';
 import {App} from 'firebase-admin/app';
 import {
   FieldValue,
diff --git a/docs/utils/cms-route.ts b/packages/root-cms/core/cms-route.ts
similarity index 64%
rename from docs/utils/cms-route.ts
rename to packages/root-cms/core/cms-route.ts
index 9419719f..744eacd2 100644
--- a/docs/utils/cms-route.ts
+++ b/packages/root-cms/core/cms-route.ts
@@ -6,7 +6,7 @@ import {
   Response,
   RouteParams,
 } from '@blinkk/root';
-import {RootCMSClient, translationsForLocale} from '@blinkk/root-cms/client';
+import {BatchRequest, RootCMSClient} from './client.js';
 
 export type CMSRequest = Request & {
   cmsClient: RootCMSClient;
@@ -37,6 +37,16 @@ export interface CMSRouteOptions {
    */
   slug?: string;
 
+  /**
+   * Hook that allows callers to modify the Root CMS `BatchRequest` object. If a
+   * new `BatchRequest` is returned, it will replace the default one created by
+   * `cmsRoute()`.
+   */
+  preRequestHook?: (
+    batchRequest: BatchRequest,
+    context: CMSRouteContext
+  ) => void | BatchRequest;
+
   /**
    * Callback function that returns a map of Promises that contain fetched data.
    * Once the promise is resolved, the values are injected into page's props
@@ -55,11 +65,6 @@ export interface CMSRouteOptions {
    */
   setResponseHeaders?: (req: Request, res: Response) => void;
 
-  /**
-   * Translations configuration.
-   */
-  translations?: (context: CMSRouteContext) => {tags?: string[]};
-
   /**
    * Sets Cache-Control header to `private`.
    */
@@ -72,13 +77,18 @@ export interface CMSRouteOptions {
 }
 
 export interface CMSDoc {
+  id: string;
+  slug: string;
   sys?: {
     locales?: string[];
   };
 }
 
+/**
+ * Utility for generating SSR and SSG handlers in a Root route file.
+ */
 export function cmsRoute(options: CMSRouteOptions) {
-  let cmsClient: RootCMSClient = null;
+  let cmsClient: RootCMSClient | null = null;
 
   function getSlug(params: RouteParams) {
     if (options.slug) {
@@ -98,27 +108,73 @@ export function cmsRoute(options: CMSRouteOptions) {
     return resolvePromisesMap(promisesMap);
   }
 
-  async function generateProps(routeContext: CMSRouteContext, locale: string) {
+  async function generateProps(
+    routeContext: CMSRouteContext,
+    preferredLocale: string | ((doc: CMSDoc) => string)
+  ) {
     const {slug, mode} = routeContext;
-    const translationsTags = ['common', `${options.collection}/${slug}`];
-    if (options.translations) {
-      const tags = options.translations(routeContext)?.tags || [];
-      translationsTags.push(...tags);
+
+    const primaryDocId = `${options.collection}/${slug}`;
+    let batchRequest = routeContext.cmsClient.createBatchRequest({
+      mode,
+      translate: true,
+    });
+    batchRequest.addDoc(primaryDocId);
+
+    // Call the pre-request hook to allow users to modify the batch request.
+    if (options.preRequestHook) {
+      const overridedBatchRequest = options.preRequestHook(
+        batchRequest,
+        routeContext
+      );
+      if (overridedBatchRequest) {
+        batchRequest = overridedBatchRequest;
+      }
     }
 
-    const [doc, translationsMap, data] = await Promise.all([
-      cmsClient.getDoc<CMSDoc>(options.collection, slug, {
-        mode,
-      }),
-      cmsClient.loadTranslations({tags: translationsTags}),
+    // Fetch the Root CMS BatchRequest in parallel with any other data the
+    // caller needs to fetch to render the route.
+    const [batchRes, data] = await Promise.all([
+      batchRequest.fetch(),
       fetchData(routeContext),
     ]);
+    const doc = batchRes.docs[primaryDocId];
     if (!doc) {
       return {notFound: true};
     }
 
-    const translations = translationsForLocale(translationsMap, locale);
+    // Determine the preferred locale to render.
+    let locale: string;
+    if (typeof preferredLocale === 'string') {
+      locale = preferredLocale;
+    } else {
+      locale = preferredLocale(doc);
+    }
+    const docLocales = doc.sys?.locales || ['en'];
+    if (!locale || !docLocales.includes(locale)) {
+      return {notFound: true};
+    }
+
+    // From the preferred locale, generate a translations map.
+    const i18nFallbacks =
+      routeContext.cmsClient.rootConfig.i18n?.fallbacks || {};
+    const translationFallbackLocales = i18nFallbacks[locale] || [locale];
+    const translations = batchRes.getTranslations(translationFallbackLocales);
+
     let props: any = {...data, locale, mode, slug, doc};
+
+    // For SSR handlers, inject the user's country of origin to props.
+    if (routeContext.req) {
+      const country =
+        getFirstQueryParam(routeContext.req, 'gl') ||
+        routeContext.req.get('x-country-code') ||
+        routeContext.req.get('x-appengine-country') ||
+        null;
+      props.country = country;
+    }
+
+    // Call the pre-render hook which allows a caller to modify props before
+    // it is passed to the route component.
     if (options.preRenderHook) {
       props = await options.preRenderHook(props, routeContext);
     }
@@ -127,8 +183,8 @@ export function cmsRoute(options: CMSRouteOptions) {
   }
 
   // SSG handlers are disabled by default. Pass `{enableSSG: true}` to enable.
-  let getStaticPaths: GetStaticPaths = null;
-  let getStaticProps: GetStaticProps = null;
+  let getStaticPaths: GetStaticPaths | null = null;
+  let getStaticProps: GetStaticProps | null = null;
 
   if (options.enableSSG) {
     getStaticPaths = async (ctx) => {
@@ -138,13 +194,12 @@ export function cmsRoute(options: CMSRouteOptions) {
       if (!cmsClient) {
         cmsClient = new RootCMSClient(ctx.rootConfig);
       }
-      // TODO(stevenle): Add support for mode.
       const mode = 'published';
-      const res = await cmsClient.listDocs(options.collection, {mode});
-      const ssgPaths = [];
-      res.docs.forEach((doc: {slug: string}) => {
+      const res = await cmsClient.listDocs<CMSDoc>(options.collection, {mode});
+      const ssgPaths: Array<{params: Record<string, string>}> = [];
+      res.docs.forEach((doc) => {
         const params: Record<string, string> = {};
-        params[options.slugParam] = doc.slug;
+        params[options.slugParam!] = doc.slug;
         ssgPaths.push({params});
       });
       return {paths: ssgPaths};
@@ -155,10 +210,8 @@ export function cmsRoute(options: CMSRouteOptions) {
         cmsClient = new RootCMSClient(ctx.rootConfig);
       }
       const slug = getSlug(ctx.params);
-      // TODO(stevenle): Add support for mode.
       const mode = 'published';
-      const routeContext: CMSRouteContext = {req: null, slug, mode, cmsClient};
-
+      const routeContext: CMSRouteContext = {slug, mode, cmsClient};
       return generateProps(routeContext, ctx.params.$locale);
     };
   }
@@ -169,9 +222,9 @@ export function cmsRoute(options: CMSRouteOptions) {
     getStaticProps: getStaticProps,
 
     // SSR handler.
-    handle: async (req, res) => {
+    handle: async (req: CMSRequest, res: Response) => {
       if (!cmsClient) {
-        cmsClient = new RootCMSClient(req.rootConfig);
+        cmsClient = new RootCMSClient(req.rootConfig!);
       }
       req.cmsClient = cmsClient;
       const ctx = req.handlerContext as HandlerContext;
@@ -180,57 +233,28 @@ export function cmsRoute(options: CMSRouteOptions) {
         res.setHeader('cache-control', 'private');
         return ctx.render404();
       }
-      const primaryDocId = `${options.collection}/${slug}`;
       const mode = String(req.query.preview) === 'true' ? 'draft' : 'published';
       const routeContext: CMSRouteContext = {req, slug, mode, cmsClient};
 
-      const batchRequest = cmsClient.createBatchRequest({
-        mode,
-        translate: true,
-      });
-      batchRequest.addDoc(primaryDocId);
-
-      const [batchRes, data] = await Promise.all([
-        batchRequest.fetch(),
-        fetchData(routeContext),
-      ]);
-      const doc = batchRes.docs[primaryDocId];
+      function getLocale(doc: CMSDoc) {
+        const docLocales = doc.sys?.locales || ['en'];
+        let locale = ctx.route.locale;
+        if (ctx.route.isDefaultLocale) {
+          locale = ctx.getPreferredLocale(docLocales);
+          if (docLocales.length > 0 && !docLocales.includes(locale)) {
+            locale = docLocales[0];
+          }
+        }
+        return locale;
+      }
 
-      if (!doc) {
+      const resData = await generateProps(routeContext, getLocale);
+      if (resData.notFound) {
         res.setHeader('cache-control', 'private');
         return ctx.render404();
       }
 
-      const sys = doc.sys;
-      const docLocales = sys.locales || ['en'];
-      let locale = ctx.route.locale;
-      if (ctx.route.isDefaultLocale) {
-        locale = ctx.getPreferredLocale(docLocales);
-        if (docLocales.length > 0 && !docLocales.includes(locale)) {
-          locale = docLocales[0];
-        }
-      }
-      const country =
-        getFirstQueryParam(req, 'gl') ||
-        req.get('x-country-code') ||
-        req.get('x-appengine-country') ||
-        null;
-
-      const i18nFallbacks = req.rootConfig.i18n?.fallbacks || {};
-      const translationFallbackLocales = i18nFallbacks[locale] || [locale];
-      const translations = batchRes.getTranslations(translationFallbackLocales);
-      let props: any = {
-        ...data,
-        req,
-        locale,
-        mode,
-        slug,
-        doc,
-        country,
-      };
-      if (options.preRenderHook) {
-        props = await options.preRenderHook(props, routeContext);
-      }
+      const {props, locale, translations} = resData;
 
       if (props.$redirect) {
         const redirectCode = props.$redirectCode || 302;
diff --git a/packages/root-cms/core/core.ts b/packages/root-cms/core/core.ts
index 2cceaa70..47c14e42 100644
--- a/packages/root-cms/core/core.ts
+++ b/packages/root-cms/core/core.ts
@@ -1,3 +1,4 @@
 export * from './client.js';
+export * from './cms-route.js';
 export * from './runtime.js';
 export * as schema from './schema.js';
diff --git a/packages/root-cms/core/plugin.ts b/packages/root-cms/core/plugin.ts
index 6b95066c..bdc31919 100644
--- a/packages/root-cms/core/plugin.ts
+++ b/packages/root-cms/core/plugin.ts
@@ -1,8 +1,7 @@
 import {promises as fs} from 'node:fs';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
-
-import {
+import type {
   ConfigureServerOptions,
   NextFunction,
   Plugin,

From 1dfa6dde00c3f9b26d8b0de1414fc42944598c6d Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Thu, 17 Oct 2024 18:39:13 -0700
Subject: [PATCH 09/14] chore: [v2] bump version to v2

---
 .changeset/moody-worms-draw.md | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 .changeset/moody-worms-draw.md

diff --git a/.changeset/moody-worms-draw.md b/.changeset/moody-worms-draw.md
new file mode 100644
index 00000000..39d47cd5
--- /dev/null
+++ b/.changeset/moody-worms-draw.md
@@ -0,0 +1,10 @@
+---
+'@blinkk/eslint-config-root': major
+'@blinkk/root-cms': major
+'@blinkk/root': major
+'@blinkk/create-root': major
+'@blinkk/rds': major
+'@blinkk/root-password-protect': major
+---
+
+chore: [v2] bump version to v2

From 72cb53019ce7a613070c024939fb83e2145d4708 Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Thu, 17 Oct 2024 18:39:22 -0700
Subject: [PATCH 10/14] chore: [v2] enter rc prerelease

---
 .changeset/pre.json | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 .changeset/pre.json

diff --git a/.changeset/pre.json b/.changeset/pre.json
new file mode 100644
index 00000000..e187e70c
--- /dev/null
+++ b/.changeset/pre.json
@@ -0,0 +1,19 @@
+{
+  "mode": "pre",
+  "tag": "rc",
+  "initialVersions": {
+    "@private/docs": "0.0.0",
+    "@examples/basepath": "0.0.0",
+    "@examples/blog": "0.0.0",
+    "@examples/cms": "0.0.0",
+    "@examples/minimal": "0.0.0",
+    "@examples/starter": "0.0.0",
+    "@blinkk/create-root": "1.3.11",
+    "@blinkk/eslint-config-root": "0.1.0",
+    "@blinkk/rds": "1.3.11",
+    "@blinkk/root": "1.3.11",
+    "@blinkk/root-cms": "1.3.11",
+    "@blinkk/root-password-protect": "1.3.11"
+  },
+  "changesets": []
+}

From 86a003c6fffecde55d30d6395a8869927c9de68f Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Thu, 17 Oct 2024 18:43:28 -0700
Subject: [PATCH 11/14] release: [v2] release v2.0.0-rc.0

---
 .changeset/pre.json                         |  7 ++++++-
 packages/create-root/CHANGELOG.md           |  6 ++++++
 packages/create-root/package.json           |  2 +-
 packages/eslint-config-root/CHANGELOG.md    |  6 ++++++
 packages/eslint-config-root/package.json    |  2 +-
 packages/rds/CHANGELOG.md                   | 13 +++++++++++++
 packages/rds/package.json                   |  4 ++--
 packages/root-cms/CHANGELOG.md              | 15 +++++++++++++++
 packages/root-cms/package.json              |  4 ++--
 packages/root-password-protect/CHANGELOG.md | 13 +++++++++++++
 packages/root-password-protect/package.json |  4 ++--
 packages/root/CHANGELOG.md                  | 11 +++++++++++
 packages/root/package.json                  |  2 +-
 13 files changed, 79 insertions(+), 10 deletions(-)

diff --git a/.changeset/pre.json b/.changeset/pre.json
index e187e70c..13152ad6 100644
--- a/.changeset/pre.json
+++ b/.changeset/pre.json
@@ -15,5 +15,10 @@
     "@blinkk/root-cms": "1.3.11",
     "@blinkk/root-password-protect": "1.3.11"
   },
-  "changesets": []
+  "changesets": [
+    "kind-pans-check",
+    "moody-worms-draw",
+    "strong-planes-float",
+    "twelve-months-explain"
+  ]
 }
diff --git a/packages/create-root/CHANGELOG.md b/packages/create-root/CHANGELOG.md
index 82a6616a..74f26dba 100644
--- a/packages/create-root/CHANGELOG.md
+++ b/packages/create-root/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @blinkk/create-root
 
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 1dfa6dd: chore: [v2] bump version to v2
+
 ## 1.3.12
 
 ## 1.3.11
diff --git a/packages/create-root/package.json b/packages/create-root/package.json
index c6596a6b..948115c8 100644
--- a/packages/create-root/package.json
+++ b/packages/create-root/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/create-root",
-  "version": "1.3.12",
+  "version": "2.0.0-rc.0",
   "description": "",
   "author": "s@blinkk.com",
   "license": "MIT",
diff --git a/packages/eslint-config-root/CHANGELOG.md b/packages/eslint-config-root/CHANGELOG.md
index d987cf26..5cc2f749 100644
--- a/packages/eslint-config-root/CHANGELOG.md
+++ b/packages/eslint-config-root/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @blinkk/eslint-config-root
 
+## 1.0.0-rc.0
+
+### Major Changes
+
+- 1dfa6dd: chore: [v2] bump version to v2
+
 ## 0.1.0
 
 ### Minor Changes
diff --git a/packages/eslint-config-root/package.json b/packages/eslint-config-root/package.json
index 7a9f5724..26447b81 100644
--- a/packages/eslint-config-root/package.json
+++ b/packages/eslint-config-root/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/eslint-config-root",
-  "version": "0.1.0",
+  "version": "1.0.0-rc.0",
   "description": "ESLint config for Root.js projects.",
   "author": "s@blinkk.com",
   "license": "MIT",
diff --git a/packages/rds/CHANGELOG.md b/packages/rds/CHANGELOG.md
index 4892cedc..7c726a73 100644
--- a/packages/rds/CHANGELOG.md
+++ b/packages/rds/CHANGELOG.md
@@ -1,5 +1,18 @@
 # @blinkk/rds
 
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 1dfa6dd: chore: [v2] bump version to v2
+
+### Patch Changes
+
+- Updated dependencies [1dfa6dd]
+- Updated dependencies [f5bd041]
+- Updated dependencies [053bb1c]
+  - @blinkk/root@2.0.0-rc.0
+
 ## 1.3.12
 
 ### Patch Changes
diff --git a/packages/rds/package.json b/packages/rds/package.json
index 20e469cb..1236a445 100644
--- a/packages/rds/package.json
+++ b/packages/rds/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@blinkk/rds",
   "description": "Root.js Design System",
-  "version": "1.3.12",
+  "version": "2.0.0-rc.0",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {
@@ -32,7 +32,7 @@
     "typescript": "^5.0.4"
   },
   "peerDependencies": {
-    "@blinkk/root": "1.3.12",
+    "@blinkk/root": "2.0.0-rc.0",
     "preact": "*"
   },
   "dependencies": {
diff --git a/packages/root-cms/CHANGELOG.md b/packages/root-cms/CHANGELOG.md
index b67dd18f..f4b2bcb1 100644
--- a/packages/root-cms/CHANGELOG.md
+++ b/packages/root-cms/CHANGELOG.md
@@ -1,5 +1,20 @@
 # @blinkk/root-cms
 
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 1dfa6dd: chore: [v2] bump version to v2
+
+### Patch Changes
+
+- f5bd041: feat: [v2] store compatibility versions in db
+- f5bd041: feat: [v2] add compatibility check for v2 translations
+- Updated dependencies [1dfa6dd]
+- Updated dependencies [f5bd041]
+- Updated dependencies [053bb1c]
+  - @blinkk/root@2.0.0-rc.0
+
 ## 1.3.12
 
 ### Patch Changes
diff --git a/packages/root-cms/package.json b/packages/root-cms/package.json
index 9dc9362e..1dfdf69e 100644
--- a/packages/root-cms/package.json
+++ b/packages/root-cms/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/root-cms",
-  "version": "1.3.12",
+  "version": "2.0.0-rc.0",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {
@@ -131,7 +131,7 @@
     "vitest": "0.34.6"
   },
   "peerDependencies": {
-    "@blinkk/root": "1.3.12",
+    "@blinkk/root": "2.0.0-rc.0",
     "firebase-admin": ">=11",
     "firebase-functions": ">=4",
     "preact": ">=10",
diff --git a/packages/root-password-protect/CHANGELOG.md b/packages/root-password-protect/CHANGELOG.md
index d0b5e56a..1abc3aa5 100644
--- a/packages/root-password-protect/CHANGELOG.md
+++ b/packages/root-password-protect/CHANGELOG.md
@@ -1,5 +1,18 @@
 # @blinkk/root-password-protect
 
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 1dfa6dd: chore: [v2] bump version to v2
+
+### Patch Changes
+
+- Updated dependencies [1dfa6dd]
+- Updated dependencies [f5bd041]
+- Updated dependencies [053bb1c]
+  - @blinkk/root@2.0.0-rc.0
+
 ## 1.3.12
 
 ### Patch Changes
diff --git a/packages/root-password-protect/package.json b/packages/root-password-protect/package.json
index 2c9c527c..d8f6e136 100644
--- a/packages/root-password-protect/package.json
+++ b/packages/root-password-protect/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/root-password-protect",
-  "version": "1.3.12",
+  "version": "2.0.0-rc.0",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {
@@ -42,7 +42,7 @@
     "micromatch": "4.0.5"
   },
   "peerDependencies": {
-    "@blinkk/root": "1.3.12",
+    "@blinkk/root": "2.0.0-rc.0",
     "preact": ">=10",
     "preact-render-to-string": ">=5"
   },
diff --git a/packages/root/CHANGELOG.md b/packages/root/CHANGELOG.md
index 040d121a..5c938ee7 100644
--- a/packages/root/CHANGELOG.md
+++ b/packages/root/CHANGELOG.md
@@ -1,5 +1,16 @@
 # @blinkk/root
 
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 1dfa6dd: chore: [v2] bump version to v2
+
+### Patch Changes
+
+- f5bd041: feat: [v2] add compatibility check for v2 translations
+- 053bb1c: feat: [v2] add "startup" hook to plugins
+
 ## 1.3.12
 
 ### Patch Changes
diff --git a/packages/root/package.json b/packages/root/package.json
index 999eadf9..31e47370 100644
--- a/packages/root/package.json
+++ b/packages/root/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/root",
-  "version": "1.3.12",
+  "version": "2.0.0-rc.0",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {

From 8acc09954ade39a41bef8bd19f1dfddd9f4c0737 Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Fri, 18 Oct 2024 10:35:43 -0700
Subject: [PATCH 12/14] fix: [v2] fix conversion of docId to translationsId

---
 packages/root-cms/core/client.ts        | 39 -------------------------
 packages/root-cms/core/compatibility.ts |  2 +-
 2 files changed, 1 insertion(+), 40 deletions(-)

diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index fa67693e..b1c1ec4c 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -739,45 +739,6 @@ export class RootCMSClient {
     return translationsMap;
   }
 
-  /**
-   * Saves a map of translations, e.g.:
-   * ```
-   * await client.saveTranslations({
-   *   "Hello": {"es": "Hola", "fr": "Bonjour"},
-   * });
-   * ```
-   *
-   * @deprecated Use `saveDraftTranslations()` and `publishTranslations()`
-   * instead.
-   */
-  async saveTranslations(
-    translations: {
-      [source: string]: {[locale: string]: string};
-    },
-    tags?: string[]
-  ) {
-    const translationsPath = `Projects/${this.projectId}/Translations`;
-    const batch = this.db.batch();
-    let batchCount = 0;
-    Object.entries(translations).forEach(([source, sourceTranslations]) => {
-      const hash = this.getTranslationKey(source);
-      const translationRef = this.db.doc(`${translationsPath}/${hash}`);
-      const data: any = {
-        ...sourceTranslations,
-        source: this.normalizeString(source),
-      };
-      if (tags) {
-        data.tags = tags;
-      }
-      batch.set(translationRef, data, {merge: true});
-      batchCount += 1;
-    });
-    if (batchCount > 500) {
-      throw new Error('up to 500 translations can be saved at a time.');
-    }
-    await batch.commit();
-  }
-
   async saveDraftTranslations(
     translationsId: string,
     translations: {[source: string]: {[locale: string]: string}},
diff --git a/packages/root-cms/core/compatibility.ts b/packages/root-cms/core/compatibility.ts
index 87c0aadc..91bddf0f 100644
--- a/packages/root-cms/core/compatibility.ts
+++ b/packages/root-cms/core/compatibility.ts
@@ -65,7 +65,7 @@ async function migrateTranslationsToV2(
     delete translation.tags;
     for (const tag of tags) {
       if (tag.includes('/')) {
-        const translationsId = tag;
+        const translationsId = tag.replaceAll('/', '--');
         translationsDocs[translationsId] ??= {
           id: translationsId,
           sys: {

From 364efadbfd35b166b22c1a897a6301ea4462468a Mon Sep 17 00:00:00 2001
From: Steven Le <stevenle08@gmail.com>
Date: Fri, 18 Oct 2024 10:37:24 -0700
Subject: [PATCH 13/14] release: [v2] release v2.0.0-rc.1

---
 .changeset/new-dryers-flow.md               | 9 +++++++++
 .changeset/pre.json                         | 1 +
 packages/create-root/CHANGELOG.md           | 6 ++++++
 packages/create-root/package.json           | 2 +-
 packages/rds/CHANGELOG.md                   | 8 ++++++++
 packages/rds/package.json                   | 4 ++--
 packages/root-cms/CHANGELOG.md              | 8 ++++++++
 packages/root-cms/package.json              | 4 ++--
 packages/root-password-protect/CHANGELOG.md | 8 ++++++++
 packages/root-password-protect/package.json | 4 ++--
 packages/root/CHANGELOG.md                  | 6 ++++++
 packages/root/package.json                  | 2 +-
 12 files changed, 54 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/new-dryers-flow.md

diff --git a/.changeset/new-dryers-flow.md b/.changeset/new-dryers-flow.md
new file mode 100644
index 00000000..7a633494
--- /dev/null
+++ b/.changeset/new-dryers-flow.md
@@ -0,0 +1,9 @@
+---
+'@blinkk/root-password-protect': patch
+'@blinkk/create-root': patch
+'@blinkk/root-cms': patch
+'@blinkk/root': patch
+'@blinkk/rds': patch
+---
+
+release: [v2] release v2.0.0-rc.1
diff --git a/.changeset/pre.json b/.changeset/pre.json
index 13152ad6..78160167 100644
--- a/.changeset/pre.json
+++ b/.changeset/pre.json
@@ -18,6 +18,7 @@
   "changesets": [
     "kind-pans-check",
     "moody-worms-draw",
+    "new-dryers-flow",
     "strong-planes-float",
     "twelve-months-explain"
   ]
diff --git a/packages/create-root/CHANGELOG.md b/packages/create-root/CHANGELOG.md
index 74f26dba..bada6808 100644
--- a/packages/create-root/CHANGELOG.md
+++ b/packages/create-root/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @blinkk/create-root
 
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- release: [v2] release v2.0.0-rc.1
+
 ## 2.0.0-rc.0
 
 ### Major Changes
diff --git a/packages/create-root/package.json b/packages/create-root/package.json
index 948115c8..267ecd07 100644
--- a/packages/create-root/package.json
+++ b/packages/create-root/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/create-root",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.1",
   "description": "",
   "author": "s@blinkk.com",
   "license": "MIT",
diff --git a/packages/rds/CHANGELOG.md b/packages/rds/CHANGELOG.md
index 7c726a73..9e358ecf 100644
--- a/packages/rds/CHANGELOG.md
+++ b/packages/rds/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @blinkk/rds
 
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- release: [v2] release v2.0.0-rc.1
+- Updated dependencies
+  - @blinkk/root@2.0.0-rc.1
+
 ## 2.0.0-rc.0
 
 ### Major Changes
diff --git a/packages/rds/package.json b/packages/rds/package.json
index 1236a445..30a269ee 100644
--- a/packages/rds/package.json
+++ b/packages/rds/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@blinkk/rds",
   "description": "Root.js Design System",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.1",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {
@@ -32,7 +32,7 @@
     "typescript": "^5.0.4"
   },
   "peerDependencies": {
-    "@blinkk/root": "2.0.0-rc.0",
+    "@blinkk/root": "2.0.0-rc.1",
     "preact": "*"
   },
   "dependencies": {
diff --git a/packages/root-cms/CHANGELOG.md b/packages/root-cms/CHANGELOG.md
index f4b2bcb1..17327bad 100644
--- a/packages/root-cms/CHANGELOG.md
+++ b/packages/root-cms/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @blinkk/root-cms
 
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- release: [v2] release v2.0.0-rc.1
+- Updated dependencies
+  - @blinkk/root@2.0.0-rc.1
+
 ## 2.0.0-rc.0
 
 ### Major Changes
diff --git a/packages/root-cms/package.json b/packages/root-cms/package.json
index 1dfdf69e..af71a7de 100644
--- a/packages/root-cms/package.json
+++ b/packages/root-cms/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/root-cms",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.1",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {
@@ -131,7 +131,7 @@
     "vitest": "0.34.6"
   },
   "peerDependencies": {
-    "@blinkk/root": "2.0.0-rc.0",
+    "@blinkk/root": "2.0.0-rc.1",
     "firebase-admin": ">=11",
     "firebase-functions": ">=4",
     "preact": ">=10",
diff --git a/packages/root-password-protect/CHANGELOG.md b/packages/root-password-protect/CHANGELOG.md
index 1abc3aa5..40e92672 100644
--- a/packages/root-password-protect/CHANGELOG.md
+++ b/packages/root-password-protect/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @blinkk/root-password-protect
 
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- release: [v2] release v2.0.0-rc.1
+- Updated dependencies
+  - @blinkk/root@2.0.0-rc.1
+
 ## 2.0.0-rc.0
 
 ### Major Changes
diff --git a/packages/root-password-protect/package.json b/packages/root-password-protect/package.json
index d8f6e136..733188b2 100644
--- a/packages/root-password-protect/package.json
+++ b/packages/root-password-protect/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/root-password-protect",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.1",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {
@@ -42,7 +42,7 @@
     "micromatch": "4.0.5"
   },
   "peerDependencies": {
-    "@blinkk/root": "2.0.0-rc.0",
+    "@blinkk/root": "2.0.0-rc.1",
     "preact": ">=10",
     "preact-render-to-string": ">=5"
   },
diff --git a/packages/root/CHANGELOG.md b/packages/root/CHANGELOG.md
index 5c938ee7..89477f06 100644
--- a/packages/root/CHANGELOG.md
+++ b/packages/root/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @blinkk/root
 
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- release: [v2] release v2.0.0-rc.1
+
 ## 2.0.0-rc.0
 
 ### Major Changes
diff --git a/packages/root/package.json b/packages/root/package.json
index 31e47370..226ca07d 100644
--- a/packages/root/package.json
+++ b/packages/root/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blinkk/root",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.1",
   "author": "s@blinkk.com",
   "license": "MIT",
   "engines": {

From d2371c159bb65953071c18e08d7643e4d2fb0157 Mon Sep 17 00:00:00 2001
From: Steven Le <s@blinkk.com>
Date: Sat, 17 May 2025 06:15:39 -0700
Subject: [PATCH 14/14] refactor: [v2] split translations docs by locale (#438)

* chore: update compatibility to split translations docs by locale
* chore: switch from murmurhash3 to farmhash
* chore: impl TranslationsManager.publishTranslations()
---
 packages/root-cms/core/client.ts              |  32 +-
 packages/root-cms/core/compatibility.ts       |  61 ++-
 .../root-cms/core/translations-manager.ts     | 425 ++++++++++++++++++
 packages/root-cms/core/tsconfig.json          |   1 +
 packages/root-cms/package.json                |   1 +
 packages/root-cms/shared/strings.ts           |  35 ++
 packages/root-cms/ui/tsconfig.json            |   1 +
 .../root/src/core/hooks/useTranslations.ts    |  12 +-
 pnpm-lock.yaml                                |  20 +-
 9 files changed, 526 insertions(+), 62 deletions(-)
 create mode 100644 packages/root-cms/core/translations-manager.ts
 create mode 100644 packages/root-cms/shared/strings.ts

diff --git a/packages/root-cms/core/client.ts b/packages/root-cms/core/client.ts
index b1c1ec4c..484585b0 100644
--- a/packages/root-cms/core/client.ts
+++ b/packages/root-cms/core/client.ts
@@ -8,7 +8,9 @@ import {
   Timestamp,
   WriteBatch,
 } from 'firebase-admin/firestore';
+import {hashStr, normalizeStr} from '../shared/strings.js';
 import {CMSPlugin, getCmsPlugin} from './plugin.js';
+import {TranslationsManager} from './translations-manager.js';
 
 export interface Doc<Fields = any> {
   /** The id of the doc, e.g. "Pages/foo-bar". */
@@ -642,6 +644,19 @@ export class RootCMSClient {
     }
   }
 
+  /**
+   * Returns a `TranslationsManager` object for managing translations.
+   *
+   * To get translations:
+   * ```
+   * await tm.loadTranslations({ids: ['Global/strings', 'Pages/index'], locales: ['es']})
+   *
+   * ```
+   */
+  getTranslationsManager(): TranslationsManager {
+    return new TranslationsManager(this);
+  }
+
   async publishTranslationsDoc(
     translationsId: string,
     options?: {batch?: WriteBatch; publishedBy?: string}
@@ -769,15 +784,10 @@ export class RootCMSClient {
   }
 
   /**
-   * Returns the "key" used for a translation as stored in the db. Translations
-   * are stored under `Projects/<project id>/Translations/<sha1 hash>`.
+   * Returns the hash "key" used for a translation as stored in the db.
    */
-  getTranslationKey(source: string) {
-    const sha1 = crypto
-      .createHash('sha1')
-      .update(this.normalizeString(source))
-      .digest('hex');
-    return sha1;
+  getTranslationKey(str: string) {
+    return hashStr(str);
   }
 
   /**
@@ -786,11 +796,7 @@ export class RootCMSClient {
    * - Removes spaces at the end of any line
    */
   normalizeString(str: string) {
-    const lines = String(str)
-      .trim()
-      .split('\n')
-      .map((line) => line.trimEnd());
-    return lines.join('\n');
+    return normalizeStr(str);
   }
 
   /**
diff --git a/packages/root-cms/core/compatibility.ts b/packages/root-cms/core/compatibility.ts
index 91bddf0f..a6f7e6bb 100644
--- a/packages/root-cms/core/compatibility.ts
+++ b/packages/root-cms/core/compatibility.ts
@@ -22,7 +22,8 @@ export async function runCompatibilityChecks(rootConfig: RootConfig) {
   const compatibilityVersions = projectConfig.compatibility || {};
   let versionsChanged = false;
 
-  const translationsVersion = compatibilityVersions.translations || 0;
+  // const translationsVersion = compatibilityVersions.translations || 0;
+  const translationsVersion = 1;
   if (translationsVersion < 2) {
     await migrateTranslationsToV2(rootConfig, cmsClient);
     compatibilityVersions.translations = 2;
@@ -57,27 +58,22 @@ async function migrateTranslationsToV2(
 
   console.log('[root cms] updating translations v2 compatibility');
 
-  const translationsDocs: Record<string, TranslationsDoc> = {};
+  const translationsDocs: Record<string, any> = {};
   querySnapshot.forEach((doc) => {
-    const hash = doc.id;
-    const translation = doc.data() as Translation;
+    const translation = doc.data();
+    const source = cmsClient.normalizeString(translation.source);
+    delete translation.source;
     const tags = (translation.tags || []) as string[];
     delete translation.tags;
     for (const tag of tags) {
       if (tag.includes('/')) {
-        const translationsId = tag.replaceAll('/', '--');
+        const translationsId = tag;
         translationsDocs[translationsId] ??= {
           id: translationsId,
-          sys: {
-            modifiedAt: Timestamp.now(),
-            modifiedBy: 'root-cms-client',
-            publishedAt: Timestamp.now(),
-            publishedBy: 'root-cms-client',
-            tags: tags,
-          },
+          tags: tags,
           strings: {},
         };
-        translationsDocs[translationsId].strings[hash] = translation;
+        translationsDocs[translationsId].strings[source] = translation;
       }
     }
   });
@@ -88,34 +84,27 @@ async function migrateTranslationsToV2(
   }
 
   // Move the doc's "l10nSheet" to the translations doc's "linkedSheet".
+  // for (const docId in translationsDocs) {
+  //   const [collection, slug] = docId.split('/');
+  //   if (collection && slug) {
+  //     const doc: any = await cmsClient.getDoc(collection, slug, {
+  //       mode: 'draft',
+  //     });
+  //     const linkedSheet = doc?.sys?.l10nSheet;
+  //     if (linkedSheet) {
+  //       translationsDocs[docId].sys.linkedSheet = linkedSheet;
+  //     }
+  //   }
+  // }
 
-  for (const docId in translationsDocs) {
-    const [collection, slug] = docId.split('/');
-    if (collection && slug) {
-      const doc: any = await cmsClient.getDoc(collection, slug, {
-        mode: 'draft',
-      });
-      const linkedSheet = doc?.sys?.l10nSheet;
-      if (linkedSheet) {
-        translationsDocs[docId].sys.linkedSheet = linkedSheet;
-      }
-    }
-  }
-
-  const batch = db.batch();
+  const tm = cmsClient.getTranslationsManager();
   Object.entries(translationsDocs).forEach(([translationsId, data]) => {
-    const draftRef = db.doc(
-      `Projects/${projectId}/TranslationsManager/draft/Translations/${translationsId}`
-    );
-    const publishedRef = db.doc(
-      `Projects/${projectId}/TranslationsManager/published/Translations/${translationsId}`
-    );
-    batch.set(draftRef, data, {merge: true});
-    batch.set(publishedRef, data, {merge: true});
     const len = Object.keys(data.strings).length;
     console.log(`[root cms] saving ${len} string(s) to ${translationsId}...`);
+    tm.saveTranslations(translationsId, data.strings, {
+      tags: data.tags || [translationsId],
+    });
   });
-  await batch.commit();
 
   console.log('[root cms] done migrating translations to v2');
 }
diff --git a/packages/root-cms/core/translations-manager.ts b/packages/root-cms/core/translations-manager.ts
new file mode 100644
index 00000000..45e32c39
--- /dev/null
+++ b/packages/root-cms/core/translations-manager.ts
@@ -0,0 +1,425 @@
+import {
+  FieldValue,
+  Query,
+  Timestamp,
+  WriteBatch,
+} from 'firebase-admin/firestore';
+import {hashStr} from '../shared/strings.js';
+import type {RootCMSClient} from './client.js';
+
+export type Locale = string;
+export type SourceString = string;
+export type TranslatedString = string;
+export type TranslationsDocMode = 'draft' | 'published';
+
+/**
+ * The TranslationsLocaleDoc is the internal doc type stored in the DB. For a
+ * translations doc, the translations for each locale is stored in a separate
+ * doc represented by this type.
+ *
+ * This type is not meant to be used by external callers since this is primarily
+ * an internal implementation detail.
+ */
+interface TranslationsLocaleDoc {
+  id: string;
+  locale: string;
+  tags: string[];
+  strings: TranslationsLocaleDocHashMap;
+  sys: {
+    modifiedAt: Timestamp;
+    modifiedBy: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+    linkedSheet?: {
+      spreadsheetId: string;
+      gid: number;
+      linkedAt: Timestamp;
+      linkedBy: string;
+    };
+  };
+}
+
+export interface TranslationsLocaleDocHashMap {
+  /**
+   * A hash map of a source string's hash fingerprint to the source string and
+   * translated string.
+   */
+  [hash: string]: TranslationsLocaleDocEntry;
+}
+
+export interface TranslationsLocaleDocEntry {
+  source: SourceString;
+  translation: TranslatedString;
+  // TODO(stevenle): in the future we should add an ability for content editors
+  // to provide additional translations notes for translators.
+  // context: string;
+}
+
+interface TranslationsDbPathOptions {
+  project: string;
+  mode: TranslationsDocMode;
+}
+
+type TranslationsLocaleDocDbPathOptions = TranslationsDbPathOptions & {
+  id: string;
+  locale: string;
+};
+
+const TRANSLATIONS_DB_PATH_FORMAT =
+  '/Projects/{project}/TranslationsManager/{mode}/Translations';
+
+const TRANSLATIONS_LOCALE_DOC_DB_PATH_FORMAT = `${TRANSLATIONS_DB_PATH_FORMAT}/{id}:{locale}`;
+
+/**
+ * A translations map containing translations for multiple locales.
+ *
+ * Example:
+ * ```
+ * {
+ *   "one": {"es": "uno", "fr": "un"},
+ *   "two": {"es": "dos", "fr": "deux"}
+ * }
+ * ```
+ */
+export interface MultiLocaleTranslationsMap {
+  [source: SourceString]: {
+    [locale: Locale]: TranslatedString;
+  };
+}
+
+/**
+ * A translations map containing translations for a single locale.
+ *
+ * Example:
+ * ```
+ * {
+ *   "one": "uno",
+ *   "two": "dos"
+ * }
+ * ```
+ */
+export interface SingleLocaleTranslationsMap {
+  [source: SourceString]: TranslatedString;
+}
+
+export class TranslationsManager {
+  cmsClient: RootCMSClient;
+
+  constructor(cmsClient: RootCMSClient) {
+    this.cmsClient = cmsClient;
+  }
+
+  /**
+   * Saves draft translations for a translations doc id.
+   *
+   * Example:
+   * ```
+   * const strings = {
+   *   'one': {es: 'uno', fr: 'un'},
+   *   'two': {es: 'dos', fr: 'deux'},
+   * };
+   * await tm.saveTranslations('Pages/index', strings);
+   * ```
+   */
+  async saveTranslations(
+    id: string,
+    strings: MultiLocaleTranslationsMap,
+    options?: {tags?: string[]; modifiedBy?: string}
+  ) {
+    const mode = 'draft';
+    const localesSet: Set<Locale> = new Set();
+    Object.values(strings).forEach((entry) => {
+      Object.keys(entry).forEach((locale) => {
+        if (locale !== 'source') {
+          localesSet.add(locale);
+        }
+      });
+    });
+
+    const batch = this.cmsClient.db.batch();
+    const locales = Array.from(localesSet);
+    locales.forEach((locale) => {
+      const updates: Record<string, any> = {
+        id: id,
+        locale: locale,
+        sys: {
+          modifiedAt: Timestamp.now(),
+          modifiedBy: options?.modifiedBy || 'root-cms-client',
+        },
+        strings: {},
+      };
+      if (options?.tags && options.tags.length > 0) {
+        updates.tags = FieldValue.arrayUnion(...options.tags);
+      }
+      let numUpdates = 0;
+      const hashMap = this.toLocaleDocHashMap(strings, locale);
+      Object.entries(hashMap).forEach(([hash, translations]) => {
+        Object.entries(translations).forEach(([locale, translation]) => {
+          if (translation) {
+            updates.strings[hash] ??= {};
+            updates.strings[hash][locale] = translation;
+            numUpdates += 1;
+          }
+        });
+      });
+      if (numUpdates > 0) {
+        const localeDocPath = getTranslationsLocaleDocDbPath({
+          project: this.cmsClient.projectId,
+          mode: mode,
+          id: id,
+          locale: locale,
+        });
+        const localeDocRef = this.cmsClient.db.doc(localeDocPath);
+        batch.set(localeDocRef, updates, {merge: true});
+      }
+    });
+    await batch.commit();
+  }
+
+  /**
+   * Publishes a translations doc id.
+   */
+  async publishTranslations(
+    id: string,
+    options?: {batch?: WriteBatch; publishedBy?: string}
+  ) {
+    const db = this.cmsClient.db;
+    const project = this.cmsClient.projectId;
+    const draftPath = getTranslationsDbPath({project, mode: 'draft'});
+    const query = db.collection(draftPath).where('id', '==', id);
+    const res = await query.get();
+    if (res.size === 0) {
+      console.warn(`no translations to publish for ${id}`);
+      return;
+    }
+
+    const batch = options?.batch || db.batch();
+    res.docs.forEach((doc) => {
+      const translationsLocaleDoc = doc.data() as TranslationsLocaleDoc;
+      const sys = {
+        ...translationsLocaleDoc.sys,
+        publishedAt: Timestamp.now(),
+        publishedBy: options?.publishedBy || 'root-cms-client',
+      };
+      batch.update(doc.ref, {sys});
+      const publishedDocPath = getTranslationsLocaleDocDbPath({
+        project,
+        mode: 'published',
+        id: translationsLocaleDoc.id,
+        locale: translationsLocaleDoc.locale,
+      });
+      const publishedDocRef = db.doc(publishedDocPath);
+      batch.set(publishedDocRef, {...translationsLocaleDoc, sys});
+    });
+
+    // If a batch was provided, assume that the caller is responsible for
+    // calling `batch.commit()`.
+    const shouldCommitBatch = !options?.batch;
+    if (shouldCommitBatch) {
+      await batch.commit();
+    }
+  }
+
+  /**
+   * Fetches translations from one or more translations docs in the translations
+   * manager.
+   *
+   * Example:
+   * ```
+   * await tm.loadTranslations();
+   * // =>
+   * // {
+   * //   "one": {"es": "uno", "fr": "un"},
+   * //   "two": {"es": "dos", "fr": "deux"}
+   * // }
+   * ```
+   *
+   * To load a specific set of translations docs by id:
+   * ```
+   * const translationsToLoad = ['Global/strings', 'Global/header', 'Global/footer', 'Pages/index'];
+   * await tm.loadTranslations({ids: translationsToLoad});
+   * // =>
+   * // {
+   * //   "one": {"es": "uno", "fr": "un"},
+   * //   "two": {"es": "dos", "fr": "deux"}
+   * // }
+   * ```
+   *
+   * To load a subset of locales (more performant):
+   * ```
+   * await tm.loadTranslations({locales: ['es']});
+   * // =>
+   * // {
+   * //   "one": {"es": "uno"},
+   * //   "two": {"es": "dos"}
+   * // }
+   * ```
+   */
+  async loadTranslations(options?: {
+    ids?: string[];
+    tags?: string[];
+    locales?: Locale[];
+    mode?: TranslationsDocMode;
+  }) {
+    const mode = options?.mode || 'published';
+    const dbPath = getTranslationsDbPath({
+      project: this.cmsClient.projectId,
+      mode: mode,
+    });
+
+    let query = this.cmsClient.db.collection(dbPath) as Query;
+    if (options?.ids && options.ids.length > 0) {
+      query = query.where('id', 'in', options.ids);
+    }
+    if (options?.tags && options.tags.length > 0) {
+      query = query.where('tags', 'array-contains', options.tags);
+    }
+    if (options?.locales && options.locales.length > 0) {
+      query = query.where('locale', 'in', options.locales);
+    }
+
+    const results = await query.get();
+    const strings: MultiLocaleTranslationsMap = {};
+    results.forEach((result) => {
+      const localeDoc = result.data() as TranslationsLocaleDoc;
+      Object.values(localeDoc.strings || {}).forEach((item) => {
+        strings[item.source] ??= {source: item.source};
+        strings[item.source][localeDoc.locale] = item.translation;
+      });
+    });
+    return strings;
+  }
+
+  /**
+   * Fetches translations for a given locale, with optional fallbacks.
+   * The return value is a map of source string to translated string.
+   *
+   * Example:
+   * ```
+   * await translationsDoc.loadTranslationsForLocale('es');
+   * // =>
+   * // {
+   * //   "one": "uno",
+   * //   "two": "dos",
+   * // }
+   * ```
+   */
+  async loadTranslationsForLocale(
+    locale: Locale,
+    options?: {mode?: TranslationsDocMode; fallbackLocales?: Locale[]}
+  ): Promise<SingleLocaleTranslationsMap> {
+    const localeSet: Set<Locale> = new Set([
+      locale,
+      ...(options?.fallbackLocales || []),
+    ]);
+    const fallbackLocales = Array.from(localeSet);
+    const multiLocaleStrings = await this.loadTranslations({
+      mode: options?.mode,
+      locales: fallbackLocales,
+    });
+    return this.toSingleLocaleMap(multiLocaleStrings, fallbackLocales);
+  }
+
+  /**
+   * Converts a multi-locale translations map to a flat single-locale map,
+   * with optional support for fallback locales.
+   *
+   * ```
+   * const multiLocaleStrings = {
+   *   'one': {es: 'uno', fr: 'un'},
+   *   'two': {es: 'dos', fr: 'deux'}
+   * };
+   * translationsDoc.toSingleLocaleMap(multiLocaleStrings, ['fr']);
+   * // =>
+   * // {
+   * //   "one": "uno",
+   * //   "two": "dos",
+   * // }
+   * ```
+   */
+  private toSingleLocaleMap(
+    multiLocaleStrings: MultiLocaleTranslationsMap,
+    fallbackLocales: Locale[]
+  ): SingleLocaleTranslationsMap {
+    const singleLocaleStrings: SingleLocaleTranslationsMap = {};
+    Object.entries(multiLocaleStrings).forEach(([source, translations]) => {
+      let translation = source;
+      for (const locale of fallbackLocales) {
+        if (translations[locale]) {
+          translation = translations[locale];
+          break;
+        }
+      }
+      singleLocaleStrings[source] = translation;
+    });
+    return singleLocaleStrings;
+  }
+
+  /**
+   * Converts a multi-locale translations map to a single-locale hashed version,
+   * used for storage in in the DB.
+   *
+   * ```
+   * const multiLocaleStrings = {
+   *   'one': {es: 'uno', fr: 'un'},
+   *   'two': {es: 'dos', fr: 'deux'}
+   * };
+   * translationsDoc.toLocaleDocHashMap(multiLocaleStrings, 'es');
+   * // =>
+   * // {
+   * //   "<hash1>": {"source": "one", "translation": "uno"},
+   * //   "<hash2>": {"source": "two", "translation": "dos"},
+   * // }
+   * ```
+   *
+   * One reason for using hashes is because the DB has limits on the number of
+   * chars that can be used as the "key" in a object map.
+   */
+  private toLocaleDocHashMap(
+    multiLocaleStrings: MultiLocaleTranslationsMap,
+    locale: Locale
+  ): TranslationsLocaleDocHashMap {
+    const hashMap: TranslationsLocaleDocHashMap = {};
+    Object.entries(multiLocaleStrings).forEach(([source, translations]) => {
+      const translation = translations[locale];
+      if (translation) {
+        const hash = hashStr(source);
+        hashMap[hash] = {source, translation};
+      }
+    });
+    return hashMap;
+  }
+
+  /**
+   * Combines two locale doc hash maps.
+   */
+  private mergeLocaleDocHashMaps(
+    a: TranslationsLocaleDocHashMap,
+    b: TranslationsLocaleDocHashMap
+  ): TranslationsLocaleDocHashMap {
+    const results: TranslationsLocaleDocHashMap = {...a};
+    Object.entries(b).forEach(([hash, translations]) => {
+      results[hash] = {...results[hash], ...translations};
+    });
+    return results;
+  }
+}
+
+function getTranslationsDbPath(options: TranslationsDbPathOptions) {
+  return TRANSLATIONS_DB_PATH_FORMAT.replace(
+    '{project}',
+    options.project
+  ).replace('{mode}', options.mode);
+}
+
+function getTranslationsLocaleDocDbPath(
+  options: TranslationsLocaleDocDbPathOptions
+) {
+  return TRANSLATIONS_LOCALE_DOC_DB_PATH_FORMAT.replace(
+    '{project}',
+    options.project
+  )
+    .replace('{mode}', options.mode)
+    .replace('{id}', options.id.replaceAll('/', '--'))
+    .replace('{locale}', options.locale);
+}
diff --git a/packages/root-cms/core/tsconfig.json b/packages/root-cms/core/tsconfig.json
index 428be5d8..fa63b44a 100644
--- a/packages/root-cms/core/tsconfig.json
+++ b/packages/root-cms/core/tsconfig.json
@@ -30,5 +30,6 @@
     "**/*.ts",
     "*.tsx",
     "**/*.tsx",
+    "../shared/*.ts"
   ]
 }
diff --git a/packages/root-cms/package.json b/packages/root-cms/package.json
index af71a7de..66c93938 100644
--- a/packages/root-cms/package.json
+++ b/packages/root-cms/package.json
@@ -72,6 +72,7 @@
     "csv-parse": "5.5.2",
     "csv-stringify": "6.4.4",
     "dts-dom": "3.7.0",
+    "farmhash-modern": "1.1.0",
     "jsonwebtoken": "9.0.2",
     "kleur": "4.1.5",
     "sirv": "2.0.3",
diff --git a/packages/root-cms/shared/strings.ts b/packages/root-cms/shared/strings.ts
new file mode 100644
index 00000000..071e95fe
--- /dev/null
+++ b/packages/root-cms/shared/strings.ts
@@ -0,0 +1,35 @@
+/**
+ * Shared utility functions for handling strings.
+ */
+
+import * as farmhash from 'farmhash-modern';
+
+/**
+ * Cleans a source string for use in translations. Performs the following:
+ * - Removes any leading/trailing whitespace
+ * - Removes spaces at the end of any line (including &nbsp;)
+ */
+export function normalizeStr(str: string): string {
+  const lines = str
+    .trim()
+    .split('\n')
+    .map((line) => removeTrailingWhitespace(line));
+  return lines.join('\n');
+}
+
+function removeTrailingWhitespace(str: string) {
+  return str.trimEnd().replace(/&nbsp;$/, '');
+}
+
+/**
+ * Returns a hash fingerprint for a string.
+ *
+ * Note that this hash function is meant to be fast and for collision avoidance
+ * for use in a hash map, but is not intended for cryptographic purposes. For
+ * these reasons farmhash is used here.
+ *
+ * @see https://www.npmjs.com/package/farmhash-modern
+ */
+export function hashStr(str: string): string {
+  return String(farmhash.fingerprint32(normalizeStr(str)));
+}
diff --git a/packages/root-cms/ui/tsconfig.json b/packages/root-cms/ui/tsconfig.json
index e55e4eba..0e3fcb57 100644
--- a/packages/root-cms/ui/tsconfig.json
+++ b/packages/root-cms/ui/tsconfig.json
@@ -36,5 +36,6 @@
     "**/*.ts",
     "*.tsx",
     "**/*.tsx",
+    "../shared/*.ts"
   ]
 }
diff --git a/packages/root/src/core/hooks/useTranslations.ts b/packages/root/src/core/hooks/useTranslations.ts
index 8ca10cb4..e14500ea 100644
--- a/packages/root/src/core/hooks/useTranslations.ts
+++ b/packages/root/src/core/hooks/useTranslations.ts
@@ -37,12 +37,12 @@ export function useTranslations() {
 }
 
 /**
- * Cleans a string that's used for translations. Performs the following:
+ * Cleans a source string for use in translations. Performs the following:
  * - Removes any leading/trailing whitespace
- * - Removes spaces at the end of any line
+ * - Removes spaces at the end of any line (including &nbsp;)
  */
-export function normalizeString(str: string) {
-  const lines = String(str)
+export function normalizeString(str: string): string {
+  const lines = str
     .trim()
     .split('\n')
     .map((line) => removeTrailingWhitespace(line));
@@ -50,7 +50,5 @@ export function normalizeString(str: string) {
 }
 
 function removeTrailingWhitespace(str: string) {
-  return String(str)
-    .trimEnd()
-    .replace(/&nbsp;$/, '');
+  return str.trimEnd().replace(/&nbsp;$/, '');
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2bbee716..8650aec4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -361,6 +361,9 @@ importers:
       dts-dom:
         specifier: 3.7.0
         version: 3.7.0
+      farmhash-modern:
+        specifier: 1.1.0
+        version: 1.1.0
       jsonwebtoken:
         specifier: 9.0.2
         version: 9.0.2
@@ -2536,15 +2539,15 @@ packages:
       '@types/gapi.client.discovery-v1': 0.0.4
     dev: true
 
-  /@maxim_mazurok/gapi.client.drive-v3@0.0.20240604:
-    resolution: {integrity: sha512-omuTEdpzapMZ+zxm0tJgX03ZMOuv3BWDEUnTbC1PuJ4AulZzYWjifKCZ3Qn9AqOHw6z+r9+Je0cw/1xntzgz2g==}
+  /@maxim_mazurok/gapi.client.drive-v3@0.0.20241020:
+    resolution: {integrity: sha512-u3cFTtRj6MC7+ILddrwIXO4EUCqiAstCOabqB+WpntZiXMSk7/PduUAtIBQlDn75rYpLOa9aw/0/roif87qnyQ==}
     dependencies:
       '@types/gapi.client': 1.0.8
       '@types/gapi.client.discovery-v1': 0.0.4
     dev: true
 
-  /@maxim_mazurok/gapi.client.sheets-v4@0.0.20240528:
-    resolution: {integrity: sha512-LZfMEbxfZzSwUSXz25aVMhZfbgU5taq3a3lSb9cJJDeu5L9sdJ6lPUBB0H+hRJCgK8vdRjxurGu1wr6EAzXFNg==}
+  /@maxim_mazurok/gapi.client.sheets-v4@0.0.20241015:
+    resolution: {integrity: sha512-dFQL1ovGZks0i3hJMLAHixeVSsv5x5aeEJmwrRK0/rGBz9LJHFq8AY+RGQl+Da4H7kJaAa8LBJTEhDYC2hs0YQ==}
     dependencies:
       '@types/gapi.client': 1.0.8
       '@types/gapi.client.discovery-v1': 0.0.4
@@ -3372,13 +3375,13 @@ packages:
   /@types/gapi.client.drive-v3@0.0.4:
     resolution: {integrity: sha512-jE37dJ0EzAdY0aJPFOp20xmec/aO0P4HtUIA9k07RMPyedFDOcuMlSac1r0PklwQdgXF7BHaMoObNHNAnwSQUQ==}
     dependencies:
-      '@maxim_mazurok/gapi.client.drive-v3': 0.0.20240604
+      '@maxim_mazurok/gapi.client.drive-v3': 0.0.20241020
     dev: true
 
   /@types/gapi.client.sheets-v4@0.0.4:
     resolution: {integrity: sha512-6kTJ7aDMAElfdQV1XzVJmZWjgbibpa84DMuKuaN8Cwqci/dkglPyHXKvsGrRugmuYvgFYr35AQqwz6j3q8R0dw==}
     dependencies:
-      '@maxim_mazurok/gapi.client.sheets-v4': 0.0.20240528
+      '@maxim_mazurok/gapi.client.sheets-v4': 0.0.20241015
     dev: true
 
   /@types/gapi.client@1.0.8:
@@ -5987,6 +5990,11 @@ packages:
     engines: {'0': node >=0.6.0}
     dev: true
 
+  /farmhash-modern@1.1.0:
+    resolution: {integrity: sha512-6ypT4XfgqJk/F3Yuv4SX26I3doUjt0GTG4a+JgWxXQpxXzTBq8fPUeGHfcYMMDPHJHm3yPOSjaeBwBGAHWXCdA==}
+    engines: {node: '>=18.0.0'}
+    dev: false
+
   /farmhash@3.3.1:
     resolution: {integrity: sha512-XUizHanzlr/v7suBr/o85HSakOoWh6HKXZjFYl5C2+Gj0f0rkw+XTUZzrd9odDsgI9G5tRUcF4wSbKaX04T0DQ==}
     engines: {node: '>=10'}