Skip to content

Commit e0b7730

Browse files
petrpavlikpetrpavlik
authored
Add documentation for Swift SDK (#993)
1 parent b4ffc3d commit e0b7730

File tree

13 files changed

+366
-5
lines changed

13 files changed

+366
-5
lines changed

‎docs.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,24 @@ const docs = [
3535
},
3636
},
3737
],
38+
[
39+
'@docusaurus/plugin-content-docs',
40+
{
41+
id: 'ios-sdk',
42+
path: 'ios-sdk',
43+
routeBasePath: 'ios-sdk',
44+
sidebarPath: require.resolve('./sidebariOSSdk.js'),
45+
lastVersion: 'current',
46+
includeCurrentVersion: true,
47+
editUrl: 'https://github.com/tolgee/documentation/tree/main',
48+
versions: {
49+
current: {
50+
banner: 'none',
51+
label: '1.x.x',
52+
},
53+
},
54+
},
55+
],
3856
[
3957
'@docusaurus/plugin-content-docs',
4058
{

‎ios-sdk/about.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
id: about
3+
title: Tolgee iOS SDK Overview
4+
slug: /
5+
description: Overview of Tolgee iOS SDK with Over‑the‑Air (OTA) localization updates and how to get started.
6+
---
7+
8+
> NOTE:
9+
> For managing static translations in your repository, consider using the [Tolgee CLI](/tolgee-cli/installation).
10+
11+
Tolgee iOS (and macOS) SDK makes it possible to deliver new translations from your Tolgee project directly to your application. This means you don’t need to release a new version through the App Store just to update localizations. With over-the-air updates, translations can be refreshed seamlessly in your app without requiring a manual update.
12+
13+
## Why use it
14+
15+
- __Avoid releases for copy changes__: Ship translation fixes and new languages without a new app build.
16+
- __Faster iteration__: Product/localization teams can push improvements instantly and validate in production.
17+
- __SwiftUI support__: You can still use features such as overwriting locales for your SwiftUI previews.
18+
- __Resilient by default__: Works offline with caching and resource fallbacks; fewer blank strings.
19+
20+
## What you can do
21+
22+
- __Over‑the‑Air (OTA) updates__: Deliver translations via CDN (Cloud or self‑host) with caching.
23+
- __UIKit and SwiftUI support__: with hooks for reactive updates of translations.
24+
- __Fallbacks and preloading__: The SDK will fallback to loading a translation bundled with your app in case of any error.
25+
- __Hosting options__: Tolgee Cloud CDN or your own CDN.
26+
- __Works with advanced codebases__: you can still have your translations split into multiple files and have them stored in a separate framework/package.
27+
28+
## Demo apps
29+
30+
- [__SwiftUI demo__](https://github.com/tolgee/tolgee-mobile-swift-sdk/tree/main/Examples/TolgeeSwiftUIExample)
31+
- [__UIKit demo__](https://github.com/tolgee/tolgee-mobile-swift-sdk/tree/main/Examples/TolgeeUIKitExample)
32+
33+
## Compatibility
34+
35+
The SDK currently supports iOS 16.0+ and macOS 13.0+ with integration via Swift Package Manager (SPM).
36+
37+
> NOTE:
38+
> Please reach out to us if you need support for older OS versions or integration through CocoaPods, we are happy to look into it.
39+
40+
## Get started
41+
42+
- __Installation__: Install and configure the SDK — [Installation](./get_started.mdx)
43+
- __SwiftUI compatibility__: Learn how Tolgee iOS SDK works with your SwiftUI code — [SwiftUI](./swiftui.mdx)
44+
- __NSLocalizedString swizzling__: Learn how to achieve zero config integration by enabling method swizzling — [Swizzling](swizzling.mdx)
45+
- __Advanced usage__: Tips and tricks for debugging and using the SDK with advanced codebases — [Advanced usage](./advanced.mdx)
46+
47+
## Next steps
48+
49+
- Install and configure the SDK: [Installation](./get_started.mdx)
50+
- Connect your app to the Tolgee Platform and manage translations collaboratively: [Platform docs](../platform/)
51+
- Generate or manage static strings with CLI: [Tolgee CLI](/tolgee-cli/installation)

‎ios-sdk/advanced.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: advanced
3+
title: Advanced usage
4+
description: Tips and tricks for debugging and using the SDK with advanced codebases.
5+
---
6+
7+
### Custom tables/namespaces
8+
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.
9+
10+
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.
11+
12+
```swift
13+
// Initialize with multiple namespaces for better organization
14+
Tolgee.shared.initialize(
15+
cdn: cdnURL,
16+
namespaces: ["common", "auth", "profile", "settings"]
17+
)
18+
19+
// Use translations from specific namespaces
20+
let commonGreeting = Tolgee.shared.translate("hello", table: "common")
21+
// or for SwiftUI
22+
TolgeeText("hello", table: "common")
23+
```
24+
25+
## Custom bundles
26+
27+
You may have your strings resources stored in a dedicated XCFramework or a Swift Package.
28+
29+
```swift
30+
let bundle: Bundle = ... // access the bundle
31+
32+
// Use the SDK directly
33+
let commonGreeting = Tolgee.shared.translate("hello", bundle: bundle)
34+
// or for SwiftUI
35+
TolgeeText("hello", bundle: bundle)
36+
```
37+
38+
## Listening for updates
39+
40+
Tolgee provides a hook to allow the consumer of the SDK to be notified about when the translation cache has been updated.
41+
42+
```swift
43+
Task {
44+
for await _ in Tolgee.shared.onTranslationsUpdated() {
45+
// update your UI
46+
}
47+
}
48+
```
49+
50+
## Log forwarding
51+
Tolgee allows forwarding of logs that are printed to the console by default.
52+
You can use this feature to forward errors and other logs into your analytics.
53+
54+
```swift
55+
for await logMessage in Tolgee.shared.onLogMessage() {
56+
// Here you can forward logs from Tolgee SDK to your analytics SDK.
57+
}
58+
```

‎ios-sdk/get_started.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
id: get_started
3+
title: Get started
4+
description: How to install Tolgee iOS SDK and basic usage instructions.
5+
---
6+
7+
## Platform Support
8+
9+
| Platform | Minimum Version |
10+
|----------|----------------|
11+
| iOS | 16.0+ |
12+
| macOS | 13.0+ |
13+
| tvOS | 16.0+ |
14+
| watchOS | 6.0+ |
15+
16+
## Requirements
17+
18+
- **Swift:** 6.0+
19+
- **Xcode:** 16.3+
20+
21+
## Adding the SDK
22+
23+
Add to your `Package.swift`:
24+
25+
```swift
26+
dependencies: [
27+
.package(url: "https://github.com/tolgee/tolgee-mobile-swift-sdk", from: "1.0.0")
28+
]
29+
```
30+
31+
Or through Xcode:
32+
1. File → Add Package Dependencies...
33+
2. Enter: `https://github.com/tolgee/tolgee-mobile-swift-sdk`
34+
3. Choose version and add to your target
35+
36+
## Initialization and configuration
37+
38+
Initialize the SDK with your [CDN URL](/platform/projects_and_organizations/content_delivery), typically in your AppDelegate or similar startup location:
39+
40+
```swift
41+
import Tolgee
42+
43+
let cdnURL = URL(string: "https://cdn.tolgee.io/your-project-id")!
44+
Tolgee.shared.initialize(cdn: cdnURL)
45+
```
46+
:::warning
47+
48+
Make sure that the format for your CDN files is set to `Apple SDK` in your Tolgee project developer/cdn settings.
49+
Learn more about [Tolgee Content Delivery](/platform/projects_and_organizations/content_delivery) feature.
50+
51+
:::
52+
53+
> **TIP**:
54+
> Refer to our SwiftUI and UIKit [examples](https://github.com/tolgee/tolgee-mobile-swift-sdk/tree/main/Examples) for a complete setup.
55+
56+
57+
You can customize the initialization with additional parameters:
58+
```swift
59+
// Initialize with specific language and namespaces
60+
Tolgee.shared.initialize(
61+
cdn: URL(string: "https://cdn.tolgee.io/your-project-id")!,
62+
language: "es", // Force Spanish instead of auto-detection
63+
namespaces: ["buttons", "errors", "onboarding"], // Organize translations
64+
enableDebugLogs: true // Enable detailed logging for development
65+
)
66+
```
67+
68+
## Fetching remote translations
69+
You have to explicitly call the `fetch` method to fetch translations from the CDN.
70+
```swift
71+
await Tolgee.shared.remoteFetch()
72+
```
73+
74+
## Basic Translation
75+
76+
```swift
77+
// Simple string translation
78+
let title = Tolgee.shared.translate("app_title")
79+
80+
// Translation with arguments
81+
let welcomeMessage = Tolgee.shared.translate("welcome_user", "John")
82+
let itemCount = Tolgee.shared.translate("items_count", 5)
83+
let nameAndAge = Tolgee.shared.translate("My name is %@ and I'm %lld years old", "John", 30)
84+
```
85+
> **NOTE:**
86+
> Strings with multiple pluralized parameters are currently **not supported**,
87+
> for example `Tolgee.shared.translate("I have %lld apples and %lld oranges", 2, 3)`
88+
89+
## Thread-safety
90+
91+
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.
92+
93+
```swift
94+
Task.deattached {
95+
// notice that the call has to be awaited outside of the main actor
96+
let str = await Tolgee.shared.translate("key")
97+
}
98+
```
99+
100+
## Next steps
101+
102+
- __SwiftUI compatibility__: Learn how Tolgee iOS SDK works with your SwiftUI code — [SwiftUI](./swiftui.mdx)
103+
- __NSLocalizedString swizzling__: Learn how to achieve zero config integration by enabling method swizzling — [Swizzling](swizzling.mdx)
104+
- __Advanced usage__: Tips and tricks for debugging and using the SDK with advanced codebases — [Advanced usage](./advanced.mdx)
105+
106+

‎ios-sdk/swiftui.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
id: swiftui
3+
title: SwiftUI
4+
description: How to use Tolgee iOS SDK with SwiftUI.
5+
---
6+
7+
## SwiftUI support
8+
9+
Tolgee works great with SwiftUI, including previewing views in different localizations using SwiftUI previews.
10+
11+
You can use the `TolgeeText` component which will automatically use the injected locale on iOS 18.4+
12+
```swift
13+
import SwiftUI
14+
import Tolgee
15+
16+
struct ContentView: View {
17+
var body: some View {
18+
TolgeeText("welcome_title")
19+
}
20+
}
21+
22+
#Preview("English") {
23+
ContentView()
24+
.environment(\.locale, Locale(identifier: "en"))
25+
}
26+
27+
#Preview("Czech") {
28+
ContentView()
29+
.environment(\.locale, Locale(identifier: "cs"))
30+
}
31+
```
32+
33+
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.
34+
35+
```swift
36+
struct ContentView: View {
37+
@Environment(\.locale) var locale
38+
39+
var body: some View {
40+
if #available(iOS 18.4, *) {
41+
Text(Tolgee.shared.translate("welcome_title", locale: locale))
42+
} else {
43+
Text(Tolgee.shared.translate("welcome_title"))
44+
}
45+
}
46+
}
47+
48+
#Preview("English") {
49+
ContentView()
50+
.environment(\.locale, Locale(identifier: "en"))
51+
}
52+
53+
#Preview("Czech") {
54+
ContentView()
55+
.environment(\.locale, Locale(identifier: "cs"))
56+
}
57+
```
58+
59+
## Reactive updates
60+
61+
Tolgee offers a convenience utility that automatically triggers a redraw of a view when the translations cache has been updated.
62+
63+
```swift
64+
struct ContentView: View {
65+
66+
// This will automatically re-render the view when
67+
// the localization cache is updated from a CDN.
68+
@StateObject private var updater = TolgeeSwiftUIUpdater()
69+
70+
var body: some View {
71+
VStack {
72+
TolgeeText("My name is %@ and I have %lld apples", "John", 3)
73+
}
74+
}
75+
}
76+
```

‎ios-sdk/swizzling.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
id: swizzling
3+
title: Swizzling NSLocalizedString
4+
description: How to achieve (almost) zero-effort integration with existing NSLocalizedString usage.
5+
---
6+
7+
## Swizzling of Apple's APIs
8+
Tolgee optionally supports swizzling of `Bundle.localizedString`, which is being used internally by `NSLocalizedString` function.
9+
10+
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.
11+
12+
Following calls will then be backed by the Tolgee SDK:
13+
```swift
14+
Bundle.main.localizedString(forKey: "welcome_message")
15+
NSLocalizedString("welcome_message", comment: "")
16+
```
17+
18+
Regular string parameters are supported as well:
19+
```swift
20+
let userName = "John"
21+
let welcomeMessage = String(format: NSLocalizedString("welcome_user", comment: ""), userName)
22+
```
23+
24+
> **NOTE:**
25+
> Plural strings are currently not supported and will fall back to using the string bundled with the app.
26+
27+
:::warning
28+
29+
Method swizzling is a powerful technique, but it can lead to unexpected behavior if not used carefully, especially if there is multiple SDKs swizzling the same APIs. Make sure to test your application thoroughly after enabling swizzling.
30+
31+
:::

‎navbar.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ module.exports.navbar = {
2323
label: 'JavaScript SDK',
2424
to: '/js-sdk',
2525
},
26+
{
27+
label: 'iOS SDK',
28+
to: '/ios-sdk',
29+
},
2630
{
2731
label: 'Android SDK',
2832
to: '/android-sdk',

‎platform/faq.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ In most cases, translators don't know the context of what they're translating. T
2424

2525
Close -> near or dismiss?
2626

27+
### Does Tolgee support iOS apps?
28+
29+
Yes. Tolgee provides a native [iOS SDK](/ios-sdk) that integrates with your app and supports SwiftUI.
30+
2731
### Does Tolgee support Android apps?
2832

2933
Yes. Tolgee provides a native [Android SDK](/android-sdk) that integrates with your app and supports Jetpack Compose.

‎platform/getting_started/about_tolgee.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ No more looking for keys in your source code, no more editing localization files
1515

1616
## Features
1717

18-
- **Developer-friendly** - Tolgee is designed to be easy to integrate with your application. There are integrations for web frameworks via the [Tolgee JS SDK](/js-sdk) and for Android apps via the [Tolgee Android SDK](/android-sdk).
18+
- **Developer-friendly** - Tolgee is designed to be easy to integrate with your application. There are integrations for web frameworks via the [Tolgee JS SDK](/js-sdk) and for native mobile apps via the [Tolgee iOS SDK](/ios-sdk) and [Tolgee Android SDK](/android-sdk).
1919
- **Easy to use** - Tolgee is easy to use for developers, but also for translators, so you can easily involve your translators into your localization process.
2020
- **Open-source** - Tolgee is open-source, you can contribute to the project on our [GitHub repository](https://github.com/tolgee/tolgee-platform). You can also [host your own instance](/platform/self_hosting/getting_started) of Tolgee, so you can have full control over your data.
2121
- **Free** - Our **cloud version** includes Business plan with 20 000 strings is **free for any open-source projects**. For commercial projects, you can use Tolgee for free up to 1000 strings. For more information, see [pricing](https://tolgee.io/pricing).

‎platform/getting_started/translation_content.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ In production mode, you should use data exported from the Tolgee platform.
3030
To export the translation files, see [exporting translations](/platform/projects_and_organizations/export).
3131
Then provide the data via Tolgee configuration options described in [Providing static data](/js-sdk/providing-static-data).
3232

33+
## iOS SDK
34+
35+
Tolgee provides a native [iOS SDK](/ios-sdk) with a great support for SwiftUI that integrates with your app and supports OTA updates of strings from a CDN.
36+
3337
## Android SDK
3438

3539
Tolgee also provides an [Android SDK](/android-sdk) for native Android apps, including Jetpack Compose support. Follow the Android docs to:

0 commit comments

Comments
 (0)