Tolgee Mobile Swift SDK 🐁

What is Tolgee?

Tolgee is a powerful localization platform that simplifies the translation process for your applications. This SDK provides integration for iOS and macOS projects.

✨ Features

• 🌍 Remote translation loading from Tolgee CDN with automatic updates
• 📦 Namespace-based organization for scalable translation management
• 💾 Intelligent caching with ETag support and background synchronization
• 🔄 Automatic fallback to bundle-based localizations when offline
• 🎯 Smart language detection from device settings with manual override
• ⚡ Modern async/await API for Swift concurrency
• 🔧 SwiftUI integration with reactive updates and TolgeeText component
• 📱 Multi-platform support for iOS, macOS, tvOS, and watchOS
• 🔍 Advanced debugging with comprehensive logging

Installation

Note

For managing static translations (used as fallback), check out tolgee-cli. It provides tools for updating and syncing your static translation files.

In each demo project you can find an example of .tolgeerc configuration file.

🚀 Quick Start

Here's a quick example of initializing Tolgee in an iOS application:

import Tolgee

// Initialize with your Tolgee CDN URL
let cdnURL = URL(string: "https://cdn.tolgee.io/your-project-id")!
Tolgee.shared.initialize(cdn: cdnURL)

// Fetch latest translations asynchronously
await Tolgee.shared.remoteFetch()

// Use translations throughout your app
let greeting = Tolgee.shared.translate("hello_world")
let personalGreeting = Tolgee.shared.translate("hello_name", "Alice")

📦 Installation

Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/tolgee/tolgee-mobile-swift-sdk", from: "1.0.0")
]

Or through Xcode:

1. File → Add Package Dependencies...
2. Enter: https://github.com/tolgee/tolgee-mobile-swift-sdk
3. Choose version and add to your target

🎯 Basic Usage

Initialization

import Tolgee

// Set the CDN format to Apple in your Tolgee project
let cdnURL = URL(string: "https://cdn.tolgee.io/your-project-id")!
Tolgee.shared.initialize(cdn: cdnURL)

Refer to our SwiftUI and UIKit examples for a complete setup.

Advanced Initialization

// Initialize with specific language and namespaces
Tolgee.shared.initialize(
    cdn: URL(string: "https://cdn.tolgee.io/your-project-id")!,
    language: "es", // Force Spanish instead of auto-detection
    namespaces: ["buttons", "errors", "onboarding"], // Organize translations
    enableDebugLogs: true // Enable detailed logging for development
)

Fetch Remote Translations

You have to explicitly call the fetch method to fetch translations from the CDN.

await Tolgee.shared.remoteFetch()

Basic Translation

// Simple string translation
let title = Tolgee.shared.translate("app_title")

// Translation with arguments
let welcomeMessage = Tolgee.shared.translate("welcome_user", "John")
let itemCount = Tolgee.shared.translate("items_count", 5)
let nameAndAge = Tolgee.shared.translate("My name is %@ and I'm %lld years old", "John", 30)

Note

Strings with multiple pluralized parameters are currently not supported, for example Tolgee.shared.translate("I have %lld apples and %lld oranges", 2, 3)

🔧 SwiftUI Integration

Tolgee works great with SwiftUI, including previewing views in different localizations using SwiftUI previews.

You can use the TolgeeText component which will automatically use the injected locale on iOS 18.4+

import SwiftUI
import Tolgee

struct ContentView: View {
    var body: some View {
        TolgeeText("welcome_title")
    }
}

#Preview("English") {
    ContentView()
        .environment(\.locale, Locale(identifier: "en"))
}

#Preview("Czech") {
    ContentView()
        .environment(\.locale, Locale(identifier: "cs"))
}

or use a version of the translate method that accepts locale param on iOS 18.4 and newer. The older implementation will fall back to the system language.

struct ContentView: View {
    @Environment(\.locale) var locale
    
    var body: some View {
        if #available(iOS 18.4, *) {
            Text(Tolgee.shared.translate("welcome_title", locale: locale))
        } else {
            Text(Tolgee.shared.translate("welcome_title"))
        }
    }
}

#Preview("English") {
    ContentView()
        .environment(\.locale, Locale(identifier: "en"))
}

#Preview("Czech") {
    ContentView()
        .environment(\.locale, Locale(identifier: "cs"))
}

Reactive Updates

Tolgee provides a hook to allow the consumer of the SDK to be notified about when the translation cache has been updated.

Task {
    for await _ in Tolgee.shared.onTranslationsUpdated() {
        // update your UI
    }
}

When using SwiftUI, Tolgee offers a convenience utility that automatically triggers a redraw of a view when the translations cache has been updated.

struct ContentView: View {
    
    // This will automatically re-render the view when
    // the localization cache is updated from a CDN.
    @StateObject private var updater = TolgeeSwiftUIUpdater()
    
    var body: some View {
        VStack {
            TolgeeText("My name is %@ and I have %lld apples", "John", 3)
        }
    }
}

Swizzling of Apple's APIs

Tolgee optionally supports swizzling of Bundle.localizedString, which is being used by NSLocalizedString function. In order to enable swizzling, set enviromental variable TOLGEE_ENABLE_SWIZZLING=true in your scheme settings. Refer to our UIKit example to see it in action.

Following calls will then be backed by the Tolgee SDK:

Bundle.main.localizedString(forKey: "welcome_message")
NSLocalizedString("welcome_message", comment: "")

Note

Plural strings are currently not supported and will fall back to using the string bundled with the app.

🌐 Advanced Features

Custom Tables/Namespaces

Tolgee iOS SDK supports loading of local translations from multiple local tables by providing the table parameter. When using .xcstrings files, the names of the tables match the names of your files without the extension. You do not need to provide the table name when loading strings stored in the default Localizable.xcstrings file.

To have the OTA updates working properly, make sure that you have enabled namespaces for your Tolgee project and that you have created namespaces matching the names of your local tables.

// Initialize with multiple namespaces for better organization
Tolgee.shared.initialize(
    cdn: cdnURL,
    namespaces: ["common", "auth", "profile", "settings"]
)

// Use translations from specific namespaces
let commonGreeting = Tolgee.shared.translate("hello", table: "common")
// or for SwiftUI
TolgeeText("hello", table: "common")

Custom Bundles

You may have your strings resources stored in a dedicated XCFramework or a Swift Package.

let bundle: Bundle = ... // access the bundle

// Use the SDK directly
let commonGreeting = Tolgee.shared.translate("hello", bundle: bundle)
// or for SwiftUI
TolgeeText("hello", bundle: bundle)

Log Forwarding

Tolgee allows forwarding of logs that are printed to the console by default. You can use this feature to forward errors and other logs into your analytics.

for await logMessage in Tolgee.shared.onLogMessage() {
    // Here you can forward logs from Tolgee SDK to your analytics SDK.
}

📱 Platform Support

Platform	Minimum Version
iOS	16.0+
macOS	13.0+
tvOS	16.0+
watchOS	6.0+

⚙️ Requirements

• Swift: 6.0+
• Xcode: 16.3+

🧵 Thread-safety

Tolgee SDK is designed to be used synchronously on the main actor (except the fetch method). Access to the SDK from other actors generally has to be awaited.

Task.deattached {
    // notice that the call has to be awaited outside of the main actor
    let str = await Tolgee.shared.translate("key")
}

🤝 Why Choose Tolgee?

Tolgee saves a lot of time you would spend on localization tasks otherwise. It enables you to provide perfectly translated software.

All-in-one localization solution for your iOS application 🙌

Translation management platform 🎈

Open-source 🔥

Learn more on the Tolgee website →

📚 Examples & Demos

Check out our example projects:

• SwiftUI Integration
• UIKit Integration

🆘 Need Help?

• 📖 Documentation
• 💬 Community Slack
• 🐛 Report Issues
• 💡 Feature Requests

🏗️ Contributing

Contributions are welcome!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by the Tolgee team