Lokalise iOS SDK
Lokalise iOS SDK comes as CocoaPod library and can be easily integrated into your Objective-C or Swift project. Once the translations are finalized in Lokalise editor, you generate bundle using Lokalise Download page (or use the API request to generate it). As end user opens your app on his device, the SDK requests latest version of the bundle from our servers and if found downloads and stores it locally.
- Over-the-air (OTA) localization
- Instant UI language switching
- Test localizations (using prerelease bundles)
- NSBundle swizzling for transparent integration
- XIB and storyboard localization
Some of the system inteface objects might not get translated (search bar for example) when changing application language at runtime.
In case you choose not to use swizzling, storyboards and nibs will not be localized using our SDK.
Step 1: Set up your project in Lokalise
If you have not done so yet, add new project in Lokalise, upload source language files you may have (or just add keys straight in Lokalise's editor if it's a new app you are building). Take a note of project ID, that can be found in project settings, usually it looks like this:
Step 2: Generate the bundle
Go to Downloads page in Lokalise, select "Lokalise iOS SDK" as the format and click Build only button to generate the bundle. You will be automatically taken to the bundle versions management page at projects settings. Leave the switches as is for now, see details in Managing bundles section.
Step 3: Install Lokalise SDK
To install using CocoaPods simply add this line to your Podfile
pod 'Lokalise', '~> 0.5.0'
Dependencies will be installed automatically.
Initialising the SDK
We recommend initiate Lokalise iOS SDK within - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
// Provide API Token and Project ID [[Lokalise sharedObject] setAPIToken:@"API Token" projectID:@"Project ID"]; // Subscribe to Lokalise events [Lokalise sharedObject].delegate = self; // Enable swizzling [[Lokalise sharedObject] swizzleMainBundle]; // Update translations to the latest version [[Lokalise sharedObject] checkForUpdates];
You need to update the interface as soon as Lokalise updates the language bundle. Monitor the following event and update your UI when necessary:
No updates are needed to your code with swizzling enabled, refer to the keys as usual:
NSLocalizedString(@"key", @"comment"); NSLocalizedStringFromTable(@"key", @"tableName", @"comment");
If you have not enabled bundle swizzling, you can refer to the keys using Lokalise SDK directly:
[[Lokalise sharedObject] localizedStringForKey:@"key" value:@"default value" table:@"table name"];
Lokalise supports production and prerelease versions of the bundle and lets you keep different versions of each bundle. Once you generate new bundle via Downloads on Lokalise web dashboard (or using the API call) it goes to the list of bundles that can be found under project settings' Lokalise iOS bundles tab.
Testing your localizations
If you are building for TestFlight or Crashlytics and don't want to mess up production app's strings, want to see local translation or no translation at all, it's handy to use localizationType option.
// Loads production localization (Default type). [Lokalise sharedObject].localizationType = LokaliseLocalizationRelease; // Loads prerelease localization. [Lokalise sharedObject].localizationType = LokaliseLocalizationPrerelease; // Uses localization included in local app bundle. [Lokalise sharedObject].localizationType = LokaliseLocalizationLocal; // Returns keys instead of localized string. [Lokalise sharedObject].localizationType = LokaliseLocalizationDebug;
You need to add language in your Xcode project, only then it becomes available in the app. Lokalise SDK does not dynamically add language to the app if you add it in Lokalise.
If you encounter crash that recursively calls these methods
[NSBundle(Lokalise) lokalise_localizedStringsForKey:value:table:] [Lokalise localizedStringForKey:value:table:]
Ensure that your Localizable.strings and other .strings files are localized as default language of your project and NOT Base language.
If this doesn't help or you are experiencing other issues contacts us in live support chat that you can find in bottom right corner of this page.