---
title: Getting Started
description: Native iOS i18n with the BetterI18n Swift SDK — reactive translations in SwiftUI.
---

import { Cards, Card } from 'fumadocs-ui/components/card'

BetterI18n's Swift SDK brings the same translation workflow you know from the JS SDK to native iOS apps. It supports **iOS 15+**, **macOS 12+**, and **watchOS 8+**.

The core primitive is `I18nStore` — an `@ObservableObject` that handles fetching, caching, and locale switching reactively. Wrap your root view with `I18nProvider` and every SwiftUI view in the tree gets access via `@EnvironmentObject`.

```swift
I18nProvider(core: BetterI18n(config: I18nConfig(
    projectId: "my-org/my-app",
    defaultLocale: "en"
))) {
    ContentView()
}
```

---

<Callout type="tip">
  **Integrating with AI?** Run `npx skills add better-i18n/skills` first — your agent (Cursor, Claude Code, or Windsurf) will already know the SDK patterns, CDN behavior, and key conventions. Then just ask it to set up the integration for you. [Learn more →](/mcp/agent-skill)
</Callout>

## Features

<Cards>
  <Card title="Offline-first" description="Two-phase load: cached translations appear instantly, CDN refresh happens in the background." />
  <Card title="Reactive" description="@Published locale, isLoaded, isRefreshing, and error — your UI updates automatically." />
  <Card title="Locale switching" description="setLocale() persists the preference to storage and re-fetches translations for the new locale." />
  <Card title="Widget support" description="AppGroup storage bridges translations to WidgetKit extensions without a network call." href="/frameworks/expo/widget-extension" />
</Cards>

---

## Guides

<Cards>
  <Card title="Setup" href="/frameworks/ios/setup" description="Install via SPM and configure I18nProvider in your app entry point." />
  <Card title="API Reference" href="/frameworks/ios/api-reference" description="Complete reference for I18nConfig, I18nStore, BetterI18n, and Translator." />
  <Card title="Widget Extension" href="/frameworks/expo/widget-extension" description="Bridge translations to a WidgetKit extension via App Groups." />
</Cards>


## AI Tooling

Now that you've integrated the SDK, your AI agent can check coverage, translate keys, and publish — all without leaving your editor.

<Cards>
  <Card title="MCP Server" icon="Bot" href="/mcp/getting-started">
    Translate keys, check coverage, and publish — all from your editor via Cursor, Claude Code, or Windsurf.
  </Card>
  <Card title="Agent Skill" icon="Sparkles" href="/mcp/agent-skill">
    Permanent better-i18n knowledge for your AI agent — SDK patterns, CDN behavior, key conventions. No prompts needed each session.
  </Card>
</Cards>
