XCStrings Tool Documentation

To ensure the generated Swift code matches your expectations, configure your .xcstrings files with the following settings:

1. Key Naming: Set each string's Key to a lowerCamelCase identifier. This ensures the generated Swift constants follow standard naming conventions.
2. Managed Setting: Ensure the Managed setting for your strings is set to Manually. If the compiler pre-populated your catalog, you may need to manually change this value.

XCStrings Tool integrates as a Swift Package Plugin. Depending on your project structure, follow the specific integration guide for your target type:

• Xcode Project Targets: Follow the guide for integrating into an Xcode project target.
• Swift Package Targets: Follow the guide for integrating into a Swift Package target.

Once integrated, the plugin will generate source code that you can use to reference your localized strings via type-safe constants.

XCStrings Tool generates Swift source files containing constants for each Strings Catalog during the build process. These files are stored in a temporary directory within your Xcode DerivedData folder and are not part of your project's file tree.

To find the path to a generated file:

1. Open the Report navigator in Xcode.
2. Select your most recent build.
3. Search the build log for a message like: Run custom shell script 'XCStringsTool: Generate Swift code for ‘[YourCatalogName].xcstrings‘'.
4. The full file path to the generated .swift file will be printed in that log entry.

The Build Tool plugin automates code generation. It monitors your Strings Catalogs and invokes the generator whenever they are modified, writing Swift constants to your derived sources.

1. Navigate to your project settings in Xcode.
2. Select your desired target.
3. Go to the Build Phases tab.
4. Expand the Run Build Tool Plug-ins group.
5. Click the + button.
6. Select XCStringsToolPlugin from the list and click Add.

To use XCStrings Tool, ensure your environment meets the following criteria:

• Project Type: An Xcode project or a Swift Package project.
• Xcode Version: Xcode 15 or later.
• Localization Formats: Support for the new Strings Catalogs (.xcstrings) or legacy .strings and .stringsdict formats.

XCStrings Tool provides convenience methods to work seamlessly with SwiftUI, ensuring compatibility across different OS versions and types. The tool generates extensions for:

• Text.init(localizable:)
• LocalizedStringKey.init(localizable:)
• LocalizedStringKey.localizable(_:)
• LocalizedStringResource.localizable(_:)

These allow you to pass generated keys directly into SwiftUI views and modifiers.

var body: some View {
    List {
        // Using Text.init(localizable:)
        Text(localizable: .listContent)
    }
    // Using LocalizedStringKey.localizable(_:)
    .navigationTitle(.localizable(.headingTitle))
    .environment(\.locale, Locale(identifier: "fr"))
}

You can integrate the XCStrings Tool plugin directly into any Swift Package target that contains Strings Catalog files (.xcstrings). This provides seamless generation of Swift constants for your localized strings.

Note: Strings Catalogs are only supported on Apple Platforms.

When building for the first time after adding the plugin, Xcode will prompt you to trust it.

1. When the alert appears, review the plugin details.
2. Click Trust & Enable All.
3. Build your project.

You can verify the plugin ran successfully by checking the Report navigator in the Xcode left sidebar. Look for a message like: Run custom shell script 'XCStringsTool: Generate Swift code for ‘[YourCatalogName].xcstrings‘'.