feat(frontend): pass locale to iframe embedded pages via lang parameter

Embedded pages (purchase subscription, custom pages) now receive the
current user locale through a `lang` URL parameter, allowing iframe
content to match the user's language preference.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/ADMIN_PAYMENT_INTEGRATION_API.md

@@ -99,16 +99,17 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
   }'
 ```
 
-### 4) 购买页 URL Query 透传（iframe / 新窗口一致）
-当 Sub2API 打开 `purchase_subscription_url` 时，会统一追加：
+### 4) 购买页 / 自定义页面 URL Query 透传（iframe / 新窗口一致）
+当 Sub2API 打开 `purchase_subscription_url` 或用户侧自定义页面 iframe URL 时，会统一追加：
 - `user_id`
 - `token`
 - `theme`（`light` / `dark`）
+- `lang`（例如 `zh` / `en`，用于向嵌入页传递当前界面语言）
 - `ui_mode`（固定 `embedded`）
 
 示例：
 ```text
-https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&ui_mode=embedded
+https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&lang=zh&ui_mode=embedded
 ```
 
 ### 5) 失败处理建议
@@ -218,16 +219,17 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
   }'
 ```
 
-### 4) Purchase URL query forwarding (iframe and new tab)
-When Sub2API opens `purchase_subscription_url`, it appends:
+### 4) Purchase / Custom Page URL query forwarding (iframe and new tab)
+When Sub2API opens `purchase_subscription_url` or a user-facing custom page iframe URL, it appends:
 - `user_id`
 - `token`
 - `theme` (`light` / `dark`)
+- `lang` (for example `zh` / `en`, used to pass the current UI language to the embedded page)
 - `ui_mode` (fixed: `embedded`)
 
 Example:
 ```text
-https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&ui_mode=embedded
+https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&lang=zh&ui_mode=embedded
 ```
 
 ### 5) Failure handling recommendations

frontend/src/utils/__tests__/embedded-url.spec.ts

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { buildEmbeddedUrl, detectTheme } from '../embedded-url'
+
+describe('embedded-url', () => {
+  const originalLocation = window.location
+
+  beforeEach(() => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        origin: 'https://app.example.com',
+        href: 'https://app.example.com/user/purchase',
+      },
+      writable: true,
+      configurable: true,
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(window, 'location', {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    })
+    document.documentElement.classList.remove('dark')
+    vi.restoreAllMocks()
+  })
+
+  it('adds embedded query parameters including locale and source context', () => {
+    const result = buildEmbeddedUrl(
+      'https://pay.example.com/checkout?plan=pro',
+      42,
+      'token-123',
+      'dark',
+      'zh-CN',
+    )
+
+    const url = new URL(result)
+    expect(url.searchParams.get('plan')).toBe('pro')
+    expect(url.searchParams.get('user_id')).toBe('42')
+    expect(url.searchParams.get('token')).toBe('token-123')
+    expect(url.searchParams.get('theme')).toBe('dark')
+    expect(url.searchParams.get('lang')).toBe('zh-CN')
+    expect(url.searchParams.get('ui_mode')).toBe('embedded')
+    expect(url.searchParams.get('src_host')).toBe('https://app.example.com')
+    expect(url.searchParams.get('src_url')).toBe('https://app.example.com/user/purchase')
+  })
+
+  it('omits optional params when they are empty', () => {
+    const result = buildEmbeddedUrl('https://pay.example.com/checkout', undefined, '', 'light')
+
+    const url = new URL(result)
+    expect(url.searchParams.get('theme')).toBe('light')
+    expect(url.searchParams.get('ui_mode')).toBe('embedded')
+    expect(url.searchParams.has('user_id')).toBe(false)
+    expect(url.searchParams.has('token')).toBe(false)
+    expect(url.searchParams.has('lang')).toBe(false)
+  })
+
+  it('returns original string for invalid url input', () => {
+    expect(buildEmbeddedUrl('not a url', 1, 'token')).toBe('not a url')
+  })
+
+  it('detects dark mode from document root class', () => {
+    document.documentElement.classList.add('dark')
+    expect(detectTheme()).toBe('dark')
+  })
+})

frontend/src/utils/embedded-url.ts

@@ -1,12 +1,13 @@
 /**
  * Shared URL builder for iframe-embedded pages.
  * Used by PurchaseSubscriptionView and CustomPageView to build consistent URLs
- * with user_id, token, theme, ui_mode, src_host, and src parameters.
+ * with user_id, token, theme, lang, ui_mode, src_host, and src parameters.
  */
 
 const EMBEDDED_USER_ID_QUERY_KEY = 'user_id'
 const EMBEDDED_AUTH_TOKEN_QUERY_KEY = 'token'
 const EMBEDDED_THEME_QUERY_KEY = 'theme'
+const EMBEDDED_LANG_QUERY_KEY = 'lang'
 const EMBEDDED_UI_MODE_QUERY_KEY = 'ui_mode'
 const EMBEDDED_UI_MODE_VALUE = 'embedded'
 const EMBEDDED_SRC_HOST_QUERY_KEY = 'src_host'
@@ -17,6 +18,7 @@ export function buildEmbeddedUrl(
   userId?: number,
   authToken?: string | null,
   theme: 'light' | 'dark' = 'light',
+  lang?: string,
 ): string {
   if (!baseUrl) return baseUrl
   try {
@@ -28,6 +30,9 @@ export function buildEmbeddedUrl(
       url.searchParams.set(EMBEDDED_AUTH_TOKEN_QUERY_KEY, authToken)
     }
     url.searchParams.set(EMBEDDED_THEME_QUERY_KEY, theme)
+    if (lang) {
+      url.searchParams.set(EMBEDDED_LANG_QUERY_KEY, lang)
+    }
     url.searchParams.set(EMBEDDED_UI_MODE_QUERY_KEY, EMBEDDED_UI_MODE_VALUE)
     // Source tracking: let the embedded page know where it's being loaded from
     if (typeof window !== 'undefined') {

frontend/src/views/user/CustomPageView.vue

@@ -75,7 +75,7 @@ import AppLayout from '@/components/layout/AppLayout.vue'
 import Icon from '@/components/icons/Icon.vue'
 import { buildEmbeddedUrl, detectTheme } from '@/utils/embedded-url'
 
-const { t } = useI18n()
+const { t, locale } = useI18n()
 const route = useRoute()
 const appStore = useAppStore()
 const authStore = useAuthStore()
@@ -107,6 +107,7 @@ const embeddedUrl = computed(() => {
     authStore.user?.id,
     authStore.token,
     pageTheme.value,
+    locale.value,
   )
 })
 

frontend/src/views/user/PurchaseSubscriptionView.vue

@@ -76,7 +76,7 @@ import AppLayout from '@/components/layout/AppLayout.vue'
 import Icon from '@/components/icons/Icon.vue'
 import { buildEmbeddedUrl, detectTheme } from '@/utils/embedded-url'
 
-const { t } = useI18n()
+const { t, locale } = useI18n()
 const appStore = useAppStore()
 const authStore = useAuthStore()
 
@@ -90,7 +90,7 @@ const purchaseEnabled = computed(() => {
 
 const purchaseUrl = computed(() => {
   const baseUrl = (appStore.cachedPublicSettings?.purchase_subscription_url || '').trim()
-  return buildEmbeddedUrl(baseUrl, authStore.user?.id, authStore.token, purchaseTheme.value)
+  return buildEmbeddedUrl(baseUrl, authStore.user?.id, authStore.token, purchaseTheme.value, locale.value)
 })
 
 const isValidUrl = computed(() => {