Setup

To configure iOS SDK integration you need to:

• Upload your localization files to Crowdin. If you have existing translations, you can upload them as well. You can use one of the following options:
  • Crowdin CLI
  • Crowdin VS Code Plugin
  • Crowdin GitHub Action
  • and more
• Set up Distribution in Crowdin.
• Set up SDK and enable Over-The-Air Content Delivery feature.

Distribution is a CDN vault that mirrors the translated content of your project and is required for integration with iOS app.

• Creating a distribution in crowdin.com
• Creating a distribution in Crowdin Enterprise

info

• The download of translations happens asynchronously after the start of the application. The downloaded translations will be used the next time the app is launched, otherwise the previously cached translations will be used (or local translations if no cache exists).
• The CDN feature does not update the localization files, if you want to add new translations to the localization files, you need to do it yourself.
• Once the SDK receives the translations, they're stored on the device as application files for future sessions to minimize requests the next time the app is launched. The storage time can be configured using the intervalUpdatesEnabled option.
• CDN will cache all translations in the release for up to 1 hour and even if new translations are released in Crowdin, CDN may return them with a delay.

Getting Started

There are several ways to set up the SDK, depending on your project. Make sure you have completed the steps in the Installation section before proceeding.

Swift

Open the AppDelegate.swift file and add:

import CrowdinSDK

In the application method add:

let crowdinProviderConfig = CrowdinProviderConfig(hashString: "{distribution_hash}",
  sourceLanguage: "{source_language}")

CrowdinSDK.startWithConfig(crowdinSDKConfig, completion: {
    // SDK is ready to use, put code to change language, etc. here
})

Objective-C

In the AppDelegate.m add:

@import CrowdinSDK

or

#import<CrowdinSDK/CrowdinSDK.h>

In the application method add:

CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] initWithHashString:@"" sourceLanguage:@""];
CrowdinSDKConfig *config = [[[CrowdinSDKConfig config] withCrowdinProviderConfig:crowdinProviderConfig]];

[CrowdinSDK startWithConfig:config completion:^{
  // SDK is ready to use, put code to change language, etc. here
}];

If you have a pure Objective-C project, you will need to take some additional steps:

Add the following code to your Library Search Paths:

1. Add to Library Search Paths:

   $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)

2. Add use_frameworks! to your Podfile.

Alternative Setup: Info.plist

Configure basic SDK settings in your project's Info.plist file:

1. Add these keys to Info.plist:

   • CrowdinDistributionHash (String) - Your Crowdin CDN hash
   • CrowdinSourceLanguage (String) - Source language code in ISO 639-1 format

2. In your AppDelegate call the following method:

   • Swift: CrowdinSDK.start()
   • Objective-C: [CrowdinSDK start]

caution

The Info.plist configuration method does not support Screenshots and Real-Time Preview features. To use these features, configure the SDK programmatically.

Config Options Reference

The SDK configuration is done using the CrowdinSDKConfig class. The following options are available:

Option	Description	Example Value
hashString	Distribution Hash	"7a0c1...o3b"
sourceLanguage	Source language code (ISO 639-1)	sourceLanguage: "en"
organizationName	Organization domain (Enterprise only)	"mycompany"
settingsEnabled	Enable SDK Controls	true
accessToken	Crowdin API Access Token. An alternative to the OAuth-based authorization in the Screenshots and Real-Time Preview features	"your_token"

OAuth Options

The CrowdinLoginConfig class provides OAuth configuration options:

Option	Description	Example Value
clientId	Crowdin OAuth Client ID	"gpY2yT...x3TYB"
clientSecret	Crowdin OAuth Client Secret	"Xz95t...EDx9T"
scope	OAuth scope (e.g., project.screenshot, project)	"project"
redirectURI	Custom URL scheme for your app	"crowdintest://"

The CrowdinLoginConfig configuration is required for the Screenshots and Real-Time Preview features only.

info

Read more about creating an OAuth application in Crowdin.

Additional Features

Translations Update Interval

By default, SDK searches for new translation once per application load, but not more often than 15 minutes. You can update translations in application every defined interval. To enable this feature add pod CrowdinSDK/IntervalUpdate to your pod file:

1. Add to Podfile:

   pod 'CrowdinSDK/IntervalUpdate'

2. Configure in SDK:

   .with(intervalUpdatesEnabled: true, interval: {interval})

   Where interval - defines translations update time interval in seconds. Minimum allowed interval is 15 minutes (900 seconds).

Change locale programmatically

By default, the SDK relies on the device locale. To change the SDK target language on the fly regardless of the device locale.

You can use the CrowdinSDK.currentLocalization property to get or set the current localization language code (ISO 639-1) used by the Crowdin SDK. When you set this property, the SDK triggers a localization download if needed:

import CrowdinSDK

// Set the current localization to German
CrowdinSDK.currentLocalization = "<language_code>"

// ...

// Get the current localization
if let currentLocale = CrowdinSDK.currentLocalization {
    print("Current localization: \(currentLocale)")
} else {
    print("Using default localization")
}

This is the recommended way to change the language programmatically. The SDK will download the new localization if it's not already available. If set to nil - the localization will be detected automatically based on the languages available in Crowdin and the system's preferred languages.

caution

The UI doesn't update automatically. You must manually update the UI after changing the localization.

addDownloadHandler closure

The addDownloadHandler method allows you to add a closure that will be called every time new localization is downloaded. This can be useful for performing actions such as updating the user interface or processing the newly downloaded localization data:

let handlerId = CrowdinSDK.addDownloadHandler {
    print("New localization downloaded!")
    // Perform additional actions, such as updating the UI
}

// Optionally, you can remove the handler later if needed
CrowdinSDK.removeDownloadHandler(handlerId)

SwiftUI Support

SwiftUI support requires explicit localization calls. Use either:

Text(NSLocalizedString("key", comment: "comment"))

or the convenience extension:

Text("key".cw_localized)

View the Swift UI Localization guide for more information.

Supported Localization File Formats

The Crowdin SDK supports the following localization file formats:

• iOS Strings and Stringsdict (.strings, .stringsdict)
• Apple XLIFF (.xliff)
• Apple Strings Catalog (.xcstrings). ⚠️ Only the CDN Content Delivery feature is available for the Apple Strings Catalog format. The Screenshots and Real-Time Preview features are not yet supported.