You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
// Basic initialization with automatic language detection
102
-
let cdnURL =URL(string: "https://cdn.tolgee.io/your-project-id")!
103
-
Tolgee.shared.initialize(cdn: cdnURL)
104
-
105
-
// Optional: Fetch translations immediately
106
-
Task {
107
-
await Tolgee.shared.remoteFetch()
108
-
}
109
-
110
-
returntrue
111
-
}
112
-
}
89
+
// Set the CDN format to Apple in your Tolgee project
90
+
let cdnURL =URL(string: "https://cdn.tolgee.io/your-project-id")!
91
+
Tolgee.shared.initialize(cdn: cdnURL)
113
92
```
114
93
94
+
Refer to our SwiftUI and UIKit examples for a complete setup.
95
+
115
96
### Advanced Initialization
116
97
117
98
```swift
@@ -124,6 +105,12 @@ Tolgee.shared.initialize(
124
105
)
125
106
```
126
107
108
+
### Fetch Remote Translations
109
+
You have to explicitly call the `fetch` method to fetch translations from the CDN.
110
+
```swift
111
+
await Tolgee.shared.remoteFetch()
112
+
```
113
+
127
114
### Basic Translation
128
115
129
116
```swift
@@ -133,25 +120,15 @@ let title = Tolgee.shared.translate("app_title")
133
120
// Translation with arguments
134
121
let welcomeMessage = Tolgee.shared.translate("welcome_user", "John")
135
122
let itemCount = Tolgee.shared.translate("items_count", 5)
136
-
137
-
// Translation from specific namespace/table
138
-
let saveButton = Tolgee.shared.translate("save", table: "buttons")
123
+
let nameAndAge = Tolgee.shared.translate("My name is %@ and I'm %lld years old", "John", 30)
139
124
```
140
125
141
-
### Plural Forms & ICU Support
142
-
143
-
```swift
144
-
// Automatic plural form selection based on count
145
-
let appleCount1 = Tolgee.shared.translate("apple_count", 1) // "You have 1 apple"
146
-
let appleCount5 = Tolgee.shared.translate("apple_count", 5) // "You have 5 apples"
147
-
148
-
// Complex pluralization for different languages
149
-
let czechPlural = Tolgee.shared.translate("items_count", 2.5) // Handles Czech plural rules
150
-
```
126
+
> [!NOTE]
127
+
> Strings with multiple pluralized parameters are currently **not supported**, for example `Tolgee.shared.translate("I have %lld apples and %lld oranges", 2, 3)`
151
128
152
-
## 🔧 SwiftUI Integration
129
+
###🔧 SwiftUI Integration
153
130
154
-
### TolgeeText Component
131
+
Tolgee is designed to work great with SwiftUI and SwiftUI previews.
155
132
156
133
```swift
157
134
importSwiftUI
@@ -165,47 +142,56 @@ struct ContentView: View {
165
142
VStack {
166
143
// Simple text translation
167
144
TolgeeText("welcome_title")
168
-
.font(.largeTitle)
169
145
170
146
// Text with arguments
171
147
TolgeeText("hello_user", userName)
172
-
.foregroundColor(.blue)
173
148
174
149
// Text with pluralization
175
150
TolgeeText("item_count", itemCount)
176
-
177
-
// Text from specific table/namespace
178
-
TolgeeText("save", tableName: "buttons")
179
151
}
180
152
}
181
153
}
182
154
```
183
155
184
156
### Reactive Updates
185
157
158
+
Tolgee provides a hook to allow the consumer of the SDK to be notified about when the translation cache has been updated.
TolgeeText("My name is %@ and I have %lld apples", "John", 3)
180
+
}
202
181
}
203
182
}
204
183
```
205
184
185
+
### Swizzling of Apple's APIs
186
+
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.
187
+
188
+
206
189
## 🌐 Advanced Features
207
190
208
-
### Namespace Management
191
+
### Custom Tables/Namespaces
192
+
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.
193
+
194
+
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.
209
195
210
196
```swift
211
197
// Initialize with multiple namespaces for better organization
@@ -216,54 +202,34 @@ Tolgee.shared.initialize(
216
202
217
203
// Use translations from specific namespaces
218
204
let commonGreeting = Tolgee.shared.translate("hello", table: "common")
219
-
let authError = Tolgee.shared.translate("invalid_credentials", table: "auth")
220
-
let profileTitle = Tolgee.shared.translate("edit_profile", table: "profile")
You may have your strings resources stored in a dedicated XCFramework or a Swift Package.
239
212
240
213
```swift
241
-
// Check initialization status
242
-
if Tolgee.shared.isInitialized {
243
-
print("Tolgee is ready to use")
244
-
}
214
+
let bundle: Bundle =...// access the bundle
245
215
246
-
// Check last fetch timestamp
247
-
iflet lastFetch = Tolgee.shared.lastFetchDate {
248
-
print("Last update: \(lastFetch)")
249
-
} else {
250
-
print("No remote fetch performed yet")
251
-
}
216
+
// Use the SDK directly
217
+
let commonGreeting = Tolgee.shared.translate("hello", bundle: bundle)
218
+
// or for SwiftUI
219
+
TolgeeText("hello", bundle: bundle)
252
220
```
253
221
254
-
### Offline-First with Fallbacks
222
+
### Log Forwarding
223
+
Tolgee allows forwarding of logs that are printed to the console by default.
224
+
You can use this feature to forward errors and other logs into your analytics.
255
225
256
226
```swift
257
-
// Tolgee automatically falls back to bundle-based localizations
258
-
// when remote translations are unavailable
259
-
260
-
// 1. First tries remote translations from CDN
261
-
// 2. Falls back to cached translations
262
-
// 3. Finally falls back to bundle-based Localizable.strings
263
-
264
-
let text = Tolgee.shared.translate("offline_message") // Always works
227
+
forawait logMessage in Tolgee.shared.onLogMessage() {
228
+
// Here you can forward logs from Tolgee SDK to your analytics SDK.
229
+
}
265
230
```
266
231
232
+
267
233
## 📱 Platform Support
268
234
269
235
| Platform | Minimum Version |
@@ -276,15 +242,24 @@ let text = Tolgee.shared.translate("offline_message") // Always works
276
242
## ⚙️ Requirements
277
243
278
244
-**Swift:** 6.0+
279
-
-**Xcode:** 15.0+
245
+
-**Xcode:** 16.3+
246
+
247
+
## 🧵 Thread-safety
248
+
249
+
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.
250
+
251
+
```swift
252
+
Task.deattached {
253
+
// notice that the call has to be awaited outside of the main actor
254
+
let str =await Tolgee.shared.translate("key")
255
+
}
256
+
```
280
257
281
258
## 🤝 Why Choose Tolgee?
282
259
283
260
**Tolgee saves a lot of time** you would spend on localization tasks otherwise. It enables you to provide **perfectly translated software**.
284
261
285
262
### All-in-one localization solution for your iOS application 🙌
286
-
### Out-of-box in-context localization 🎉
287
-
### Automated screenshot generation 📷
288
263
### Translation management platform 🎈
289
264
### Open-source 🔥
290
265
@@ -293,20 +268,19 @@ let text = Tolgee.shared.translate("offline_message") // Always works
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
0 commit comments