Migrating Legacy macOS Applications to Use Base Internationalization: A Guide

I am working on modernizing the legacy macOS application developed on macOS 10.5. While doing so, I encountered a problem. The built binary could not launch, preventing the debugger from attaching to its process.


Investigate the Cause of the Problem

The debugger couldn’t launch the binary, so I guessed that the application package’s contents or structure contained something invalid. To diagnose the issue, I attempted to launch the binary directly from the Terminal to capture any error messages or output. Xcode writes intermediate files and binaries for debugging into sub-directories created for each project in the following directory with the default configuration.


The application name is RKDetailDesign. The project file name is RKDetailDesign.xcodeproj, so I can find the RKDetailDesign-byccbbcuvpnixtdhipwqzxlntobv folder in the above directory. In this directory, the following directory contains the debug version binary.


Launch the debug version application from the Terminal.

% cd /Users/akira/Library/Developer/Xcode/DerivedData/RKDetailDesign-byccbbcuvpnixtdhipwqzxlntobv/Build/Products/Debug
% % ./RKDetailDesign.app/Contents/MacOS/RKDetailDesign
2024-03-15 22:10:17.965 RKDetailDesign[14090:143830] Unable to load nib file: MainMenu, exiting

I knowed the cause of this problem. The system couldn’t find the MainMenu.nib file and canceled the launch.

About the MainMenu.nib File

The MainMenu.nib file is generated from the MainMenu.xib file in the building process. The project file has the MainMenu.xib file; its localization is only English. The MainMenu.nib file is at the following path in the built application package.


The Base Internationalization

The en.lproj folder is a localizable resource folder for English. The legacy name is English.lproj. Xcode will show a warning if the legacy name is used, and Xcode says that the new name should be used. Xcode’s migration feature will change the name to come up with this guidance. At the same time, it will turn on the use-base-internationalization feature.

With the use-based-internationalization, the system can’t find the file only in the localizable resource folders for specified languages. It needs the base version, which is in the base.lproj folder.

In this example, the application package doesn’t have base.lproj/MainMenu.nib, so the system couldn’t find the MainMenu.nib file and failed to launch.

Without the use-base-internationalization, English.lproj has the role of base.lproj.

The “Use Base Internationalization” checkbox in the “Info” tab of the project configuration allows you to turn on/off the use-base-internationalization feature.

"Use Base Internationalization" checkbox
“Use Base Internationalization” checkbox

Move files From en.lproj To base.lproj

Move resource files in the en.lproj directory into the base.lproj directory. First, move the MainMenu.nib file. You can do that in Xcode. Follow the steps below.

Select the “MainMenu.xib” file.
Add the base localization in the file inspector.

In the “Localization” section of the file inspector, you’ll see a list of localization for the selected file. It checked only English, meaning the MainMenu.xib file only has an English localization. Add the base localization by checking on the “base,” and the Xcode will copy the MainMenu.xib file into the base.lproj folder.

Turn on "Base"
Turn on “Base”
Remove the English Localization

The system will use the base localization for the unlocalized version. The legacy system used English localization for that; we no longer need it, so turn off the “English” checkbox to remove it. Xcode removes the MainMenu.xib file from the en.lproj folder and no longer exports the en.lproj/MainMenu.nib file on the build.

Turn off "English" checkbox
Turn off “English” checkbox


We should perform “Clean Build Folder…” in the “Product” menu before the build-and-run because we changed the structure of the resource files/folders. Do the build-and-run.

The base.lproj/MainMenu.nib file was exported, and the system can now find it and launch the built application.

Do the same operations to other resource files in the English localization.

Doing so completes the migration to base internationalization.


Authored Books

  • URLをコピーしました!
  • URLをコピーしました!


Akira Hayashi (林 晃)のアバター Akira Hayashi (林 晃) Representative(代表), Software Engineer(ソフトウェアエンジニア)

アールケー開発代表。Appleプラットフォーム向けの開発を専門としているソフトウェアエンジニア。ソフトウェアの受託開発、技術書執筆、技術指導・セミナー講師。note, Medium, LinkedIn
Representative of RK Kaihatsu. Software Engineer Specializing in Development for the Apple Platform. Specializing in contract software development, technical writing, and serving as a tech workshop lecturer. note, Medium, LinkedIn