Messagevisor

SDKs

iOS SDK

Native iOS and iPadOS applications can use the Swift SDK to evaluate translations, message overrides and locale formatting on the device.

There is no separate iOS package. This guide focuses on app integration, while the Swift SDK reference covers the complete API and other Apple platforms. For React Native applications, use the React Native guide.

Installation

Add the Swift SDK through Xcode's package dependencies, or declare it in a Swift package:

.package(
    url: "https://github.com/messagevisor/messagevisor-swift.git",
    from: "0.2.0"
)

Add the Messagevisor and MessagevisorICU products to your application target. The second product provides ICU message formatting.

The SDK supports iOS 13 or newer. The example SwiftUI application targets iOS 14 or newer and uses @StateObject to own its view model.

Load a datafile

The SDK evaluates a generated datafile; networking and persistence belong to your application. You can bundle a starter datafile, fetch updated content using URLSession, and retain a last known working copy for offline use.

The example application fetches this public demonstration datafile:

https://messagevisor-example-cloudflare-pages.pages.dev/production/messagevisor-mobile-en-US.json

Use your own deployment for production content. Check the HTTP response before decoding, handle failed requests and cancel obsolete loads when the owning screen or task goes away. A failed refresh should not discard the current working content.

Create an instance and translate

After loading the response into a Foundation Data value named data, decode it and create the instance:

import Foundation
import Messagevisor
import MessagevisorICU
let datafile = try DatafileContent.fromData(data)
let m = createMessagevisor(
    MessagevisorOptions(
        datafile: datafile,
        timeZone: "America/New_York",
        modules: [createICUModule()]
    )
)
let signIn = try m.translate("auth.signin")
let closingTime = ISO8601DateFormatter().date(
    from: "2026-08-02T21:30:00Z"
)!
let contact = try m.translate(
    "nav.contact",
    values: ["closingTime": .date(closingTime)]
)

Handle decoding and evaluation errors in your loader or view model, and observe diagnostics when investigating missing content or invalid messages. If evaluation fails after creating an instance that you will not retain, close it as part of error cleanup.

The explicit New York time zone makes the example reproducible. Choose the user or product time zone deliberately for your own application.

Display translations in SwiftUI

Publish evaluated strings from a view model on the main actor. A view can display them without running another localisation lookup:

import SwiftUI
struct MessageRows: View {
    let signIn: String
    let contact: String
    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: signIn)
            Text(verbatim: contact)
        }
    }
}

The SDK does not automatically publish SwiftUI state. Reevaluate the displayed strings when the locale, context or datafile changes, then update your observable properties. For UIKit, assign evaluated strings to labels on the main thread instead.

Updates and lifecycle

  • Load the selected locale's datafile before calling try m.setLocale(locale). Loading a second locale does not automatically select it.
  • m.setDatafile(datafile) merges data for that locale. Use m.setDatafile(datafile, replace: true) when replacing a complete snapshot.
  • Use SDK events to connect runtime changes to your application's state, and remove subscriptions when their owner is disposed.
  • Apply layout direction through SwiftUI or UIKit as appropriate. Translated strings alone do not change the application's RTL layout.
  • From an asynchronous context, call try await m.close() when the instance is no longer needed. Closing clears subscriptions and module resources; handle cleanup errors as appropriate for your application.
  • Cancel pending loads and ignore obsolete responses. Do not let an earlier request replace the content of a newer locale selection.

The example owns its instance in a view model, closes the previous instance before retaining a replacement and closes it when the view disappears. An application shared instance can instead live for the application's lifetime.

Native formatting

Foundation and JavaScript can use different locale data, so punctuation, digits, day periods and other presentation details may differ. Keep native Apple output and test the locales and formatter options your application uses. See Swift SDK formatting and the capability matrix for platform boundaries.

Example application

The messagevisor-example-ios application uses MessagevisorViewModel.swift to load data, create the SDK and expose results. ContentView.swift renders loading, retry and translation states with SwiftUI.

Previous
Swift
Next
React