@shopify/ui-extensions-server-kit 0.0.0-experimental-20260902222805

package/src/i18n.test.ts

@@ -0,0 +1,417 @@
+import {flattenDevExtensionTranslations, resolveDevExtensionLocale, getFlattenedLocalization} from './i18n'
+
+/**
+ * These tests were adapted from https://github.com/Shopify/checkout-web/blob/master/app/utilities/development-mode/tests/i18n-utilities.test.tsx
+ * */
+
+describe('resolveDevExtensionLocale()', () => {
+  test('returns the user locale if it is provided as a supported locale', () => {
+    const userLocale = 'fr-FR'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+        'fr-FR': {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale})
+
+    expect(extensionLocale).toBe(userLocale)
+  })
+
+  test('returns the non-regional user locale if there is no exact match with user locale', async () => {
+    const userLocale = 'de-DE'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+        'fr-FR': {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale})
+
+    expect(extensionLocale).toBe(userLocale.split('-')[0])
+  })
+
+  test("returns the shop locale if it is provided as a supported locale and there isn't a match for the user locale", () => {
+    const shopLocale = 'fr-FR'
+    const userLocale = 'de-DE'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        'fr-FR': {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale, shop: shopLocale})
+
+    expect(extensionLocale).toBe(shopLocale)
+  })
+
+  test("returns the non-regional shop locale if it is provided as a supported locale and there isn't a match for the user locale", async () => {
+    const userLocale = 'ja-JP'
+    const shopLocale = 'de-DE'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale, shop: shopLocale})
+
+    expect(extensionLocale).toBe(shopLocale.split('-')[0])
+  })
+
+  test('returns the default translation locale when no full or partial match can be for neither user nor shop locale made', async () => {
+    const userLocale = 'en-US'
+    const shopLocale = 'ja'
+    const defaultLocale = 'fi'
+
+    const localization = {
+      defaultLocale,
+      lastUpdated: Date.now(),
+      translations: {
+        'en-CA': {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+        fi: {
+          greetings: {
+            hello: 'Hei',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale, shop: shopLocale})
+
+    expect(extensionLocale).toBe(defaultLocale)
+  })
+})
+
+describe('flattenDevExtensionTranslations()', () => {
+  test('returns flattened translation keys using a single locale', () => {
+    const resolvedLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Hello',
+    })
+  })
+
+  test('returns flattened and merged translations with fallbacks for missing keys from the default locale', () => {
+    const resolvedLocale = 'en-GB'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+          },
+        },
+        'en-GB': {
+          greetings: {
+            hello: 'Hello, UK',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Hello, UK',
+      'greetings.goodbye': 'Goodbye',
+    })
+  })
+
+  test('returns flattened and merged translations based on exact match for locale translation', () => {
+    const resolvedLocale = 'fr-CA'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+            goodbye: 'Au revoir',
+          },
+        },
+        'fr-CA': {
+          greetings: {
+            hello: 'Bonjour, Canada',
+            goodbye: 'Au revoir, Canada',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Bonjour, Canada',
+      'greetings.goodbye': 'Au revoir, Canada',
+    })
+  })
+
+  test('returns flattened and merged translations based on non-regional match for locale translation', () => {
+    const resolvedLocale = 'fr-CA'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+            sorry: 'Sorry',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+            goodbye: 'Au revoir',
+            sorry: 'Désolé',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Bonjour',
+      'greetings.goodbye': 'Au revoir',
+      'greetings.sorry': 'Désolé',
+    })
+  })
+
+  test('returns the flattened default locale where no locale match is possible (full or non-regional)', () => {
+    const resolvedLocale = 'de'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+            sorry: 'Sorry',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+            goodbye: 'Au revoir',
+            sorry: 'Désolé',
+          },
+        },
+        'de-DE': {
+          greetings: {
+            hello: 'Hallo',
+            goodbye: 'Auf Wiedersehen',
+            sorry: ' Entschuldigung',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Hello',
+      'greetings.goodbye': 'Goodbye',
+      'greetings.sorry': 'Sorry',
+    })
+  })
+
+  test('returns flattened translations with pluralizations', () => {
+    const resolvedLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          pluralExample: {
+            one: 'You have {{count}} apple',
+            other: 'You have {{count}} apples',
+          },
+          example: {
+            of: {
+              nestedTranslation: 'This is a nested translation only in the default locale',
+              anotherNestedTranslation: 'This is another nested translation defined in the default locale',
+            },
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'pluralExample.one': 'You have {{count}} apple',
+      'pluralExample.other': 'You have {{count}} apples',
+      'example.of.nestedTranslation': 'This is a nested translation only in the default locale',
+      'example.of.anotherNestedTranslation': 'This is another nested translation defined in the default locale',
+    })
+  })
+})
+
+describe('getFlattenedLocalization()', () => {
+  test('returns flattened translations string and resolved extension locale when locales options are provided', () => {
+    const userLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+      },
+    }
+
+    const flattenedLocalization = getFlattenedLocalization(localization, {user: userLocale})
+
+    expect(flattenedLocalization).toStrictEqual({
+      extensionLocale: userLocale,
+      translations: '{"greetings.hello":"Hello"}',
+      lastUpdated: localization.lastUpdated,
+    })
+  })
+
+  test('return undefined when locales options are not provided', () => {
+    const userLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+      },
+    }
+
+    const flattenedLocalization = getFlattenedLocalization(localization)
+
+    expect(flattenedLocalization).toBeUndefined()
+  })
+
+  test('return undefined when localization is null', () => {
+    const userLocale = 'en'
+    const flattenedLocalization = getFlattenedLocalization(null, {user: userLocale})
+
+    expect(flattenedLocalization).toBeUndefined()
+  })
+
+  test('return flattened localization if localization is already flattened', () => {
+    const userLocale = 'en'
+
+    const localization = {
+      extensionLocale: userLocale,
+      lastUpdated: Date.now(),
+      translations: '{"greetings.hello":"Hello"}',
+    }
+
+    const flattenedLocalization = getFlattenedLocalization(localization, {user: userLocale})
+
+    expect(flattenedLocalization).toStrictEqual(localization)
+  })
+})

package/src/i18n.ts

@@ -0,0 +1,205 @@
+/**
+ * These translation utilities were adapted from https://github.com/Shopify/checkout-web/blob/master/app/utilities/development-mode/i18n-utilities.tsx
+ * */
+
+type Translation = string | {[key: string]: Translation}
+
+export interface Localization {
+  defaultLocale: string
+  translations: Record<string, Record<string, Translation>>
+  lastUpdated: number
+}
+
+export interface FlattenedLocalization {
+  extensionLocale: string
+  translations: string
+  lastUpdated: number
+}
+
+export interface LocalesOptions {
+  user: string
+  shop?: string
+}
+
+interface TranslationDictionary {
+  [key: string]: string | TranslationDictionary
+}
+
+/**
+ * This is a flattened dictionary of extension translations for the active locale.
+ *
+ * Here are some examples for the 'en' locale.
+ *
+ * Nested keys are dot separated. Consider this translation definition:
+ *
+ * ```
+ * {
+ *   "greetings": {
+ *     "hello": "Hello {{user}}"
+ *   }
+ * }
+ * ```
+ *
+ * It would be represented in this flattened dictionary as:
+ * ```
+ * {
+ *   "greetings.hello": "Hello {{user}}"
+ * }
+ * ```
+ * Pluralized translations will also be flattened. Consider this definition:
+ * ```
+ * {
+ *   "loyaltyPointsRemaining": {
+ *     "one": "You have {{count}} loyalty point",
+ *     "other": "You have {{count}} loyalty points",
+ *   }
+ * }
+ * ```
+ * It would be represented in this flattened dictionary as:
+ * ```
+ * {
+ *   "loyaltyPointsRemaining.one":  "You have {{count}} loyalty point",
+ *   "loyaltyPointsRemaining.other": "You have {{count}} loyalty points",
+ * }
+ * ```
+ */
+type ExtensionTranslationMap = Record<string, string>
+
+export const TRANSLATED_KEYS = ['localization', 'name', 'description']
+/**
+ * From a nested dictionary like the following :
+ *
+ * ```typescript
+ * const dictionary = {
+ *   Foo: {
+ *     Bar: {
+ *        fooBar: 'something'
+ *     }
+ *   }
+ * }
+ *
+ * Returns a map containing this pair : {'Foo.Bar.fooBar': 'something'}
+ * ```
+ */
+function dictionaryToFlatMap(dictionary: TranslationDictionary) {
+  const map = new Map<string, string>()
+
+  traverseDictionary(dictionary, (key, value) => map.set(key, value))
+
+  return map
+}
+
+function traverseDictionary(
+  dictionary: TranslationDictionary,
+  callback: (key: string, value: string) => void,
+  keyPrefix?: string,
+) {
+  Object.keys(dictionary).forEach((key: string) => {
+    const value = dictionary[key]
+    const translationKey = keyPrefix ? `${keyPrefix}.${key}` : key
+
+    if (value == null) {
+      return
+    }
+
+    if (typeof value === 'string') {
+      callback(translationKey, value)
+    } else {
+      traverseDictionary(value, callback, translationKey)
+    }
+  })
+}
+
+export function flattenDevExtensionTranslations(localization: Localization, locale: string): ExtensionTranslationMap {
+  const defaultTranslations = getFlatMap(localization.translations[localization.defaultLocale])
+
+  const nonRegionalLocale = getNonRegionalLocale(locale)
+  const nonRegionalTranslations = getFlatMap(localization.translations[nonRegionalLocale])
+
+  const userLocaleTranslations = getFlatMap(localization.translations[locale])
+
+  return convertMapToExtensionTranslationMap(
+    new Map([...defaultTranslations, ...nonRegionalTranslations, ...userLocaleTranslations]),
+  )
+}
+
+function getFlatMap(translationDictionary: TranslationDictionary | undefined) {
+  if (translationDictionary) {
+    return dictionaryToFlatMap(translationDictionary)
+  }
+  return new Map<string, string>()
+}
+
+export function resolveDevExtensionLocale(
+  localization: Localization,
+  locales: {
+    user: string
+    shop?: string
+  },
+): string {
+  const extensionLocales = new Set(Object.keys(localization.translations))
+
+  // 0. If no translations, use the user's locale
+  if (extensionLocales.size === 0) return locales.user
+
+  // 1. Attempt to match the user's locale exactly
+  if (extensionLocales.has(locales.user)) return locales.user
+
+  // 2. Attempt to match the non-regional part of the user's locale (i.e. 'fr-CA' becomes 'fr')
+  const nonRegionalUserLocale = getNonRegionalLocale(locales.user)
+  if (extensionLocales.has(nonRegionalUserLocale)) return nonRegionalUserLocale
+
+  // 3. Attempt to match the shop's default locale exactly
+  if (locales.shop && extensionLocales.has(locales.shop)) return locales.shop
+
+  // 4. Attempt to match the non-regional part of the shop's default locale (i.e. 'fr-CA' becomes 'fr')
+  const nonRegionalShopLocale = locales.shop && getNonRegionalLocale(locales.shop)
+  if (nonRegionalShopLocale && extensionLocales.has(nonRegionalShopLocale)) return nonRegionalShopLocale
+
+  // 5. Finally, return the default locale as a fallback
+  return localization.defaultLocale
+}
+
+function convertMapToExtensionTranslationMap(map: Map<string, string>): ExtensionTranslationMap {
+  const extTransMap: ExtensionTranslationMap = {}
+  for (const [key, value] of map) {
+    extTransMap[key] = value
+  }
+  return extTransMap
+}
+
+function getNonRegionalLocale(locale: string): string {
+  return locale.split('-')[0]
+}
+
+export function getFlattenedLocalization(
+  localization?: FlattenedLocalization | Localization | null,
+  locales?: LocalesOptions,
+) {
+  if (!localization || !locales) {
+    return
+  }
+
+  if (isFlattenedTranslations(localization)) {
+    return localization
+  }
+
+  const extensionLocale = resolveDevExtensionLocale(localization, locales)
+  const translations = JSON.stringify(flattenDevExtensionTranslations(localization, extensionLocale))
+
+  const flattenedLocalization: FlattenedLocalization = {
+    extensionLocale,
+    translations,
+    lastUpdated: localization.lastUpdated,
+  }
+  return flattenedLocalization
+}
+
+export function isFlattenedTranslations(
+  localization: Localization | FlattenedLocalization,
+): localization is FlattenedLocalization {
+  return (
+    typeof localization.translations === 'string' &&
+    Object.prototype.hasOwnProperty.call(localization, 'extensionLocale')
+  )
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './context'
+export * from './ExtensionServerClient'
+export * from './hooks'
+export * from './state'
+export * from './types'
+export * from './utilities'
+export * from './i18n'

package/src/state/actions/actions.ts

@@ -0,0 +1,36 @@
+import type {ConnectedAction, UpdateAction, RefreshAction, FocusAction, UnfocusAction} from './types'
+
+export function createConnectedAction(payload: ConnectedAction['payload']): ConnectedAction {
+  return {
+    type: 'connected',
+    payload,
+  }
+}
+
+export function createUpdateAction(payload: UpdateAction['payload']): UpdateAction {
+  return {
+    type: 'update',
+    payload,
+  }
+}
+
+export function createRefreshAction(payload: RefreshAction['payload']): RefreshAction {
+  return {
+    type: 'refresh',
+    payload,
+  }
+}
+
+export function createFocusAction(payload: FocusAction['payload']): FocusAction {
+  return {
+    type: 'focus',
+    payload,
+  }
+}
+
+export function createUnfocusAction(payload: UnfocusAction['payload']): UnfocusAction {
+  return {
+    type: 'unfocus',
+    payload,
+  }
+}

package/src/state/actions/index.ts

@@ -0,0 +1,2 @@
+export * from './actions'
+export * from './types'

package/src/state/actions/types.ts

@@ -0,0 +1,26 @@
+export interface ConnectedAction {
+  type: 'connected'
+  payload: ExtensionServer.InboundEvents['connected']
+}
+
+export interface UpdateAction {
+  type: 'update'
+  payload: ExtensionServer.InboundEvents['update']
+}
+
+export interface RefreshAction {
+  type: 'refresh'
+  payload: ExtensionServer.InboundEvents['refresh']
+}
+
+export interface FocusAction {
+  type: 'focus'
+  payload: ExtensionServer.InboundEvents['focus']
+}
+
+export interface UnfocusAction {
+  type: 'unfocus'
+  payload: ExtensionServer.InboundEvents['unfocus']
+}
+
+export type ExtensionServerActions = ConnectedAction | UpdateAction | RefreshAction | FocusAction | UnfocusAction

package/src/state/index.ts

@@ -0,0 +1,2 @@
+export * from './actions'
+export * from './reducers'

package/src/state/reducers/constants.ts

@@ -0,0 +1,6 @@
+import type {ExtensionServerState} from './types'
+
+export const INITIAL_STATE: ExtensionServerState = {
+  extensions: [],
+  store: '',
+}