Centralized management of external links (#4471)

Update the desktop guide links to make them platform and locale-aware

Edited by Terry:
Refactor external link management by introducing a centralized
useExternalLink composable with automatic locale and platform detection
for documentation URLs.

- Created useExternalLink composable - A new centralized utility for
managing all external links
- Dynamic docs URL builder (buildDocsUrl) - Automatically constructs
docs.comfy.org URLs with:
  - Locale detection (Chinese vs English)
  - Platform detection (macOS vs Windows for desktop)
  - Flexible path construction with options

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-4471-Add-platform-and-locale-aware-desktop-guide-URL-2346d73d3650815ea4a4dd64be575bbe)
by [Unito](https://www.unito.io)

---------

Co-authored-by: Terry Jia <terryjia88@gmail.com>

Author: comfyui-wiki

src/components/dialog/content/ApiNodesSignInContent.vue

@@ -29,7 +29,10 @@
 import Button from 'primevue/button'
 import { useI18n } from 'vue-i18n'
 
+import { useExternalLink } from '@/composables/useExternalLink'
+
 const { t } = useI18n()
+const { buildDocsUrl } = useExternalLink()
 
 const { apiNodeNames, onLogin, onCancel } = defineProps<{
   apiNodeNames: string[]
@@ -38,6 +41,9 @@ const { apiNodeNames, onLogin, onCancel } = defineProps<{
 }>()
 
 const handleLearnMoreClick = () => {
-  window.open('https://docs.comfy.org/tutorials/api-nodes/faq', '_blank')
+  window.open(
+    buildDocsUrl('/tutorials/api-nodes/faq', { includeLocale: true }),
+    '_blank'
+  )
 }
 </script>

src/components/dialog/content/setting/CreditsPanel.vue

@@ -123,6 +123,7 @@ import { computed, ref, watch } from 'vue'
 import UserCredit from '@/components/common/UserCredit.vue'
 import UsageLogsTable from '@/components/dialog/content/setting/UsageLogsTable.vue'
 import { useFirebaseAuthActions } from '@/composables/auth/useFirebaseAuthActions'
+import { useExternalLink } from '@/composables/useExternalLink'
 import { useSubscription } from '@/platform/cloud/subscription/composables/useSubscription'
 import { useTelemetry } from '@/platform/telemetry'
 import { useDialogService } from '@/services/dialogService'
@@ -137,6 +138,7 @@ interface CreditHistoryItemData {
   isPositive: boolean
 }
 
+const { buildDocsUrl } = useExternalLink()
 const dialogService = useDialogService()
 const authStore = useFirebaseAuthStore()
 const authActions = useFirebaseAuthActions()
@@ -183,12 +185,17 @@ const handleMessageSupport = async () => {
 }
 
 const handleFaqClick = () => {
-  window.open('https://docs.comfy.org/tutorials/api-nodes/faq', '_blank')
+  window.open(
+    buildDocsUrl('/tutorials/api-nodes/faq', { includeLocale: true }),
+    '_blank'
+  )
 }
 
 const handleOpenPartnerNodesInfo = () => {
   window.open(
-    'https://docs.comfy.org/tutorials/api-nodes/overview#api-nodes',
+    buildDocsUrl('/tutorials/api-nodes/overview#api-nodes', {
+      includeLocale: true
+    }),
     '_blank'
   )
 }

src/components/helpcenter/HelpCenterMenuContent.vue

@@ -143,6 +143,7 @@ import type { CSSProperties, Component } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 import PuzzleIcon from '@/components/icons/PuzzleIcon.vue'
+import { useExternalLink } from '@/composables/useExternalLink'
 import { isCloud } from '@/platform/distribution/types'
 import { useSettingStore } from '@/platform/settings/settingStore'
 import { useTelemetry } from '@/platform/telemetry'
@@ -168,15 +169,6 @@ interface MenuItem {
 }
 
 // Constants
-const EXTERNAL_LINKS = {
-  DOCS: 'https://docs.comfy.org/',
-  DISCORD: 'https://www.comfy.org/discord',
-  GITHUB: 'https://github.com/comfyanonymous/ComfyUI',
-  DESKTOP_GUIDE_WINDOWS: 'https://docs.comfy.org/installation/desktop/windows',
-  DESKTOP_GUIDE_MACOS: 'https://docs.comfy.org/installation/desktop/macos',
-  UPDATE_GUIDE: 'https://docs.comfy.org/installation/update_comfyui'
-} as const
-
 const TIME_UNITS = {
   MINUTE: 60 * 1000,
   HOUR: 60 * 60 * 1000,
@@ -193,7 +185,8 @@ const SUBMENU_CONFIG = {
 } as const
 
 // Composables
-const { t, locale } = useI18n()
+const { t } = useI18n()
+const { staticUrls, buildDocsUrl } = useExternalLink()
 const releaseStore = useReleaseStore()
 const commandStore = useCommandStore()
 const settingStore = useSettingStore()
@@ -230,11 +223,12 @@ const moreItems = computed<MenuItem[]>(() => {
       visible: isElectron(),
       action: () => {
         trackResourceClick('docs', true)
-        const docsUrl =
-          electronAPI().getPlatform() === 'darwin'
-            ? EXTERNAL_LINKS.DESKTOP_GUIDE_MACOS
-            : EXTERNAL_LINKS.DESKTOP_GUIDE_WINDOWS
-        openExternalLink(docsUrl)
+        openExternalLink(
+          buildDocsUrl('/installation/desktop', {
+            includeLocale: true,
+            platform: true
+          })
+        )
         emit('close')
       }
     },
@@ -286,7 +280,7 @@ const menuItems = computed<MenuItem[]>(() => {
       label: t('helpCenter.docs'),
       action: () => {
         trackResourceClick('docs', true)
-        openExternalLink(EXTERNAL_LINKS.DOCS)
+        openExternalLink(buildDocsUrl('/', { includeLocale: true }))
         emit('close')
       }
     },
@@ -297,7 +291,7 @@ const menuItems = computed<MenuItem[]>(() => {
       label: 'Discord',
       action: () => {
         trackResourceClick('discord', true)
-        openExternalLink(EXTERNAL_LINKS.DISCORD)
+        openExternalLink(staticUrls.discord)
         emit('close')
       }
     },
@@ -308,7 +302,7 @@ const menuItems = computed<MenuItem[]>(() => {
       label: t('helpCenter.github'),
       action: () => {
         trackResourceClick('github', true)
-        openExternalLink(EXTERNAL_LINKS.GITHUB)
+        openExternalLink(staticUrls.github)
         emit('close')
       }
     },
@@ -533,25 +527,19 @@ const onReleaseClick = (release: ReleaseNote): void => {
   trackResourceClick('release_notes', true)
   void releaseStore.handleShowChangelog(release.version)
   const versionAnchor = formatVersionAnchor(release.version)
-  const changelogUrl = `${getChangelogUrl()}#${versionAnchor}`
+  const changelogUrl = `${buildDocsUrl('/changelog', { includeLocale: true })}#${versionAnchor}`
   openExternalLink(changelogUrl)
   emit('close')
 }
 
 const onUpdate = (_: ReleaseNote): void => {
   trackResourceClick('docs', true)
-  openExternalLink(EXTERNAL_LINKS.UPDATE_GUIDE)
+  openExternalLink(
+    buildDocsUrl('/installation/update_comfyui', { includeLocale: true })
+  )
   emit('close')
 }
 
-// Generate language-aware changelog URL
-const getChangelogUrl = (): string => {
-  const isChineseLocale = locale.value === 'zh'
-  return isChineseLocale
-    ? 'https://docs.comfy.org/zh-CN/changelog'
-    : 'https://docs.comfy.org/changelog'
-}
-
 // Lifecycle
 onMounted(async () => {
   telemetry?.trackHelpCenterOpened({ source: 'sidebar' })

src/components/topbar/CurrentUserPopover.vue

@@ -101,6 +101,7 @@ import UserAvatar from '@/components/common/UserAvatar.vue'
 import UserCredit from '@/components/common/UserCredit.vue'
 import { useCurrentUser } from '@/composables/auth/useCurrentUser'
 import { useFirebaseAuthActions } from '@/composables/auth/useFirebaseAuthActions'
+import { useExternalLink } from '@/composables/useExternalLink'
 import SubscribeButton from '@/platform/cloud/subscription/components/SubscribeButton.vue'
 import { useSubscription } from '@/platform/cloud/subscription/composables/useSubscription'
 import { isCloud } from '@/platform/distribution/types'
@@ -111,6 +112,8 @@ const emit = defineEmits<{
   close: []
 }>()
 
+const { buildDocsUrl } = useExternalLink()
+
 const planSettingsLabel = isCloud
   ? 'settingsCategories.PlanCredits'
   : 'settingsCategories.Credits'
@@ -145,7 +148,9 @@ const handleTopUp = () => {
 
 const handleOpenPartnerNodesInfo = () => {
   window.open(
-    'https://docs.comfy.org/tutorials/api-nodes/overview#api-nodes',
+    buildDocsUrl('/tutorials/api-nodes/overview#api-nodes', {
+      includeLocale: true
+    }),
     '_blank'
   )
   emit('close')

src/components/topbar/LoginButton.vue

@@ -22,7 +22,7 @@
     <div>
       <div class="mb-1">{{ t('auth.loginButton.tooltipHelp') }}</div>
       <a
-        href="https://docs.comfy.org/tutorials/api-nodes/overview#api-nodes"
+        :href="apiNodesOverviewUrl"
         target="_blank"
         class="text-neutral-500 hover:text-primary"
         >{{ t('auth.loginButton.tooltipLearnMore') }}</a
@@ -37,9 +37,17 @@ import Popover from 'primevue/popover'
 import { ref } from 'vue'
 
 import { useCurrentUser } from '@/composables/auth/useCurrentUser'
+import { useExternalLink } from '@/composables/useExternalLink'
 import { t } from '@/i18n'
 
 const { isLoggedIn, handleSignIn } = useCurrentUser()
+const { buildDocsUrl } = useExternalLink()
+const apiNodesOverviewUrl = buildDocsUrl(
+  '/tutorials/api-nodes/overview#api-nodes',
+  {
+    includeLocale: true
+  }
+)
 const popoverRef = ref<InstanceType<typeof Popover> | null>(null)
 let hideTimeout: ReturnType<typeof setTimeout> | null = null
 let showTimeout: ReturnType<typeof setTimeout> | null = null

src/composables/useCoreCommands.ts

@@ -1,6 +1,7 @@
 import { useCurrentUser } from '@/composables/auth/useCurrentUser'
 import { useFirebaseAuthActions } from '@/composables/auth/useFirebaseAuthActions'
 import { useSelectedLiteGraphItems } from '@/composables/canvas/useSelectedLiteGraphItems'
+import { useExternalLink } from '@/composables/useExternalLink'
 import { useModelSelectorDialog } from '@/composables/useModelSelectorDialog'
 import {
   DEFAULT_DARK_COLOR_PALETTE,
@@ -76,6 +77,7 @@ export function useCoreCommands(): ComfyCommand[] {
   const canvasStore = useCanvasStore()
   const executionStore = useExecutionStore()
   const telemetry = useTelemetry()
+  const { staticUrls, buildDocsUrl } = useExternalLink()
 
   const bottomPanelStore = useBottomPanelStore()
 
@@ -761,10 +763,7 @@ export function useCoreCommands(): ComfyCommand[] {
           is_external: true,
           source: 'menu'
         })
-        window.open(
-          'https://github.com/comfyanonymous/ComfyUI/issues',
-          '_blank'
-        )
+        window.open(staticUrls.githubIssues, '_blank')
       }
     },
     {
@@ -779,7 +778,7 @@ export function useCoreCommands(): ComfyCommand[] {
           is_external: true,
           source: 'menu'
         })
-        window.open('https://docs.comfy.org/', '_blank')
+        window.open(buildDocsUrl('/', { includeLocale: true }), '_blank')
       }
     },
     {
@@ -794,7 +793,7 @@ export function useCoreCommands(): ComfyCommand[] {
           is_external: true,
           source: 'menu'
         })
-        window.open('https://www.comfy.org/discord', '_blank')
+        window.open(staticUrls.discord, '_blank')
       }
     },
     {
@@ -861,7 +860,7 @@ export function useCoreCommands(): ComfyCommand[] {
           is_external: true,
           source: 'menu'
         })
-        window.open('https://forum.comfy.org/', '_blank')
+        window.open(staticUrls.forum, '_blank')
       }
     },
     {

src/composables/useExternalLink.ts

@@ -0,0 +1,99 @@
+import { computed } from 'vue'
+
+import { electronAPI, isElectron } from '@/utils/envUtil'
+import { useI18n } from 'vue-i18n'
+
+/**
+ * Composable for building docs.comfy.org URLs with automatic locale and platform detection
+ *
+ * @example
+ * ```ts
+ * const { buildDocsUrl } = useExternalLink()
+ *
+ * // Simple usage
+ * const changelogUrl = buildDocsUrl('/changelog', { includeLocale: true })
+ * // => 'https://docs.comfy.org/zh-CN/changelog' (if Chinese)
+ *
+ * // With platform detection
+ * const desktopUrl = buildDocsUrl('/installation/desktop', {
+ *   includeLocale: true,
+ *   platform: true
+ * })
+ * // => 'https://docs.comfy.org/zh-CN/installation/desktop/macos' (if Chinese + macOS)
+ * ```
+ */
+export function useExternalLink() {
+  const { locale } = useI18n()
+
+  const isChinese = computed(() => {
+    return locale.value === 'zh' || locale.value === 'zh-TW'
+  })
+
+  const platform = computed(() => {
+    if (!isElectron()) {
+      return null
+    }
+
+    const electronPlatform = electronAPI().getPlatform()
+    return electronPlatform === 'darwin' ? 'macos' : 'windows'
+  })
+
+  /**
+   * Build a docs.comfy.org URL with optional locale and platform
+   *
+   * @param path - The path after the domain (e.g., '/installation/desktop')
+   * @param options - Options for building the URL
+   * @param options.includeLocale - Whether to include locale prefix (default: false)
+   * @param options.platform - Whether to include platform suffix (default: false)
+   * @returns The complete docs URL
+   *
+   * @example
+   * ```ts
+   * buildDocsUrl('/changelog') // => 'https://docs.comfy.org/changelog'
+   * buildDocsUrl('/changelog', { includeLocale: true }) // => 'https://docs.comfy.org/zh-CN/changelog' (if Chinese)
+   * buildDocsUrl('/installation/desktop', { includeLocale: true, platform: true })
+   * // => 'https://docs.comfy.org/zh-CN/installation/desktop/macos' (if Chinese + macOS)
+   * ```
+   */
+  const buildDocsUrl = (
+    path: string,
+    options: {
+      includeLocale?: boolean
+      platform?: boolean
+    } = {}
+  ): string => {
+    const { includeLocale = false, platform: includePlatform = false } = options
+
+    let url = 'https://docs.comfy.org'
+
+    if (includeLocale && isChinese.value) {
+      url += '/zh-CN'
+    }
+
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`
+    url += normalizedPath
+
+    if (includePlatform && platform.value) {
+      url = url.endsWith('/') ? url : `${url}/`
+      url += platform.value
+    }
+
+    return url
+  }
+
+  const staticUrls = {
+    // Static external URLs
+    discord: 'https://www.comfy.org/discord',
+    github: 'https://github.com/comfyanonymous/ComfyUI',
+    githubIssues: 'https://github.com/comfyanonymous/ComfyUI/issues',
+    githubFrontend: 'https://github.com/Comfy-Org/ComfyUI_frontend',
+    githubElectron: 'https://github.com/Comfy-Org/electron',
+    forum: 'https://forum.comfy.org/',
+    comfyOrg: 'https://www.comfy.org/'
+  }
+
+  return {
+    buildDocsUrl,
+    staticUrls
+  }
+}