iOS SDK - Quick Start Guide

Prerequisites

iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+
Swift 5.7+
Xcode 14.0+
A GetTranslated account and API key

🎯 Getting Started: To use translations in your app, you only need to:

Create a project and use the CLI to translate your strings
Call GetTranslated.initialize(key: "your-ck-api-key") in your AppDelegate

That's it! The SDK automatically handles language detection, caching, and all other functionality. Language management, dynamic strings, user authentication, callbacks, and other features are optional and only needed if you want to customize the default behavior.

Step 1: Installation

Option A: Swift Package Manager (Recommended)

1. In Xcode, go to File → Add Packages...

2. Enter the repository URL: https://github.com/get-translated/ios-sdk.git

3. Select version: 1.0.0 or Up to Next Major Version

4. Add to your target

// Or add to your Package.swift
dependencies: [
    .package(url: "https://github.com/get-translated/ios-sdk.git", from: "1.0.0")
]

Option B: CocoaPods

Add to your Podfile:

pod 'GetTranslatedSDK', '~> 1.0.0'

Then run:

pod install

Step 2: Basic Setup

Initialize the SDK

Add the initialization code to your AppDelegate or SceneDelegate:

import GetTranslatedSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Initialize GetTranslated SDK (simple version)
    GetTranslated.initialize(key: "your-ck-api-key")
    
    return true
}

Initialize with Callback (Recommended)

For better error handling, use the callback version:

import GetTranslatedSDK

class AppDelegate: UIResponder, UIApplicationDelegate, InitCallback {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize with callback
        GetTranslated.initialize(key: "your-ck-api-key", callback: self)
        return true
    }
    
    func onInitSuccess() {
        print("SDK initialized successfully")
        // Check if initialized
        if GetTranslated.isInitialized() {
            let languages = GetTranslated.getLanguages()
            print("Supported languages: \(languages)")
        }
    }
    
    func onInitError(_ errorCode: Int, _ errorMessage: String) {
        print("Initialization failed: \(errorCode) - \(errorMessage)")
    }
}

Important:

Get your API key from your dashboard. Don't have an account? Sign up for free.
Initialize in AppDelegate or SceneDelegate before views are created for proper language persistence
Using the callback version is recommended for better error handling

Step 3: Basic Translation

Simple Translation

// Get a translation (synchronous)
let translated = GetTranslated.getDynamicString("Hello, World!")

// Display in your UI
label.text = translated

Translation with Callback

// Get a translation with callback (asynchronous)
GetTranslated.getDynamicString("Hello, World!") { translation in
    // Update UI on main thread
    DispatchQueue.main.async {
        label.text = translation
    }
} onError: { error in
    // Handle error
    print("Translation error: \(error)")
}

Step 4: Language Management (Optional)

Note: This section is optional. The SDK automatically handles language detection and selection. You only need to read this if you want to implement a custom language selector or manually control language settings.

Automatic Language Detection

Important: The SDK automatically sets the application language during initialization based on:

System preferences (device language)
Saved user overrides (if previously set)
Server language overrides (if provided)

You do not need to manually set the language unless you want to implement a custom language selector.

Manual Language Setting (Optional)

If you want to implement a language selector in your app, you can manually set the language:

// Optional: Only needed if implementing a language selector
GetTranslated.setLanguage("es") // Spanish
GetTranslated.setLanguage("fr") // French

Get Supported Languages

// Get all supported languages
let languages = GetTranslated.getLanguages()
for language in languages {
    print("Supported: \(language)")
}

Get Current Language

// Get current device language
let currentLang = GetTranslated.getCurrentLanguage()
print("Current: \(currentLang)")

// Check if SDK is initialized
if GetTranslated.isInitialized() {
    // SDK is ready to use
    let languages = GetTranslated.getLanguages()
}

Language Change Callbacks (Optional)

Register callbacks to automatically update your UI when the language changes:

class MyViewController: UIViewController, LanguageChangeCallback {
    override func viewDidLoad() {
        super.viewDidLoad()
        GetTranslated.onLanguageChange(self)
    }
    
    deinit {
        GetTranslated.offLanguageChange(self)
    }
    
    func onLanguageChanged(_ languageCode: String) {
        // Automatically update UI when language changes
        print("Language changed to: \(languageCode)")
        reloadTranslations()
    }
}

Step 5: User Management (Optional)

Note: This section is optional. The SDK automatically creates anonymous users by default. You only need to read this if you want to implement user authentication or track specific users.

Anonymous Users (Default)

The SDK automatically creates anonymous users when initialized without a user ID:

// Anonymous user (default)
GetTranslated.initialize(key: "your-ck-api-key")

Authenticated Users

Initialize with a specific user ID:

// With user ID
GetTranslated.initialize(key: "your-ck-api-key", userId: "user-123")

Login/Logout

// Simple login
GetTranslated.login(userId: "user-123")

// Login with callback
class MyViewController: UIViewController, InitCallback {
    func loginUser() {
        GetTranslated.login(userId: "user-123", callback: self)
    }
    
    func onInitSuccess() {
        print("Login successful")
    }
    
    func onInitError(_ errorCode: Int, _ errorMessage: String) {
        print("Login failed: \(errorCode) - \(errorMessage)")
    }
}

// Simple logout
GetTranslated.logout()

// Logout with callback
GetTranslated.logout(callback: self)

Step 6: Complete Example

Here's a complete example using the SDK in a view controller:

import UIKit
import GetTranslatedSDK

class ViewController: UIViewController {
    @IBOutlet weak var welcomeLabel: UILabel!
    @IBOutlet weak var descriptionLabel: UILabel!
    @IBOutlet weak var languageButton: UIButton!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        loadTranslations()
    }
    
    func loadTranslations() {
        // Load translations
        GetTranslated.getDynamicString("Welcome to our app!") { translation in
            DispatchQueue.main.async {
                self.welcomeLabel.text = translation
            }
        } onError: { error in
            print("Translation error: \(error)")
        }
        
        GetTranslated.getDynamicString("This is a sample translation app.") { translation in
            DispatchQueue.main.async {
                self.descriptionLabel.text = translation
            }
        } onError: { error in
            print("Translation error: \(error)")
        }
    }
    
    @IBAction func switchLanguage(_ sender: UIButton) {
        let currentLang = GetTranslated.getCurrentLanguage()
        let newLang = currentLang == "en" ? "es" : "en"
        
        GetTranslated.setLanguage(newLang)
        loadTranslations() // Re-translate all texts
        updateLanguageButton()
    }
    
    func updateLanguageButton() {
        let currentLang = GetTranslated.getCurrentLanguage()
        let buttonText = currentLang == "en" ? "Switch to Spanish" : "Switch to English"
        languageButton.setTitle(buttonText, for: .normal)
    }
}

Next Steps

Complete Integration Guide 📦 GitHub Repository Back to Developers