Fixing the URL Scheme goldendict://word of GoldenDict-ng on macOS

The link goldendict://word doesn’t work for Goldendict-ng on macOS (Sequoia 15.5). When entered in the browser’s address bar it can open the Goldendict-ng app, but not to the specified word, no query happening.

The Cause

Here’s the system and installation info as of writing (2026/01/02):

macOS (Sequoia 15.5)
Version: 25.06.0.8a87a79 at 2025-06-18T05:45:54Z
Qt 6.7.2 Clang 15.0.0 (clang-1500.3.9.4)
macos darwin 24.5.0 arm64-little_endian-lp64
Flags: ZIM EPWING OPENCC

It appears you are encountering a known limitation with the macOS implementation of the goldendict:// URL scheme in GoldenDict-ng. On macOS, the system correctly identifies the application registered to the scheme (which is why the app opens), but it fails to pass the specific “word” parameter to the application’s search engine.

On macOS, for an app to handle URL parameters (the word part of goldendict://word), it must implement a specific Apple Event handler (openURL). If the application only registers the scheme in its Info.plist without this handler logic, it will launch but ignore the payload.

Fixing the URL Scheme

If you specifically need the link to work (e.g., clicking a link in a web page or Anki), you can create a small “Shim” app using AppleScript to bridge the gap.

1. Open Script Editor on your Mac.

2. Paste the following code:

   on open location theURL
       set AppleScript's text item delimiters to "://"
       set theWord to text item 2 of theURL
       do shell script "/Applications/GoldenDict-ng.app/Contents/MacOS/GoldenDict-ng " & quoted form of theWord
   end open location
   

3. Save it as an Application (e.g., “GD-Handler”).

To make your “GD-Handler” the default handler for the goldendict:// scheme, you must register it in the application’s metadata and then force macOS to recognize it.

1. Add the Protocol to Info.plist

   macOS identifies what an app can do by reading its Info.plist file.

   1. Locate your GD-Handler.app in Finder.

   2. Right-click it and select Show Package Contents.

   3. Navigate to Contents/Info.plist.

   4. Open Info.plist with a text editor (like TextEdit or VS Code).

   5. Paste the following XML block right before the final </dict></plist> tags:

      <key>CFBundleURLTypes</key>
      <array>
        <dict>
          <key>CFBundleURLName</key>
          <string>GoldenDict Handler</string>
          <key>CFBundleURLSchemes</key>
          <array>
            <string>goldendict</string>
          </array>
          <key>LSIsAppleDefaultForScheme</key>
          <true/>
        </dict>
      </array>
      

2. Register the App with the System

   Simply saving the file isn’t enough; macOS caches these settings in a database called Launch Services. You need to force a refresh.

   1. Move your GD-Handler.app out of its current folder (e.g., to the Desktop) and then move it back to /Applications. This often triggers a background scan.

   2. Open the app once manually. This is critical; macOS will not route URLs to an app that has never been opened by the user (a security feature).

3. Force the Association (Optional)

   If GoldenDict-ng is still “stealing” the link, you can use the built-in macOS lsregister tool to force your handler to the top of the pile. Open Terminal and run:

   /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -f /Applications/GD-Handler.app
   

4. Verify the Default Handler

   To verify which app is currently set as the primary handler for the goldendict:// scheme, run this command:

   defaults read com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers | grep -B 1 "goldendict"
   

   If you don’t see your app’s bundle ID there, you can use a utility like SwiftDefaultApps or Duti (brew install duti) to set it explicitly:

   duti -s com.your.gdhandler.id goldendict all
   

   (You can find your bundle ID inside the same Info.plist under

Update to the latest version

Try to update the app to the latest version. After doing so the problem is gone.

Here’s the system and installation info as of writing:

macOS (Sequoia 15.5)
Version: 26.1.0.13f0f84 at 2026-01-04T06:32:13Z
Qt 6.9.1 Clang 15.0.0 (clang-1500.3.9.4)
macos darwin 24.5.0 arm64-little_endian-lp64
Flags: ZIM EPWING OPENCC FFMPEG