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:
- 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.
- 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:
-
Add to Library Search Paths:
$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)
-
Add
use_frameworks!
to yourPodfile
.
Alternative Setup: Info.plist
Configure basic SDK settings in your project's Info.plist
file:
-
Add these keys to Info.plist:
CrowdinDistributionHash
(String) - Your Crowdin CDN hashCrowdinSourceLanguage
(String) - Source language code in ISO 639-1 format
-
In your
AppDelegate
call the following method:- Swift:
CrowdinSDK.start()
- Objective-C:
[CrowdinSDK start]
- Swift:
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.
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:
-
Add to
Podfile
:pod 'CrowdinSDK/IntervalUpdate'
-
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.
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.