feat: add context menu translate option

.changeset/context-menu-translate.md

@@ -0,0 +1,9 @@
+---
+"@read-frog/extension": minor
+---
+
+feat: add context menu translate option
+
+Add right-click context menu option for translating pages directly from the browser context menu.
+
+**Important**: This feature requires a new `contextMenus` permission. When upgrading, your browser may prompt you to approve this new permission and temporarily disable the extension until approved. This is normal browser behavior for permission changes.

src/entrypoints/background/context-menu.ts

@@ -0,0 +1,225 @@
+import type { Browser } from '#imports'
+import type { Config } from '@/types/config/config'
+import { browser, i18n, storage } from '#imports'
+import { isAPIProviderConfig } from '@/types/config/provider'
+import { getProviderConfigById } from '@/utils/config/helpers'
+import { CONFIG_STORAGE_KEY } from '@/utils/constants/config'
+import { getTranslationStateKey, TRANSLATION_STATE_KEY_PREFIX } from '@/utils/constants/storage-keys'
+import { logger } from '@/utils/logger'
+import { sendMessage } from '@/utils/message'
+import { ensureInitializedConfig } from './config'
+
+const MENU_ID_TRANSLATE = 'read-frog-translate'
+
+let currentConfig: Config | null = null
+
+/**
+ * Register all context menu event listeners synchronously
+ * This must be called during main() execution to ensure listeners are registered
+ * before Chrome completes initialization
+ */
+export function registerContextMenuListeners() {
+  // Listen for config changes using native Chrome API for persistence
+  // This ensures the listener survives service worker sleep/wake cycles
+  browser.storage.local.onChanged.addListener(async (changes) => {
+    const configChange = changes[CONFIG_STORAGE_KEY]
+    if (configChange?.newValue) {
+      currentConfig = configChange.newValue as Config
+      await updateContextMenuItems(currentConfig)
+    }
+  })
+
+  // Listen for tab activation to update menu title
+  browser.tabs.onActivated.addListener(async (activeInfo) => {
+    await updateTranslateMenuTitle(activeInfo.tabId)
+  })
+
+  // Listen for tab updates (e.g., navigation)
+  browser.tabs.onUpdated.addListener(async (tabId, changeInfo) => {
+    if (changeInfo.status === 'complete') {
+      await updateTranslateMenuTitle(tabId)
+    }
+  })
+
+  // Listen for translation state changes in storage
+  // This ensures menu updates when translation is toggled from any UI
+  // (floating button, auto-translate, etc.) without interfering with
+  // the translation logic in translation-signal.ts
+  browser.storage.session.onChanged.addListener(async (changes) => {
+    for (const [key, change] of Object.entries(changes)) {
+      // Check if this is a translation state change
+      if (key.startsWith(TRANSLATION_STATE_KEY_PREFIX.replace('session:', ''))) {
+        // Extract tabId from key (format: "translationState.{tabId}")
+        const parts = key.split('.')
+        const tabId = Number.parseInt(parts[1])
+
+        if (!Number.isNaN(tabId)) {
+          // Only update menu if this is the active tab
+          const [activeTab] = await browser.tabs.query({ active: true, currentWindow: true })
+          if (activeTab?.id === tabId) {
+            const newValue = change.newValue as { enabled: boolean } | undefined
+            await updateTranslateMenuTitle(tabId, newValue?.enabled)
+          }
+        }
+      }
+    }
+  })
+
+  // Handle menu item clicks
+  browser.contextMenus.onClicked.addListener(handleContextMenuClick)
+}
+
+/**
+ * Initialize context menu items based on config
+ * This can be called asynchronously after listeners are registered
+ */
+export async function initializeContextMenu() {
+  // Ensure config is initialized before setting up context menu
+  const config = await ensureInitializedConfig()
+  if (!config) {
+    return
+  }
+
+  currentConfig = config
+  await updateContextMenuItems(config)
+}
+
+/**
+ * Update context menu items based on config
+ */
+async function updateContextMenuItems(config: Config) {
+  // Remove all existing menu items first
+  await browser.contextMenus.removeAll()
+
+  const { translateEnabled } = config.contextMenu
+
+  if (translateEnabled) {
+    browser.contextMenus.create({
+      id: MENU_ID_TRANSLATE,
+      title: i18n.t('contextMenu.translate'),
+      contexts: ['page'],
+    })
+  }
+
+  // Update translate menu title for current tab
+  const [activeTab] = await browser.tabs.query({ active: true, currentWindow: true })
+  if (activeTab?.id) {
+    await updateTranslateMenuTitle(activeTab.id)
+  }
+}
+
+/**
+ * Update translate menu title based on current translation state
+ * @param tabId - The tab ID to check translation state for
+ * @param enabled - Optional: if provided, use this value instead of reading from storage
+ */
+async function updateTranslateMenuTitle(tabId: number, enabled?: boolean) {
+  if (!currentConfig?.contextMenu.translateEnabled) {
+    return
+  }
+
+  try {
+    let isTranslated: boolean
+    if (enabled !== undefined) {
+      isTranslated = enabled
+    }
+    else {
+      const state = await storage.getItem<{ enabled: boolean }>(
+        getTranslationStateKey(tabId),
+      )
+      isTranslated = state?.enabled ?? false
+    }
+
+    await browser.contextMenus.update(MENU_ID_TRANSLATE, {
+      title: isTranslated
+        ? i18n.t('contextMenu.showOriginal')
+        : i18n.t('contextMenu.translate'),
+    })
+  }
+  catch {
+    // Menu item might not exist if translateEnabled is false
+  }
+}
+
+/**
+ * Handle context menu item click
+ */
+async function handleContextMenuClick(
+  info: Browser.contextMenus.OnClickData,
+  tab?: Browser.tabs.Tab,
+) {
+  if (!tab?.id) {
+    return
+  }
+
+  if (info.menuItemId === MENU_ID_TRANSLATE) {
+    await handleTranslateClick(tab.id)
+  }
+}
+
+/**
+ * Validate translation configuration in background context
+ * This is a simplified version of validateTranslationConfig without toast notifications
+ */
+function validateTranslationConfigInBackground(config: Config): boolean {
+  const { providersConfig, translate: translateConfig, language: languageConfig } = config
+  const providerConfig = getProviderConfigById(providersConfig, translateConfig.providerId)
+
+  // Check if provider exists
+  if (!providerConfig) {
+    logger.warn('[ContextMenu] Translation provider not found')
+    return false
+  }
+
+  // Check if source and target languages are the same
+  if (languageConfig.sourceCode === languageConfig.targetCode) {
+    logger.warn('[ContextMenu] Source and target languages are the same')
+    return false
+  }
+
+  // Check if detected language and target language are the same in auto mode
+  // Note: Unlike the case above, this only warns but does NOT block translation
+  // This matches the behavior of validateTranslationConfig in translate-text.ts
+  if (languageConfig.sourceCode === 'auto' && languageConfig.detectedCode === languageConfig.targetCode) {
+    logger.warn('[ContextMenu] Detected language matches target language in auto mode')
+    // Don't return false - allow translation to proceed with warning
+  }
+
+  // Check if API key is configured for providers that require it
+  if (isAPIProviderConfig(providerConfig) && !providerConfig.apiKey?.trim() && !['deeplx', 'ollama'].includes(providerConfig.provider)) {
+    logger.warn('[ContextMenu] API key not configured for provider')
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Handle translate menu click - toggle page translation
+ */
+async function handleTranslateClick(tabId: number) {
+  const state = await storage.getItem<{ enabled: boolean }>(
+    getTranslationStateKey(tabId),
+  )
+  const isCurrentlyTranslated = state?.enabled ?? false
+  const newState = !isCurrentlyTranslated
+
+  // If enabling translation, validate configuration first
+  if (newState && currentConfig) {
+    if (!validateTranslationConfigInBackground(currentConfig)) {
+      logger.error('[ContextMenu] Translation config validation failed')
+      // Send a message to content script to show error notification
+      void sendMessage('showTranslationConfigError', undefined, tabId)
+      return
+    }
+  }
+
+  // Update storage directly (instead of sending message to self)
+  await storage.setItem(getTranslationStateKey(tabId), { enabled: newState })
+
+  // Notify content script in that specific tab
+  void sendMessage('translationStateChanged', { enabled: newState }, tabId)
+
+  // Update menu title immediately
+  await updateTranslateMenuTitle(tabId)
+}

src/entrypoints/background/index.ts

@@ -5,6 +5,7 @@ import { onMessage, sendMessage } from '@/utils/message'
 import { SessionCacheGroupRegistry } from '@/utils/session-cache/session-cache-group-registry'
 import { ensureInitializedConfig } from './config'
 import { setUpConfigBackup } from './config-backup'
+import { initializeContextMenu, registerContextMenuListeners } from './context-menu'
 import { cleanupAllCache, setUpDatabaseCleanup } from './db-cleanup'
 import { handleAnalyzeSelectionPort, handleTranslateStreamPort, runAnalyzeSelectionStream } from './firefox-stream'
 import { initMockData } from './mock-data'
@@ -79,6 +80,13 @@ export default defineBackground({
     newUserGuide()
     translationMessage()
 
+    // Register context menu listeners synchronously
+    // This ensures listeners are registered before Chrome completes initialization
+    registerContextMenuListeners()
+
+    // Initialize context menu items asynchronously
+    void initializeContextMenu()
+
     void setUpRequestQueue()
     void setUpDatabaseCleanup()
     setUpConfigBackup()

src/entrypoints/host.content/index.tsx

@@ -95,6 +95,21 @@ export default defineContentScript({
       enabled ? void manager.start() : manager.stop()
     })
 
+    // Listen for translation config error from context menu
+    onMessage('showTranslationConfigError', async () => {
+      const config = await getConfigFromStorage()
+      if (!config)
+        return
+
+      // Dynamically import validateTranslationConfig to show proper error messages with toast
+      const { validateTranslationConfig } = await import('@/utils/host/translate/translate-text')
+      validateTranslationConfig({
+        providersConfig: config.providersConfig,
+        translate: config.translate,
+        language: config.language,
+      })
+    })
+
     const config = await getConfigFromStorage()
     if (config) {
       const { detectedCode } = getDocumentInfo()

src/entrypoints/options/pages/floating-button-and-toolbar/context-menu-translate-toggle.tsx

@@ -0,0 +1,27 @@
+import { i18n } from '#imports'
+import { useAtom } from 'jotai'
+import { Switch } from '@/components/shadcn/switch'
+import { configFieldsAtomMap } from '@/utils/atoms/config'
+import { ConfigCard } from '../../components/config-card'
+
+export function ContextMenuTranslateToggle() {
+  const [contextMenu, setContextMenu] = useAtom(
+    configFieldsAtomMap.contextMenu,
+  )
+
+  return (
+    <ConfigCard
+      title={i18n.t('options.floatingButtonAndToolbar.contextMenu.translate.title')}
+      description={i18n.t('options.floatingButtonAndToolbar.contextMenu.translate.description')}
+    >
+      <div className="w-full flex justify-end">
+        <Switch
+          checked={contextMenu.translateEnabled}
+          onCheckedChange={(checked) => {
+            void setContextMenu({ ...contextMenu, translateEnabled: checked })
+          }}
+        />
+      </div>
+    </ConfigCard>
+  )
+}

src/entrypoints/options/pages/floating-button-and-toolbar/index.tsx

@@ -3,6 +3,7 @@ import floatingButtonDemoImage from '@/assets/demo/floating-button.png'
 import selectionToolbarDemoImage from '@/assets/demo/selection-toolbar.png'
 import { GradientBackground } from '@/components/gradient-background'
 import { PageLayout } from '../../components/page-layout'
+import { ContextMenuTranslateToggle } from './context-menu-translate-toggle'
 import { FloatingButtonDisabledSites } from './floating-button-disabled-sites'
 import { FloatingButtonGlobalToggle } from './floating-button-global-toggle'
 import { SelectionToolbarDisabledSites } from './selection-toolbar-disabled-sites'
@@ -29,6 +30,10 @@ export function FloatingButtonAndToolbarPage() {
       </GradientBackground>
       <SelectionToolbarGlobalToggle />
       <SelectionToolbarDisabledSites />
+      <h2 className="text-lg font-semibold mt-6 mb-2">
+        {i18n.t('options.floatingButtonAndToolbar.contextMenu.title')}
+      </h2>
+      <ContextMenuTranslateToggle />
     </PageLayout>
   )
 }

src/locales/en.yml

@@ -2,6 +2,9 @@ name: Read Frog
 extName: Read Frog - Open Source Immersive Translate
 extDescription: Read Frog is an open source browser extension designed to help you learn languages deeply from any website.
 uninstallSurveyUrl: https://tally.so/r/nPK6Ob
+contextMenu:
+  translate: Translate
+  showOriginal: Show Original
 popup:
   autoLang: Auto
   sourceLang: Source
@@ -176,6 +179,11 @@ options:
         description: Configure websites where the selection toolbar should be disabled
         enterUrlPattern: Enter URL pattern
         urlPattern: URL Pattern
+    contextMenu:
+      title: Context Menu
+      translate:
+        title: Enable Context Menu Translate
+        description: Add a translate option to the browser right-click menu for quick page translation
   translation:
     title: Translation
     requestQueueConfig:

src/locales/ja.yml

@@ -1,6 +1,9 @@
 name: 読書カエル
 extName: 読書カエル - オープンソースインビジブル翻訳
 extDescription: 読書カエルは、あらゆるウェブサイトから言語を深く学ぶために設計されたオープンソースのブラウザ拡張機能です。
+contextMenu:
+  translate: 翻訳
+  showOriginal: 原文を表示
 popup:
   autoLang: 自動検出
   sourceLang: ソース言語
@@ -174,6 +177,11 @@ options:
         description: 選択ツールバーを無効化するウェブサイトを設定します
         enterUrlPattern: URL パターンを入力
         urlPattern: URL パターン
+    contextMenu:
+      title: コンテキストメニュー
+      translate:
+        title: 右クリック翻訳を有効化
+        description: ブラウザの右クリックメニューに翻訳オプションを追加し、ページを素早く翻訳
   translation:
     title: 翻訳
     requestQueueConfig:

src/locales/ko.yml

@@ -1,6 +1,9 @@
 name: Read Frog
 extName: Read Frog - 오픈 소스 몰입형 번역
 extDescription: Read Frog는 모든 웹사이트에서 언어를 깊이 있게 학습할 수 있도록 도와주는 오픈 소스 브라우저 확장 프로그램입니다.
+contextMenu:
+  translate: 번역
+  showOriginal: 원문 보기
 popup:
   autoLang: 자동
   sourceLang: 원본
@@ -175,6 +178,11 @@ options:
         description: 선택 툴바를 비활성화할 웹사이트를 설정합니다
         enterUrlPattern: URL 패턴 입력
         urlPattern: URL 패턴
+    contextMenu:
+      title: 컨텍스트 메뉴
+      translate:
+        title: 우클릭 번역 활성화
+        description: 브라우저 우클릭 메뉴에 번역 옵션을 추가하여 빠른 페이지 번역
   translation:
     title: 번역
     requestQueueConfig: