Navigating the Apple Localization Format Jungle

Strings Files (.strings, .stringsdict)

.strings and .stringsdict files are what is used at runtime in iOS, iPadOS and MacOS apps. Both formats work out of the box with our SDK, Command Line Interface (CLI), as well as manual import and export on the dashboard.

String Catalogs (.xcstrings)

String catalogs are a new feature introduced by Apple which conveniently detects and organizes translations for keys or hard-coded values used throughout the project. Xcode now has a new screen to manage that, and it works by scanning the source code and extracting these values. The process is performed as part of each build and any changes will be detected and updated.

Internally, Xcode stores those strings and translations into a .json file called Localizable.xcstrings

To preserve backward compatibility, Xcode automatically generates the previously used Localizable.strings. These generated .strings files are the ones added to the bundle and loaded during runtime. This allows, for example, the SDK to also work seamlessly with string catalogs the same way as before without any additional work.

In Xcode, the Build Settings provide these flags to control the behavior for detecting strings for each target:

• Use compiler to extract swift strings: when disabled, only ObjC strings will be detected. This option can be used to disable extraction for each target separately.
• Localized String SwiftUI Support: also includes values from SwiftUI views like Text

If you want to import strings from a String Catalog into the GlobalLink Strings dashboard, you need to export the strings into a Localization Catalog.

Localization Catalogs (.xcloc)

A Localization Catalog can be generated by Xcode on demand. It contains all the localizable resources for each language and region found in the project. It is a package (folder) with the .xcloc extension and it includes an .xliff and other files metadata to be used as a distributable package for sending off localizable content. The embedded .xliff file can be imported to the GlobalLink Strings dashboard manually or using the CLI. The .xliff will be available for each language inside the Localized Contents folder.

Using the SDK

Since at runtime everything is converted to .strings and .stringsdict files, the SDK works out of the box no matter how you distribute your localizable content. The SDK automatically uploads the latest keys with translations when running in draft mode or when the debugger is connected. For more details on this, please see our SDK Documentation.

Using the Command Line Interface (CLI)

Import (Source Language Upload)

In order to import a String Catalog (.xcstrings) into the dashboard, it needs to be converted into a Localization Catalogs (.xcloc).

1. To accomplish this in the command line, you need to execute the following command with the relevant parameters set for your project:

xcodebuild -exportLocalizations -project <projectname> -localizationPath <dirpath> [[-exportLanguage <targetlanguage>] ...]

Note: dirpath will be created inside the project folder.

Afterwards you can upload the generated .xliff inside the Localization Catalog as outlined below.

2. Inside the .applanga.json, set the file format to xliff, and make sure the path is inside the <dirpath> used in step 1:

{
 "app": {
    "access_token": ".....",
        "base_language": "en",
        "push": {
            "source": [
                {
                    "language": "en",
                    "file_format": "xliff", 
                    "path": "YourProject Localizations/en.xcloc/Localized Contents/en.xliff",
                }
            ]
        }
    }
}

3. Run applanga push to upload.

Export (Target Localization Download)

1. Inside the .applanga.json set the file format to .xliff:

{
    "app":{
        "access_token":".....",
        "base_language":"en",
        "pull":{
            "target":[
                {
                    "file_format":"xliff",
                    "path":"./some/path/<language>.xliff",
                    "tag":"app:language.xliff"
                }
            ]
        }
    }
}

2. Run applanga pull command, this will download the .xliff to the path you set in the above .json.

3. Run the following command with the relevant parameter set for your project, and dirpath used in step 1:

xcodebuild -importLocalizations -project <projectname> -localizationPath <dirpath>

For more details on the CLI configuration, please see the CLI documentation.

Manual Import & Export

Import

1. From Xcode, click the Product > Export Localizations menu option and select a path to save the output as a Localization Catalog.

2. Locate the .xliff file inside the Localized Contents folder of the generated Localization Catalogs (.xcloc) file. You can navigate into such a package by right clicking onto it and select Show Package Contents.

3. Upload the .xliff to your project

Export

1. Follow the steps in our documentation on manual exports to generate an .xliff file

2. Start the Xcode import process by clicking on the Product > Import Localizations menu option and choose the .xliff for your required language

3. For more information see: https://developer.apple.com/documentation/xcode/importing-localizations#Import-localizations-using-Xcode