App Intent title and other localized strings not showing correctly in Shortcuts app on macOS 15

What happens if you add a new string catalog named AppShortcuts.xcstrings to your project?

—Ed Ford,  DTS Engineer

Do you mean to the main target or the app extension? And should I keep the existing Localizable.xcstrings or delete it?

App Shortcuts need to be in your main app target, so the localization file should go there along with it. As to your Localizable.xcstrings file, you can keep that for general purpose localization throughout your app. AppShortcuts.xcstrings will be just for your App Shortcuts, and the system will know that based on the file name.

—Ed Ford,  DTS Engineer

I have a non-SwiftUI app, so I guess this doesn't apply? I don't see how I could have App Shortcuts without a separate App Intents Extension.

Is this AppShortcuts.xcstrings officially documented? I couldn't find it anywhere.

App Shortcuts need to be in your main app target

I have a non-SwiftUI app, so I guess this doesn't apply?

It still applies — the UI framework of your app doesn't change the way your targets are structured.

I don't see how I could have App Shortcuts without a separate App Intents Extension.

To do this, you define a type conforming to AppShortcutsProvider in your main app target, and calling updateAppShortcutParameters() from somewhere in your app initialization code path. The process for defining the conforming type isn't different for a SwiftUI app or a UIKit based app, though the place where you call the update method would be different based on either the SwiftUI or UIKit app lifecycle.

Is this AppShortcuts.xcstrings officially documented? I couldn't find it anywhere.

We've mentioned it in a video (timecode link) and use it in our sample app. I recognize this is a subtle detail that's easy to miss in those sources.

— Ed Ford,  DTS Engineer

I don't follow. Currently I have an App Intents extension as a separate target and the Shortcuts app lists the intents defined there, even without me defining anything in the main target. That's why I assumed you were talking about SwiftUI. If that's not the case, I don't understand what AppShortcutsProvider is meant for.

What confuses me even more is that I have a different Xcode project with an App Intents extension that contains a Localizable.xcstrings file, and Shortcuts displays those string just fine.

I've now removed the App Intents Extension and moved the code to the main target.

@available(macOS 13.0, *)
struct MyShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(intent: MyIntent(), phrases: ["Do something in \(.applicationName)"])
    }
}

@available(macOS 13, *)
struct MyIntent: AppIntent {
    static let title = LocalizedStringResource("intent.title")
    static let description = IntentDescription("intent.description")
    static let openAppWhenRun = true
    
    @Parameter(title: "intent.parameter.first")
    var first: String
    @Parameter(title: "intent.parameter.second")
    var second: String
    
    func perform() async throws -> some IntentResult {
        return .result()
    }
}

I've also created AppShortcuts.xcstrings in the main target.

When I build the project, AppShortcuts.xcstrings only contains the string Do something in \(.applicationName), while all other strings (intent.title etc.) appear in Localizable.xcstrings. Is this expected?

Previously, when I still had the separate App Intents Extension, I had all those strings in the same file, but when I renamed it to AppShortcuts.xcstrings and moved it to the main target I got several errors

Invalid Utterance. Every App Shortcut utterance should have one '${applicationName}' in it.

The errors went away when I only kept the string Do something in \(.applicationName), although I had to remove the others manually from the source code editor, since the string catalog editor always disables the buttons to add and remove strings in AppShortcuts.xcstrings.

Even more confusing is that the following

struct MyShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(intent: MyIntent(), phrases: ["Do something in \(.applicationName)"], shortTitle: "Do something short", systemImageName: "doc")
    }
}

causes Do something in \(.applicationName) to appear in AppShortcuts.xcstrings, but Do something short to appear in Localizable.xcstrings. Is this expected?

Do something in (.applicationName) to appear in AppShortcuts.xcstrings, but Do something short to appear in Localizable.xcstrings. Is this expected?

Yes it is. The App Shortcuts string catalog is focused on the invocation phrases for the app, which then enables the App Shortcuts phrase recognition. For example, you can use the Product > App Shortcuts Preview tool to see how small variations in phrasing that your customers might use will match up with your App Shortcut intents, in each language your app supports. This extra string catalog dedicated to those automatically extracted phrases from your app is key to that.

— Ed Ford,  DTS Engineer

Thanks for confirming. Combining the information in this thread and this other thread about App Intents, I was finally able to understand better how they work. It's somewhat unfortunate that there's little to no (written) documentation about AppShortcuts.xcstrings.