feat(theme): mirror theme-scoped translations on blue/green deploy

Translations registered via Translate & Adapt (and any caller of the
Translations API) for resources of type ONLINE_STORE_THEME_* are keyed
to a specific theme GID. Blue and Green are distinct permanent themes,
so translations written against the currently-live color do not follow
when the on-deck color is promoted. The previously-live color's
translations are silently stranded, and the storefront reverts to
source-language strings on the next deploy.

This PR adds:

- `shopkeeper theme translations mirror` — a standalone command that
  copies theme-scoped translations from one theme to another.
    * `--from / --to`        explicit override (recovery scenarios where
                             the authoritative-translations theme is no
                             longer [live])
    * `--blue / --green`     derive source = live, target = on-deck via
                             the same getLiveTheme + getOnDeckThemeId
                             helpers `theme deploy` uses
    * `--locale`             restrict to a single locale (default: every
                             non-primary published locale)
    * `--resource-type`      restrict to a single theme-scoped resource
                             type (useful for targeted ops + testing)
    * `--dry-run`            build the write plan, do not register

- Optional auto-step inside `blueGreenDeploy()`, gated on the new
  `--mirror-translations` flag (env: SKR_FLAG_MIRROR_TRANSLATIONS).
  Default-off because most client stores don't use Translate & Adapt
  and paying the pre-flight cost on every deploy isn't justified for
  them. Stores that need it (e.g. Hiya) opt in via env.

Performance:

- Pre-flight short-circuit: before doing the full inventory, compare
  aggregate translation maps for ONLINE_STORE_THEME,
  ONLINE_STORE_THEME_LOCALE_CONTENT, and
  ONLINE_STORE_THEME_SETTINGS_DATA_SECTIONS between source and target.
  If all match per-locale, skip the mirror entirely (~6 queries vs
  the full ~250).
- Source-is-live fast path: when source = live, the type-scoped list
  query returns content + translations directly, so we avoid a
  per-resource source-fetch round-trip (~50% fewer reads).
- Bounded-concurrency parallelism on per-resource target fetches
  (concurrency 8, hand-rolled in src/utilities/concurrency.ts).

Together these bring a typical mirror on Hiya's catalog (~124 theme-
scoped resources) from ~5 minutes to well under a minute.

Auth:

- Requires a Shopify Theme Access password (--password or
  SHOPIFY_CLI_THEME_TOKEN). The token's Theme Access app must include
  read_translations + write_translations scopes; ensureAuthenticatedThemes
  uses the password directly without falling back to OAuth.

Resource scope:

  ONLINE_STORE_THEME
  ONLINE_STORE_THEME_APP_EMBED
  ONLINE_STORE_THEME_JSON_TEMPLATE
  ONLINE_STORE_THEME_LOCALE_CONTENT
  ONLINE_STORE_THEME_SECTION_GROUP
  ONLINE_STORE_THEME_SETTINGS_CATEGORY
  ONLINE_STORE_THEME_SETTINGS_DATA_SECTIONS

Resource-scoped translations (PRODUCT, COLLECTION, METAOBJECT, PAGE,
etc.) are not theme-keyed and survive blue/green without
intervention, so they are intentionally excluded.

Idempotent + safe:

- Skips writes when the target value already matches the source.
- Skips keys whose source content has been removed on the target, or
  whose digest no longer matches between deploys.
- Refuses to mirror a theme onto itself.
- Anchoring on explicit `--from` / `--to` is intentional: in recovery
  scenarios the most-up-to-date translations may live on a no-longer-
  live theme. Deriving direction from [live] would invert the mirror
  and overwrite the freshly-edited theme with stale data.

Tests: 164 passing. New coverage in services/theme/translations.test.ts
covers resolveThemes flag matrix, password requirement, sourceIsLive
detection, digest-match registration, idempotent skip, dry-run,
target-resource-absent, locale/resource-type filters, and the
pre-flight skip + full-mirror-on-mismatch behavior. Deploy tests
updated to assert default-off and explicit opt-in.

Author: grantkang5

docs/commands/readme.md

@@ -44,6 +44,12 @@ export default class Deploy extends ThemeCommand {
         },
       ],
     }),
+    'mirror-translations': Flags.boolean({
+      description:
+        'Opt-in. Before deploying code, mirror theme-scoped translations (Translate & Adapt template / locale-content / settings translations) from the currently-live theme onto the on-deck theme. Default off; most stores do not register theme-scoped translations, and the pre-flight cost is not justified for them. Stores that use Translate & Adapt should enable this via SKR_FLAG_MIRROR_TRANSLATIONS=true.',
+      default: false,
+      env: 'SKR_FLAG_MIRROR_TRANSLATIONS',
+    }),
   }
 
   async run(): Promise<void> {
@@ -60,6 +66,7 @@ export default class Deploy extends ThemeCommand {
       strategy: flags.strategy,
       green: flags.green,
       blue: flags.blue,
+      mirrorTranslations: flags['mirror-translations'],
     }
     await deploy(deployFlags)
   }

oclif.manifest.json

@@ -0,0 +1,82 @@
+import {Flags} from '@oclif/core'
+import {globalFlags} from '@shopify/cli-kit/node/cli'
+import BaseCommand from '@shopify/cli-kit/node/base-command'
+import {themeFlags} from '../../../utilities/shopify/flags.js'
+import {mirrorTranslations, MirrorTranslationsFlags} from '../../../services/theme/translations.js'
+
+export default class Mirror extends BaseCommand {
+  static description =
+    'Mirror theme-scoped translations from one theme to another. Translations registered via the Translate & Adapt app (or any caller of translationsRegister) are keyed to a specific theme GID and do NOT migrate between themes — so a blue/green deploy strands them on the previously-live color unless something explicitly carries them across. This command does that.'
+
+  static examples = [
+    {
+      description: 'Mirror live -> on-deck before a blue/green deploy (standard use):',
+      command: '<%= config.bin %> <%= command.id %> --blue 134599540817 --green 134599737425',
+    },
+    {
+      description: 'Recover translations stranded on a no-longer-live theme:',
+      command: '<%= config.bin %> <%= command.id %> --from 134599540817 --to 134599737425',
+    },
+    {
+      description: 'Dry-run (print plan without writing):',
+      command: '<%= config.bin %> <%= command.id %> --blue 1 --green 2 --dry-run',
+    },
+  ]
+
+  static flags = {
+    ...globalFlags,
+    store: themeFlags.store,
+    password: themeFlags.password,
+    environment: themeFlags.environment,
+    from: Flags.integer({
+      description:
+        'Source theme ID. When provided, must be combined with --to. Use this to anchor the mirror direction explicitly (e.g. for recovery scenarios where the most-up-to-date translation source is no longer [live]).',
+      env: 'SKR_FLAG_FROM_THEME_ID',
+    }),
+    to: Flags.integer({
+      description: 'Target theme ID. When provided, must be combined with --from.',
+      env: 'SKR_FLAG_TO_THEME_ID',
+    }),
+    blue: Flags.integer({
+      description:
+        'Blue theme ID. Used when --from/--to are not provided: live theme becomes source, on-deck becomes target.',
+      env: 'SKR_FLAG_BLUE_THEME_ID',
+    }),
+    green: Flags.integer({
+      description: 'Green theme ID. Pairs with --blue.',
+      env: 'SKR_FLAG_GREEN_THEME_ID',
+    }),
+    locale: Flags.string({
+      description: 'Mirror only this locale (e.g. "fr"). Defaults to every published non-primary locale on the store.',
+      env: 'SKR_FLAG_LOCALE',
+    }),
+    'resource-type': Flags.string({
+      description:
+        'Restrict the mirror to a single theme-scoped resource type. Useful for targeted ops or testing. Allowed: ONLINE_STORE_THEME, ONLINE_STORE_THEME_APP_EMBED, ONLINE_STORE_THEME_JSON_TEMPLATE, ONLINE_STORE_THEME_LOCALE_CONTENT, ONLINE_STORE_THEME_SECTION_GROUP, ONLINE_STORE_THEME_SETTINGS_CATEGORY, ONLINE_STORE_THEME_SETTINGS_DATA_SECTIONS.',
+      env: 'SKR_FLAG_RESOURCE_TYPE',
+    }),
+    'dry-run': Flags.boolean({
+      description: 'Build the write plan and print a summary, but do not invoke translationsRegister.',
+      env: 'SKR_FLAG_DRY_RUN',
+      default: false,
+    }),
+  }
+
+  async run(): Promise<void> {
+    const {flags} = await this.parse(Mirror)
+    const serviceFlags: MirrorTranslationsFlags = {
+      store: flags.store,
+      password: flags.password,
+      from: flags.from,
+      to: flags.to,
+      blue: flags.blue,
+      green: flags.green,
+      locale: flags.locale,
+      resourceType: flags['resource-type'],
+      dryRun: flags['dry-run'],
+      noColor: flags['no-color'],
+      verbose: flags.verbose,
+    }
+    await mirrorTranslations(serviceFlags)
+  }
+}

src/commands/theme/deploy.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, test, vi } from 'vitest'
+import {beforeEach, describe, expect, test, vi} from 'vitest'
 import {
   basicDeploy,
   blueGreenDeploy,
@@ -8,16 +8,17 @@ import {
   getOnDeckThemeId,
   gitHeadHash,
 } from './deploy.js'
-import { findPathUp } from '@shopify/cli-kit/node/fs'
-import { getLatestGitCommit } from '@shopify/cli-kit/node/git'
-import { BLUE_GREEN_STRATEGY } from '../../utilities/constants.js'
-import { Theme } from '@shopify/cli-kit/node/themes/types'
-import { outputInfo } from '@shopify/cli-kit/node/output'
-import { themeUpdate } from '@shopify/cli-kit/node/themes/api'
-import { deployToLive, deployTheme, pullLiveThemeSettings } from '../../utilities/theme.js'
-import { findThemes } from '../../utilities/shopify/theme-selector.js'
-import { ensureAuthenticatedThemes } from '@shopify/cli-kit/node/session'
-import { getThemeStore } from '../../utilities/shopify/services/local-storage.js'
+import {findPathUp} from '@shopify/cli-kit/node/fs'
+import {getLatestGitCommit} from '@shopify/cli-kit/node/git'
+import {BLUE_GREEN_STRATEGY} from '../../utilities/constants.js'
+import {Theme} from '@shopify/cli-kit/node/themes/types'
+import {outputInfo} from '@shopify/cli-kit/node/output'
+import {themeUpdate} from '@shopify/cli-kit/node/themes/api'
+import {deployToLive, deployTheme, pullLiveThemeSettings} from '../../utilities/theme.js'
+import {findThemes} from '../../utilities/shopify/theme-selector.js'
+import {ensureAuthenticatedThemes} from '@shopify/cli-kit/node/session'
+import {getThemeStore} from '../../utilities/shopify/services/local-storage.js'
+import {mirrorTranslations} from './translations.js'
 
 vi.mock('@shopify/cli-kit/node/fs')
 vi.mock('@shopify/cli-kit/node/git')
@@ -27,13 +28,14 @@ vi.mock('@shopify/cli-kit/node/session')
 vi.mock('../../utilities/shopify/theme-selector.js')
 vi.mock('../../utilities/theme.js')
 vi.mock('../../utilities/shopify/services/local-storage.js')
+vi.mock('./translations.js')
 
 describe('deploy', () => {
-  const adminSession = { token: 'ABC', storeFqdn: 'example.myshopify.com' }
+  const adminSession = {token: 'ABC', storeFqdn: 'example.myshopify.com'}
   const path = '/my-theme'
 
   function theme(id: number, role: string) {
-    return { id, role, name: `theme (${id})` } as Theme
+    return {id, role, name: `theme (${id})`} as Theme
   }
 
   beforeEach(async () => {
@@ -42,7 +44,7 @@ describe('deploy', () => {
 
   describe('deploy', () => {
     describe('when blue/green strategy', () => {
-      test('makes blue/green deploy', async () => {
+      test('makes blue/green deploy without mirroring translations by default', async () => {
         // Given
         const green = 1
         const blue = 2
@@ -74,12 +76,90 @@ describe('deploy', () => {
         await deploy(flags)
 
         // Then
-        expect(outputInfo).toHaveBeenCalledTimes(2)
         expect(outputInfo).toHaveBeenCalledWith('Pulling theme settings')
         expect(pullLiveThemeSettings).toBeCalledWith(flags)
+        expect(mirrorTranslations).not.toHaveBeenCalled()
         expect(deployTheme).toBeCalledWith(green, flags)
         expect(outputInfo).toHaveBeenCalledWith('Green renamed to [BABCD123] Production - Green')
       })
+
+      test('mirrors translations when mirrorTranslations is set', async () => {
+        // Given
+        const green = 1
+        const blue = 2
+        const liveTheme = theme(blue, 'main')
+        const themes = [theme(green, 'unpublished'), liveTheme]
+        vi.mocked(getThemeStore).mockReturnValue('')
+        vi.mocked(ensureAuthenticatedThemes).mockResolvedValue(adminSession)
+        vi.mocked(findThemes).mockResolvedValue([liveTheme])
+        vi.mocked(themeUpdate).mockResolvedValue(themes[1])
+        vi.mocked(findPathUp).mockResolvedValue('path')
+        vi.mocked(getLatestGitCommit).mockResolvedValue({
+          hash: 'BABCD1234AB',
+          date: '',
+          message: '',
+          refs: '',
+          body: '',
+          author_name: '',
+          author_email: '',
+        })
+        const flags: DeployFlags = {
+          store: 'test',
+          green: green,
+          blue: blue,
+          strategy: BLUE_GREEN_STRATEGY,
+          publish: false,
+          mirrorTranslations: true,
+        }
+
+        // When
+        await deploy(flags)
+
+        // Then
+        expect(mirrorTranslations).toBeCalledWith({
+          store: 'test',
+          password: undefined,
+          from: blue,
+          to: green,
+        })
+        expect(deployTheme).toBeCalledWith(green, flags)
+      })
+
+      test('continues deploy when translation mirror throws', async () => {
+        // Given
+        const green = 1
+        const blue = 2
+        const liveTheme = theme(blue, 'main')
+        vi.mocked(getThemeStore).mockReturnValue('')
+        vi.mocked(ensureAuthenticatedThemes).mockResolvedValue(adminSession)
+        vi.mocked(findThemes).mockResolvedValue([liveTheme])
+        vi.mocked(themeUpdate).mockResolvedValue(theme(green, 'unpublished'))
+        vi.mocked(findPathUp).mockResolvedValue('path')
+        vi.mocked(getLatestGitCommit).mockResolvedValue({
+          hash: 'BABCD1234AB',
+          date: '',
+          message: '',
+          refs: '',
+          body: '',
+          author_name: '',
+          author_email: '',
+        })
+        vi.mocked(mirrorTranslations).mockRejectedValue(new Error('admin API down'))
+        const flags: DeployFlags = {
+          store: 'test',
+          green: green,
+          blue: blue,
+          strategy: BLUE_GREEN_STRATEGY,
+          publish: false,
+          mirrorTranslations: true,
+        }
+
+        // When
+        await deploy(flags)
+
+        // Then — the code deploy should still happen even if translation mirror failed
+        expect(deployTheme).toBeCalledWith(green, flags)
+      })
     })
 
     describe('when no strategy is passsed', () => {
@@ -144,15 +224,23 @@ describe('deploy', () => {
         blue: blue,
         strategy: BLUE_GREEN_STRATEGY,
         publish: false,
+        mirrorTranslations: true,
       }
 
       // When
       await blueGreenDeploy(flags)
 
       // Then
-      expect(outputInfo).toHaveBeenCalledTimes(2)
+      expect(outputInfo).toHaveBeenCalledTimes(3)
       expect(outputInfo).toHaveBeenCalledWith('Pulling theme settings')
+      expect(outputInfo).toHaveBeenCalledWith('Mirroring theme-scoped translations from live to on-deck')
       expect(pullLiveThemeSettings).toBeCalledWith(flags)
+      expect(mirrorTranslations).toBeCalledWith({
+        store: undefined,
+        password: undefined,
+        from: blue,
+        to: green,
+      })
       expect(deployTheme).toBeCalledWith(green, flags)
       expect(outputInfo).toHaveBeenCalledWith('Green renamed to [BABCD123] Production - Green')
     })
@@ -220,7 +308,9 @@ describe('deploy', () => {
         }
 
         // Then
-        await expect(errorFunc).rejects.toThrowError(/Something very bad has happened. The store doesn't have a live theme./)
+        await expect(errorFunc).rejects.toThrowError(
+          /Something very bad has happened. The store doesn't have a live theme./,
+        )
       })
     })
   })

src/commands/theme/translations/mirror.ts

@@ -5,9 +5,10 @@ import {getLatestGitCommit} from '@shopify/cli-kit/node/git'
 import {deployToLive, deployTheme as deployTheme, pullLiveThemeSettings} from '../../utilities/theme.js'
 import {findPathUp} from '@shopify/cli-kit/node/fs'
 import {BLUE_GREEN_STRATEGY} from '../../utilities/constants.js'
-import {outputInfo} from '@shopify/cli-kit/node/output'
+import {outputInfo, outputWarn} from '@shopify/cli-kit/node/output'
 import {findThemes} from '../../utilities/shopify/theme-selector.js'
 import {ensureThemeStore} from '../../utilities/shopify/theme-store.js'
+import {mirrorTranslations as runMirrorTranslations} from './translations.js'
 
 type OnDeckTheme = {
   id: number
@@ -48,6 +49,21 @@ export interface DeployFlags {
   strategy: string
   blue?: number
   green?: number
+
+  /**
+   * Opt-in. When true, mirror theme-scoped translations (Translate & Adapt
+   * template / locale-content / settings translations) from the currently-
+   * live theme onto the on-deck theme before deploying code. Translations
+   * registered via the Translations API are keyed to a theme GID, so without
+   * this step they are stranded on the previously-live color and disappear
+   * from the storefront on promotion.
+   *
+   * Default-off because most client stores don't use Translate & Adapt and
+   * paying the (cheap, but non-zero) pre-flight cost on every deploy isn't
+   * justified for them. Stores that do use it (Hiya) should set
+   * SKR_FLAG_MIRROR_TRANSLATIONS=true in their deploy environment.
+   */
+  mirrorTranslations?: boolean
 }
 
 export async function deploy(flags: DeployFlags) {
@@ -72,6 +88,24 @@ export async function blueGreenDeploy(flags: DeployFlags) {
 
   const liveThemeId = await getLiveTheme(adminSession)
   const onDeckTheme = getOnDeckThemeId(liveThemeId, blue!, green!)
+
+  if (flags.mirrorTranslations) {
+    try {
+      outputInfo('Mirroring theme-scoped translations from live to on-deck')
+      await runMirrorTranslations({
+        store: flags.store,
+        password: flags.password,
+        from: liveThemeId,
+        to: onDeckTheme.id,
+      })
+    } catch (error) {
+      outputWarn(
+        `Failed to mirror theme translations before deploy. Theme-scoped translations registered via Translate & Adapt on the previously-live theme may not appear after this deploy promotes ${onDeckTheme.name}.`,
+      )
+      outputWarn(error instanceof Error ? error.message : String(error))
+    }
+  }
+
   await deployTheme(onDeckTheme.id, flags)
 
   const headSHA = await gitHeadHash()