OTA localization architecture and implementation guide

What is OTA localization?

Over-the-air localization is the delivery of translation data to an application independently of its binary release. Instead of reading only strings packaged at build time, the app may use a newer reviewed translation snapshot downloaded from a localization service.

OTA is a content-delivery mechanism, not remote code execution. It is appropriate for text and localization metadata the app already knows how to render. New screens, behavior, assets, and layout capabilities still require the normal application release process.

Bundled localization versus OTA delivery

The OTA localization lifecycle

1. Translate and review.Stable keys, placeholders, plurals, and locale values are reviewed before becoming eligible for release.
2. Publish an immutable snapshot.Each environment receives a versioned manifest and deterministic locale artifacts rather than a mutable live document.
3. Fetch outside the lookup path.The client asks for a manifest with a read-only credential, then downloads only the artifact for the active locale.
4. Validate and cache atomically.Scope, release order, origin, byte size, and content hash are checked before the last-known-good cache is replaced.
5. Resolve locally and roll forward.Lookup stays synchronous. A rollback is published as another release, preserving history and client version ordering.

How does OTA localization work offline?

Network access should never sit inside a string lookup. A resilient client initializes local state from persistent cache, optionally refreshes in the background, and resolves from in-memory OTA content. If no OTA value is available, it uses content bundled with the app, then a caller fallback or the key.

GoLocalise's JavaScript, Swift, and Kotlin clients follow this model. Failed requests and invalid artifacts do not replace the last-known-good cache. Applications can therefore start and resolve translations during an API or CDN outage.

Failure scenarios to design and test

A practical GoLocalise manifest request

Runtime clients use a public, read-only gl_sdk_ credential. The manifest identifies the current immutable release and the locale artifact's URL, hash, and byte size. SDKs perform this exchange during initialization or refresh—not during synchronous translation lookup.

curl --fail \
  -H "Authorization: Bearer gl_sdk_REPLACE_ME" \
  "https://api.golocalise.me/ota/v1/projects/PROJECT_ID/environments/production/manifest?locale=en"

Platform-specific setup is documented in the Swift/iOS guide and Kotlin/Android guide. Web and server setup is available in the Developer Hub.

When OTA is appropriate—and when it is not

OTA is a good fit for reviewed copy corrections, terminology changes, and translations for UI capabilities already present in the installed app. It is less suitable for legal or safety-critical text that must remain tied to a particular binary unless your release controls make that relationship explicit.

Prefer bundled strings when first-launch availability is the only requirement, the product changes infrequently, or the operational cost of a content release system is not justified. Most robust mobile implementations use both: a complete bundled baseline plus validated OTA updates.

Safe rollout checklist

• Separate Development, Staging, and Production content.
• Require review before content becomes release-eligible.
• Make releases immutable and address artifacts by content hash.
• Use public credentials with read-only, project-scoped access.
• Validate scope, origin, size, and hash before replacing cache.
• Exercise first launch offline and corrupt-cache recovery.
• Keep bundled translations for critical and startup copy.
• Make rollback create a new auditable release.