How to insert Spotlight for Help into localized macOS applications?

Question

I am implementing a Java application using the Swing GUI framework on macOS. When using the system look and feel and a screen menu bar, Swing automatically inserts a search field called Spotlight for Help into the first menu labelled "Help" of the menu bar of a frame:

System.setProperty("apple.laf.useScreenMenuBar", "true");

try {
  UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
} catch (Exception e) {
  e.printStackTrace();
}

JFrame frame = new JFrame();
JMenuBar menuBar = new JMenuBar();
JMenu helpMenu = new JMenu("Help");
menuBar.add(helpMenu);
frame.setJMenuBar(menuBar);

As my application is localized, the English string "Help" is different in other locales (e.g. "Aide" in French). But in those cases Swing does not insert Spotlight for Help since the string is different:

Lisandralisbeth

Answer 1

Solution

1. Bundle the .class files and resources (image, sound, video, localization files, etc.) of your application in a .jar file with Oracle's Java Archive.
2. Bundle your .jar file in an .app directory with Oracle's AppBundler (for Java 7+, which replaces the old Apple's JarBundler for Java 6).
3. Add to the .app directory the Contents/Resources/<locale>.lproj directories for each locale that should be supported by your application (you can let the locale directories empty since the localization files can be already in the .jar file).
4. Launch your application (double-click on the application icon in Finder or type open <application>.app in Terminal).

The search field Spotlight for Help will appear.

Explanation

I'm going to make a guess and it's that you're executing the .class files directly (from an IDE, for instance) or the .jar file, because from what I know this should be working.

Although what most sources say, Swing is deeply rooted on system calls and thus relies on the OS for many features, like in this case. Ideally, this should be covered by the method setHelpMenu(JMenu) but as you'll notice this has never been implemented.

If you check first, you'll notice that there's no extra component added in your JMenuBar and you have no control over that. If you try using AWT's MenuBar instead you'll see the behavior is exactly the same although, insterestingly enough, the method setHelpMenu(Menu) it is really implemented but doesn't add the search field if the menu is named something different from "Help".

At this point I found a workaround and it's setting the menu label to "Help" and once displayed (don't use ComponentListener.componentShown(ComponentEvent), this won't work, use AncestorListener.ancestorAdded(AncestorEvent)) changing the menu label to the localized one. This will add the search field to the help menu. However the search field will in English, with the label "Search".

Checking the API, it's more than clear that in Swing this feature is not implemented and fully relies on AWT. AWT on the other hand has partly implemented the native calls to the OS, but it's not wired to be invokable. Reaching this point and knowing that the search field does appear in our application and that in other ones running in Java it's properly localized lets us hint that this is a trait of the OS itself (I might be wrong at this point and it's really AWT doing the dirty job, but wasn't able to find any piece of code that does it directly, although in Objective C you can define any).

Reading the documentation about how to localize a Java application in MacOS, we note that:

• it's a requirement that the application be bundled in an .app directory and contain the Contents/Resources/<os-locale>.lproj directory, so that the OS recognizes the OS locale as supported by the application, and consequently expects a menu labeled with the OS-localized "Help" string in order to add the OS-localized search field to that menu;
• otherwise, the OS treats the application as en_US localized, and consequently expects a menu labeled with the en_US-localized "Help" string in order to add the en_US-localized search field to that menu.

Now you can type open <application>.app in Terminal and your application will be launched with the OS-localized search field added to the help menu.

Note that Apple has its own mechanism for forcing the application to use another locale than the OS locale, and it's using the -AppleLanguages option (open <application>.app --args -AppleLanguages "(<locale>)"). The Language Switcher utility does the same under the hood. Again, the appropriate Contents/Resources/<locale>.lproj directory should exist, otherwise the OS will treat the application as en_US localized.

How you make an .app directory from the .class files and resources (image, sound, video, localization files, etc.) of your application is beyond the scope of this question because it varies depending on the platform you're using, but Oracle provides the Java Archive (to make the intermediary .jar file) and AppBundler (to make the .app directory) utilities.

Screenshot

The OS is localized in Spanish in this screenshot but the application is localized in French, because it's been launched with the -AppleLanguages "(fr)" option.

Floccus

This solved my problem, thanks. I edited your answer that suggests to use Apple's JarBundler (for Java 6) because it is a legacy program that has been replaced by Oracle's AppBundler (for Java 7+). – Duron

That's great, good to know about AppBundler. You also removed the part where's explained why running classes directly doesn't show locales other than en_US and I find it important to understand what's happening under the hood initially. Anyway, I leave it up to you since if you feel answered, who am I to contradict you. – Liquidator

I found your sentence "Java is defined to only work with the language en_US" ambiguous and so did not understand your last paragraph, that is why I removed it in the first place. But now I know what you meant: macOS assumes the locale is en_US (and consequently expects a menu labelled with the English string "Help", in which it can add the Spotlight field) when there is no <application>.app bundle containing a directory named Contents/Resources/<locale>.lproj. I have improved the answer accordingly. Again, thank you for this complete answer. – Duron

I have just found out another way (see my answer below). – Duron

Answer 2

I have just found out another way. No need to add empty Contents/Resources/<locale>.lproj directories in the .app directory, just adding these two lines (key-value pair) in the Contents/Info.plist file of the .app directory works:

<key>CFBundleAllowMixedLocalizations</key>
<true />

And the new way to make an .app bundle is to use Oracle's JavaPackager command-line utility, which is part of the J.D.K. It generates an .app directory with a Contents/Info.plist that has the above two lines by default (no need to pass the key-value pair as an option of javapackager in the command-line). And forcing another locale with the open <application>.app --args -AppleLanguages "(<locale>)" command really works with the <application>.app directory generated by Oracle's JavaPackager, contrary to the one generated by Oracle's AppBundler.

Lisandralisbeth

I remember trying this at some point but didn't work for me, but indeed works. About the JavaPackager, if you check my original response I deliberately left out the different tools available, explained the issue and just made some suggestions to have a look at (I use a Maven plugin for instance), because each one has their own particularities. That's why I don't like heavy edits, but as long as the community approves, I'm fine. – Liquidator