Skip to main content

Advanced usage

Language Overwrite​

You 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.

Setting Language During Initialization​

You can set a custom language when initializing Tolgee:

// Override both locale and language
Tolgee.shared.initialize(
    cdn: cdnURL,
    locale: Locale(identifier: "pt_BR"), // Override the system locale
    language: "pt-BR" // Override the language name on Tolgee CDN
)

// Or just override the locale (language is extracted automatically)
Tolgee.shared.initialize(
    cdn: cdnURL,
    locale: Locale(identifier: "pt_BR")
)

Changing Language at Runtime​

Use setCustomLocale(_:language:) to change the language dynamically:

// Set custom locale (language is extracted automatically)
try Tolgee.shared.setCustomLocale(Locale(identifier: "fr"))

// Or specify a custom language for the CDN if it differs from the locale
try Tolgee.shared.setCustomLocale(
    Locale(identifier: "pt_BR"),
    language: "pt-BR" // CDN language code
)

// Fetch translations for the new language
await Tolgee.shared.remoteFetch()

Resetting to System Language​

To return to the device's system language:

try Tolgee.shared.setCustomLocale(.current)
await Tolgee.shared.remoteFetch()

Pre-fetching all available languages from the CDN​

You can pre-fetch all languages supported by your app:

await withTaskGroup(of: Void.self) { group in
    for language in Bundle.main.localizations {
        group.addTask {
            await Tolgee.shared.remoteFetch(language: language)
        }
    }
}

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)

Listening for 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
    }
}

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.
}