{"id":30792083,"url":"https://github.com/tolgee/tolgee-mobile-swift-sdk","last_synced_at":"2026-01-12T10:26:08.663Z","repository":{"id":309625989,"uuid":"1036719477","full_name":"tolgee/tolgee-mobile-swift-sdk","owner":"tolgee","description":"Apple platforms SDK delivering Over-the-Air translation updates for iOS \u0026 macOS","archived":false,"fork":false,"pushed_at":"2026-01-02T12:15:08.000Z","size":248,"stargazers_count":7,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-08T14:58:47.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tolgee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tolgee"]}},"created_at":"2025-08-12T13:39:34.000Z","updated_at":"2025-12-26T16:24:31.000Z","dependencies_parsed_at":"2025-09-05T15:52:08.545Z","dependency_job_id":null,"html_url":"https://github.com/tolgee/tolgee-mobile-swift-sdk","commit_stats":null,"previous_names":["tolgee/tolgee-mobile-swift-sdk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tolgee/tolgee-mobile-swift-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Ftolgee-mobile-swift-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Ftolgee-mobile-swift-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Ftolgee-mobile-swift-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Ftolgee-mobile-swift-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tolgee","download_url":"https://codeload.github.com/tolgee/tolgee-mobile-swift-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Ftolgee-mobile-swift-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-05T15:36:57.401Z","updated_at":"2026-01-12T10:26:08.655Z","avatar_url":"https://github.com/tolgee.png","language":"Swift","funding_links":["https://github.com/sponsors/tolgee"],"categories":[],"sub_categories":[],"readme":"# Tolgee Mobile Swift SDK 🐁\n\n[![Tolgee](https://img.shields.io/badge/Tolgee-f06695)](https://tolgee.io/)\n![Android](https://img.shields.io/badge/iOS-Supported-green?logo=ios)\n![language](https://img.shields.io/github/languages/top/tolgee/tolgee-mobile-swift-sdk)\n[![github release](https://img.shields.io/github/v/release/tolgee/tolgee-mobile-swift-sdk?label=GitHub%20Release)](https://github.com/tolgee/tolgee-mobile-swift-sdk/releases/latest)\n![Licence](https://img.shields.io/github/license/tolgee/tolgee-mobile-swift-sdk)\n[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-mobile-swift-sdk?style=social\u0026label=Tolgee%20Mobile%20Swift%20SDK)](https://github.com/tolgee/tolgee-mobile-swift-sdk)\n[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-platform?style=social\u0026label=Tolgee%20Platform)](https://github.com/tolgee/tolgee-platform)\n[![Github discussions](https://img.shields.io/github/discussions/tolgee/tolgee-platform)](https://github.com/tolgee/tolgee-platform/discussions)\n[![Dev.to](https://img.shields.io/badge/Dev.to-tolgee_i18n?logo=devdotto\u0026logoColor=white)](https://dev.to/tolgee_i18n)\n[![Read the Docs](https://img.shields.io/badge/Read%20the%20Docs-8CA1AF?logo=readthedocs\u0026logoColor=fff)](https://docs.tolgee.io/)\n[![Slack](https://img.shields.io/badge/Slack-4A154B?logo=slack\u0026logoColor=fff)](https://tolg.ee/slack)\n[![YouTube](https://img.shields.io/badge/YouTube-%23FF0000.svg?logo=YouTube\u0026logoColor=white)](https://www.youtube.com/@tolgee)\n[![LinkedIn](https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white\u0026logoColor=fff)](https://www.linkedin.com/company/tolgee/)\n[![X](https://img.shields.io/badge/X-%23000000.svg?logo=X\u0026logoColor=white)](https://x.com/Tolgee_i18n)\n\n## What is Tolgee?\n\n[Tolgee](https://tolgee.io/) is a powerful localization platform that simplifies the translation process for your applications.\nThis SDK provides integration for iOS and macOS projects.\n\n## ✨ Features\n\n- 🌍 **Remote translation loading** from Tolgee CDN with automatic updates\n- 📦 **Namespace-based organization** for scalable translation management  \n- 💾 **Intelligent caching** with ETag support and background synchronization\n- 🔄 **Automatic fallback** to bundle-based localizations when offline\n- 🎯 **Smart language detection** from device settings with manual override\n- ⚡ **Modern async/await API** for Swift concurrency\n- 🔧 **SwiftUI integration** with reactive updates and `TolgeeText` component\n- 📱 **Multi-platform support** for iOS, macOS, tvOS, and watchOS\n- 🔍 **Advanced debugging** with comprehensive logging \n\n\n## Installation\n\n\u003e [!NOTE]\n\u003e For managing static translations (used as fallback), check out [tolgee-cli](https://github.com/tolgee/tolgee-cli).\n\u003e It provides tools for updating and syncing your static translation files.\n\u003e\n\u003e In each demo project you can find an example of `.tolgeerc` configuration file.\n\n\n\n## 🚀 Quick Start\n\nHere's a quick example of initializing Tolgee in an iOS application:\n\n```swift\nimport Tolgee\n\n// Initialize with your Tolgee CDN URL\nlet cdnURL = URL(string: \"https://cdn.tolgee.io/your-project-id\")!\nTolgee.shared.initialize(cdn: cdnURL)\n\n// Fetch latest translations asynchronously\nawait Tolgee.shared.remoteFetch()\n\n// Use translations throughout your app\nlet greeting = Tolgee.shared.translate(\"hello_world\")\nlet personalGreeting = Tolgee.shared.translate(\"hello_name\", \"Alice\")\n```\n\n## 📦 Installation\n\n### Swift Package Manager\n\nAdd to your `Package.swift`:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/tolgee/tolgee-mobile-swift-sdk\", from: \"1.0.0\")\n]\n```\n\nOr through Xcode:\n1. File → Add Package Dependencies...\n2. Enter: `https://github.com/tolgee/tolgee-mobile-swift-sdk`\n3. Choose version and add to your target\n\n## 🎯 Basic Usage\n\n### Initialization\n\n```swift\nimport Tolgee\n\n// Set the CDN format to Apple in your Tolgee project\nlet cdnURL = URL(string: \"https://cdn.tolgee.io/your-project-id\")!\nTolgee.shared.initialize(cdn: cdnURL)\n```\n\nRefer to our SwiftUI and UIKit examples for a complete setup.\n\n### Advanced Initialization\n\n```swift\n// Initialize with specific language and namespaces\nTolgee.shared.initialize(\n    cdn: URL(string: \"https://cdn.tolgee.io/your-project-id\")!,\n    locale: Locale(identifier: \"pt_BR\"), // Override the system locale\n    language: \"pt-BR\", // Override the language name on Tolgee CDN\n    namespaces: [\"buttons\", \"errors\", \"onboarding\"], // Organize translations\n    enableDebugLogs: true // Enable detailed logging for development\n)\n```\n\n### Fetch Remote Translations\nYou have to explicitly call the `fetch` method to fetch translations from the CDN.\n```swift\nawait Tolgee.shared.remoteFetch()\n```\n\n### Basic Translation\n\n```swift\n// Simple string translation\nlet title = Tolgee.shared.translate(\"app_title\")\n\n// Translation with arguments\nlet welcomeMessage = Tolgee.shared.translate(\"welcome_user\", \"John\")\nlet itemCount = Tolgee.shared.translate(\"items_count\", 5)\nlet nameAndAge = Tolgee.shared.translate(\"My name is %@ and I'm %lld years old\", \"John\", 30)\n```\n\n\u003e [!NOTE]\n\u003e Strings with multiple pluralized parameters are currently **not supported**, for example `Tolgee.shared.translate(\"I have %lld apples and %lld oranges\", 2, 3)`\n\n### 🔧 SwiftUI Integration\n\nTolgee works great with SwiftUI, including previewing views in different localizations using SwiftUI previews.\n\nYou can use the `TolgeeText` component which will automatically use the injected locale\n```swift\nimport SwiftUI\nimport Tolgee\n\nstruct ContentView: View {\n    var body: some View {\n        TolgeeText(\"welcome_title\")\n    }\n}\n\n#Preview(\"English\") {\n    ContentView()\n        .environment(\\.locale, Locale(identifier: \"en\"))\n}\n\n#Preview(\"Czech\") {\n    ContentView()\n        .environment(\\.locale, Locale(identifier: \"cs\"))\n}\n```\n\nor use a version of the `translate` method that accepts `locale` param.\n\n```swift\nstruct ContentView: View {\n    @Environment(\\.locale) var locale\n    \n    var body: some View {\n        Text(Tolgee.shared.translate(\"welcome_title\", locale: locale))\n    }\n}\n\n#Preview(\"English\") {\n    ContentView()\n        .environment(\\.locale, Locale(identifier: \"en\"))\n}\n\n#Preview(\"Czech\") {\n    ContentView()\n        .environment(\\.locale, Locale(identifier: \"cs\"))\n}\n```\n\n\u003e [!NOTE]\n\u003e The `locale` parameter in `translate(...)` methods is primarily intended for SwiftUI previews. When set to a non-current locale, translations from the CDN will be ignored and only bundle localizations will be used. If a custom locale is set on the SDK level via `initialize(...)` or `setCustomLocale(...)`, it will take precedence and the locale parameter will be ignored.\n\n### Reactive Updates\n\nTolgee provides a hook to allow the consumer of the SDK to be notified about when the translation cache has been updated.\n\n```swift\nTask {\n    for await _ in Tolgee.shared.onTranslationsUpdated() {\n        // update your UI\n    }\n}\n```\n\nWhen using SwiftUI, `TolgeeText` will automatically update. Tolgee additionally offers a convenience utility that automatically triggers a redraw of a view when the translations cache has been updated.\n\n```swift\nstruct ContentView: View {\n    \n    // This will automatically re-render the view when\n    // the localization cache is updated from a CDN.\n    @StateObject private var updater = TolgeeSwiftUIUpdater()\n    \n    var body: some View {\n        VStack {\n            TolgeeText(\"My name is %@ and I have %lld apples\", \"John\", 3)\n        }\n    }\n}\n```\n\n### Swizzling of Apple's APIs\nTolgee 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.\n\nFollowing calls will then be backed by the Tolgee SDK:\n```swift\nBundle.main.localizedString(forKey: \"welcome_message\")\nNSLocalizedString(\"welcome_message\", comment: \"\")\n```\n\n\u003e [!NOTE]\n\u003e Plural strings are currently not supported and will fall back to using the string bundled with the app.\n\n## 🌐 Advanced Features\n\n### Language Overwrite\n\nYou can override the default system language to display translations in a specific language. This is useful when implementing custom language switchers or when you want to force a specific language regardless of the device settings.\n\n#### Setting Language During Initialization\n\nYou can set a custom language when initializing Tolgee:\n\n```swift\n// Override both locale and language\nTolgee.shared.initialize(\n    cdn: cdnURL,\n    locale: Locale(identifier: \"pt_BR\"), // Override the system locale\n    language: \"pt-BR\" // Override the language name on Tolgee CDN\n)\n\n// Or just override the locale (language is extracted automatically)\nTolgee.shared.initialize(\n    cdn: cdnURL,\n    locale: Locale(identifier: \"pt_BR\")\n)\n```\n\n#### Changing Language at Runtime\n\nUse `setCustomLocale(_:language:)` to change the language dynamically:\n\n```swift\n// Set custom locale (language is extracted automatically)\ntry Tolgee.shared.setCustomLocale(Locale(identifier: \"fr\"))\n\n// Or specify a custom language for the CDN if it differs from the locale\ntry Tolgee.shared.setCustomLocale(\n    Locale(identifier: \"pt_BR\"),\n    language: \"pt-BR\" // CDN language code\n)\n\n// Fetch translations for the new language\nawait Tolgee.shared.remoteFetch()\n```\n\n#### Resetting to System Language\n\nTo return to the device's system language:\n\n```swift\ntry Tolgee.shared.setCustomLocale(.current)\nawait Tolgee.shared.remoteFetch()\n```\n\n#### Pre-fetching all available languages from the CDN\n\nYou can pre-fetch all languages supported by your app:\n\n```swift\nawait withTaskGroup(of: Void.self) { group in\n    for language in Bundle.main.localizations {\n        group.addTask {\n            await Tolgee.shared.remoteFetch(language: language)\n        }\n    }\n}\n```\n\n### Custom Tables/Namespaces\nTolgee 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.\n\nTo 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.\n\n```swift\n// Initialize with multiple namespaces for better organization\nTolgee.shared.initialize(\n    cdn: cdnURL,\n    namespaces: [\"common\", \"auth\", \"profile\", \"settings\"]\n)\n\n// Use translations from specific namespaces\nlet commonGreeting = Tolgee.shared.translate(\"hello\", table: \"common\")\n// or for SwiftUI\nTolgeeText(\"hello\", table: \"common\")\n```\n\n### Custom Bundles\n\nYou may have your strings resources stored in a dedicated XCFramework or a Swift Package.\n\n```swift\nlet bundle: Bundle = ... // access the bundle\n\n// Use the SDK directly\nlet commonGreeting = Tolgee.shared.translate(\"hello\", bundle: bundle)\n// or for SwiftUI\nTolgeeText(\"hello\", bundle: bundle)\n```\n\n### Log Forwarding\nTolgee allows forwarding of logs that are printed to the console by default.\nYou can use this feature to forward errors and other logs into your analytics.\n\n```swift\nfor await logMessage in Tolgee.shared.onLogMessage() {\n    // Here you can forward logs from Tolgee SDK to your analytics SDK.\n}\n```\n\n\n## 📱 Platform Support\n\n| Platform | Minimum Version | \n|----------|----------------|\n| iOS      | 16.0+          |\n| macOS    | 13.0+          |\n| tvOS     | 16.0+          |\n| watchOS  | 6.0+           |\n\n## ⚙️ Requirements\n\n- **Swift:** 6.0+\n- **Xcode:** 16.0+\n\n## 🧵 Thread-safety\n\nTolgee 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.\n\n```swift\nTask.deattached {\n    // notice that the call has to be awaited outside of the main actor\n    let str = await Tolgee.shared.translate(\"key\")\n}\n```\n\n## 🤝 Why Choose Tolgee?\n\n**Tolgee saves a lot of time** you would spend on localization tasks otherwise. It enables you to provide **perfectly translated software**.\n\n### All-in-one localization solution for your iOS application 🙌\n### Translation management platform 🎈\n### Open-source 🔥\n\n[Learn more on the Tolgee website →](https://tolgee.io)\n\n## 📚 Examples \u0026 Demos\n\nCheck out our example projects:\n- [SwiftUI Integration](Examples/TolgeeSwiftUIExample)\n- [UIKit Integration](Examples/TolgeeUIKitExample)\n\n## 🆘 Need Help?\n\n- 📖 [Documentation](https://docs.tolgee.io)\n- 💬 [Community Slack](https://tolg.ee/slack)\n- 🐛 [Report Issues](https://github.com/petrpavlik/tolgee-ios/issues)\n- 💡 [Feature Requests](https://github.com/petrpavlik/tolgee-ios/discussions)\n\n## 🏗️ Contributing\n\nContributions are welcome!\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://tolgee.io\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/18496315/188628892-33fcc282-44f1-4926-8be4-d0db5a2420ca.png\" alt=\"Tolgee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nMade with ❤️ by the \u003ca href=\"https://github.com/tolgee\"\u003eTolgee team\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolgee%2Ftolgee-mobile-swift-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftolgee%2Ftolgee-mobile-swift-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolgee%2Ftolgee-mobile-swift-sdk/lists"}