1# SwiftUI Localization Reference
2 
3Guidance for user-facing text: `Text`, `Button`, `Label`, navigation/toolbar titles, alerts, and types that carry localizable strings. For the narrower "verbatim vs localized" decision on a single `Text`, see `references/text-patterns.md`.
4 
5## Table of Contents
6 
7- [SwiftUI Localizes String Literals Automatically](#swiftui-localizes-string-literals-automatically)
8- [String Catalogs](#string-catalogs)
9- [Bundle for Swift Packages and Frameworks](#bundle-for-swift-packages-and-frameworks)
10- [Localizing Variables and Custom Types](#localizing-variables-and-custom-types)
11- [LocalizedStringResource for Non-View Types](#localizedstringresource-for-non-view-types)
12- [Interpolation vs Concatenation](#interpolation-vs-concatenation)
13- [Casing](#casing)
14- [Formatting Dates, Numbers, and Currencies](#formatting-dates-numbers-and-currencies)
15- [Layout for Localization](#layout-for-localization)
16- [Reading the Current Locale](#reading-the-current-locale)
17- [String(localized:) Outside SwiftUI Views](#stringlocalized-outside-swiftui-views)
18- [Comments for Translators](#comments-for-translators)
19 
20## SwiftUI Localizes String Literals Automatically
21 
22Initializers that accept `LocalizedStringKey` (`Text`, `Button`, `Label`, `.navigationTitle`, alert titles, and so on) treat string literals as localization keys automatically. Do not wrap literals in `NSLocalizedString`, `String(localized:)`, or `LocalizedStringResource` — that resolves the string eagerly and ignores `\.locale` overrides.
23 
24```swift
25// AVOID: double work, and resolves eagerly
26Text(String(localized: "start_workout"))
27 
28// PREFER: pass the literal directly
29Text("start_workout")
30```
31 
32Both opaque keys (`"start_workout"`) and natural-language strings (`"Start Workout"`) work as keys — pick whichever convention the project already uses. Use `Text(verbatim:)` only to opt a literal out of localization (e.g. a debug label interpolating a runtime value). When the argument is already a `String` variable, `Text(value)` calls the `StringProtocol` overload and skips localization on its own.
33 
34## String Catalogs
35 
36Most projects localize through String Catalogs (`.xcstrings`). Each build syncs new keys from code into the catalog, but the catalog file must already exist — Xcode doesn't create one automatically. If a project already uses `.strings` / `.stringsdict`, add new strings there rather than migrating. Route groups of strings to a specific catalog with `tableName:`.
37 
38```swift
39Text("Explore", tableName: "Navigation",
40     comment: "Tab bar item title for the Explore screen.")
41```
42 
43## Bundle for Swift Packages and Frameworks
44 
45Apps, app extensions, and XPC services are their own main bundle, so `bundle` can be omitted. Frameworks and Swift packages need an explicit `bundle:` — without one, SwiftUI looks up strings in `Bundle.main`, the lookup fails silently, and the string appears unlocalized at runtime.
46 
47```swift
48// AVOID (inside a framework/package): searches the app's catalog
49Text("Save to Favorites")
50 
51// PREFER: #bundle resolves to the current target's bundle
52Text("Save to Favorites", bundle: #bundle,
53     comment: "Button to bookmark a recipe.")
54```
55 
56`#bundle` is the preferred form; `Bundle.module` and `Bundle(for:)` still work but are older patterns.
57 
58## Localizing Variables and Custom Types
59 
60A `String` variable passed to `Text` runs the `StringProtocol` overload and is **not** localized. Wrapping it in `LocalizedStringKey(_:)` doesn't help — Xcode can't extract a literal from a runtime value, so nothing lands in the catalog. To localize a value chosen from a known set, model it with a type that exposes `LocalizedStringResource`:
61 
62```swift
63enum Category {
64    case appetizers, mains, desserts
65    var name: LocalizedStringResource {
66        switch self {
67        case .appetizers: "Appetizers"
68        case .mains: "Mains"
69        case .desserts: "Desserts"
70        }
71    }
72}
73 
74Text(category.name)
75```
76 
77When a view or model exposes user-facing text, type the property as `LocalizedStringKey` or `LocalizedStringResource` rather than `String`. Every SwiftUI view that takes localized text accepts both, so deferring resolution costs nothing at the display site and preserves locale/bundle context.
78 
79## LocalizedStringResource for Non-View Types
80 
81When a non-view type carries user-facing text — a model object, a tip, a queued notification — use `LocalizedStringResource` instead of `String`. It defers resolution to display time, so it honors the locale active when the value actually renders, not when it was created.
82 
83```swift
84// AVOID: resolved at creation time, can't re-render in another locale
85struct Tip { let headline: String }
86let tip = Tip(headline: String(localized: "Tip of the Day"))
87 
88// PREFER: resolution deferred to display time
89struct Tip { let headline: LocalizedStringResource }
90let tip = Tip(headline: "Tip of the Day")
91```
92 
93Apply this when designing new types or changing user-facing text — don't sweep through existing `String` properties as part of unrelated edits.
94 
95## Interpolation vs Concatenation
96 
97String interpolation preserves `LocalizedStringKey` and produces a format string in the catalog (e.g. `"Welcome, %@"`). Concatenation with `+` produces a plain `String` and is not localized. Never glue separately localized fragments into a sentence — word order varies across languages.
98 
99```swift
100// AVOID: + produces String; sentence assembly breaks word order
101Text("Error: " + statusMessage)
102Text(String(localized: "Created by")) + Text(" ") + Text(authorName)
103 
104// PREFER: one interpolated string translators can rearrange
105Text("Error: \(statusMessage)")
106Text("Created by \(authorName)")
107```
108 
109## Casing
110 
111Bake the desired case into the string rather than transforming at runtime via `.textCase(_:)`, `.localizedUppercase`, or `.localizedCapitalized`. A runtime transform forces the same casing on every translation, leaving translators no room to adjust per language.
112 
113```swift
114// AVOID
115Text("Section Header").textCase(.uppercase)
116 
117// PREFER
118Text("SECTION HEADER")
119```
120 
121This applies to localized strings; display user-entered text as-is. If a transform is unavoidable, prefer `.localizedUppercase` / `.localizedCapitalized`, which honor the user's locale.
122 
123## Formatting Dates, Numbers, and Currencies
124 
125Use `Text`'s `format:` parameter or `.formatted()` instead of `DateFormatter` / `NumberFormatter` with hardcoded format strings. Format styles adapt to the user's locale; hardcoded format strings don't.
126 
127```swift
128// AVOID
129let f = DateFormatter(); f.dateFormat = "MM/dd/yyyy"
130Text(f.string(from: workout.date))
131Text("$\(product.price, specifier: "%.2f")")
132 
133// PREFER
134Text(workout.date, format: .dateTime.month().day().year())
135Text(product.price, format: .currency(code: store.currencyCode))
136```
137 
138Field components (`.month()`, `.day()`) choose which fields appear; the locale decides the order. For lists, `Array.formatted()` inserts locale-correct separators and conjunctions instead of `joined(separator:)`. When `DateFormatter` is genuinely unavoidable, use `setLocalizedDateFormatFromTemplate(_:)` rather than assigning `dateFormat`.
139 
140## Layout for Localization
141 
142- Use `.leading` / `.trailing` instead of `.left` / `.right` — they flip for right-to-left locales.
143- Don't hardcode frame widths/heights for text; translations vary in length and scripts vary in height. Use `ViewThatFits` when a layout might not fit longer translations.
144- Use text styles (`.body`, `.headline`) rather than fixed point sizes, so line height adapts per script.
145 
146```swift
147// PREFER
148Text(recipe.title)
149    .frame(maxWidth: .infinity, alignment: .leading)
150 
151ViewThatFits {
152    HStack { actionButtons }
153    VStack { actionButtons }
154}
155```
156 
157## Reading the Current Locale
158 
159Use `@Environment(\.locale)` for locale-dependent logic in views, not `Locale.current` — the environment respects preview overrides and per-view injection.
160 
161## String(localized:) Outside SwiftUI Views
162 
163When you need a localized `String` outside a view, use `String(localized:)`, not `NSLocalizedString`. Don't interpolate inside `NSLocalizedString` — Xcode extracts keys from literals at build time and can't extract interpolated values. `String(localized:)` supports interpolation (it extracts the format string and treats values as runtime arguments) and is preferred over `String(format:)`, which always renders digits as 0–9 regardless of locale.
164 
165```swift
166// PREFER
167let title = String(localized: "activity_summary", comment: "Dashboard header")
168```
169 
170## Comments for Translators
171 
172Add a `comment:` describing the UI element and its purpose, especially for ambiguous strings. For interpolated strings, describe each placeholder by position — translators don't see Swift variable names. Comments can live at the call site or in the String Catalog's per-string Comment field; keep one source of truth per string.
173 
174```swift
175// AVOID: "Edit" could be a noun or a verb
176Text("Edit")
177 
178// PREFER
179Text("Edit", comment: "Toolbar button that enters editing mode for the list.")
180Text("Completed \(count) of \(total)",
181     comment: "Progress label — first variable is finished items, second is the total.")
182```
183 
184## Summary Checklist
185 
186- [ ] String literals passed directly to `Text`/`Button`/`Label` (not wrapped in `NSLocalizedString`/`String(localized:)`)
187- [ ] `bundle: #bundle` on user-facing strings inside frameworks and Swift packages
188- [ ] User-facing text on models/non-view types typed as `LocalizedStringResource`, not `String`
189- [ ] Interpolation (not `+`) for dynamic strings; no sentence assembly from fragments
190- [ ] Case baked into the string, not applied via `.textCase`
191- [ ] Dates/numbers/currencies use `format:` / `.formatted()` with locale-aware styles
192- [ ] `.leading`/`.trailing` (not `.left`/`.right`); no hardcoded text frame sizes
193- [ ] `@Environment(\.locale)` for locale logic in views
194- [ ] `comment:` provided for ambiguous strings and interpolated placeholders
195