Swift Internationalization
Expert-level Swift i18n patterns for macOS/iOS applications. Covers string localization, semantic key naming, and best practices.
When: to Use
Use this skill when:
- Adding localized strings to SwiftUI views
- Creating new localization keys
- Writing String(localized:) calls
- Organizing Localizable.strings files
- Reviewing i18n implementation in Swift projects
Core Principles
1. String(localized:) Pattern
// Always use String(localized:) for user-facing text
Text(String(localized: "common.save"))
Button(String(localized: "sidebar.today"))
// Never hardcode strings
Text("Save") // ❌ Wrong
2. Semantic Key Naming
Use domain.feature.key pattern:
// Good: Semantic keys
"app.name" = "TimeFlow"
"common.save" = "Save"
"sidebar.today" = "Today"
"settings.theme.title" = "Theme"
// Bad: Non-semantic keys
"saveButton" = "Save"
"viewTitle1" = "Today"
"themeTitle" = "Theme"
3. Localizable.strings Organization
Group by domain with MARK comments:
/*
Localizable.strings
TimeFlow
*/
// MARK: - App
"app.name" = "TimeFlow";
// MARK: - Common
"common.delete" = "Delete";
"common.save" = "Save";
"common.cancel" = "Cancel";
// MARK: - Sidebar
"sidebar.today" = "Today";
"sidebar.settings" = "Settings";
"sidebar.daily_note" = "Daily Note";
// MARK: - GTD Navigation
"gtd.inbox" = "Inbox";
"gtd.today" = "Today";
"gtd.projects" = "Projects";
Key Naming Conventions
| Domain | Feature | Examples |
|---|---|---|
app |
- | app.name |
common |
delete, save, cancel | common.delete, common.save |
sidebar |
today, settings, search | sidebar.today, sidebar.settings |
| `home`` today, progress, timeline | home.today, home.progress |
|
gtd |
inbox, next, projects | gtd.inbox, gtd.next |
settings |
theme, language, sync | settings.theme.title |
sync |
idle, syncing, failed | sync.idle, sync.syncing |
SwiftUI Usage Patterns
Text Component
struct TodayView: View {
var body: some View {
VStack {
Text(String(localized: "home.today"))
.font(.title)
Text(String(localized: "home.no_events"))
.foregroundStyle(.secondary)
}
}
}
Button with Localized String
Button(String(localized: "common.save")) {
// Save action
}
.disabled(isSaving)
Navigation Titles
NavigationLink(destination: SettingsView()) {
Label(String(localized: "sidebar.settings"), systemImage: .gear)
}
Best Practices
| Practice | Reason |
|---|---|
Use String(localized:) |
Prevents hardcoding, enables i18n |
| Semantic key names | Self-documenting, easier maintenance |
Group with // MARK: |
Organized, searchable strings files |
| Use domain.feature.key | Clear ownership, prevents collisions |
| Update all languages together | Prevents missing translations |
| Avoid format strings in keys | Use Swift interpolation instead |
String Interpolation
// Good: Use Swift interpolation
let message = String(localized: "sync.completed.count")
.replacingOccurrences(of: "{count}", with: "\(count)")
// Alternative: Use String(format:) for localized format strings
let formatted = String(
localized: "sync.completed.count",
comment: "Number of items synced"
)
// Localizable.strings entry:
// "sync.completed.count" = "Synced %d items";
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
| Hardcoded strings | Can't localize | Always use String(localized:) |
| Non-semantic keys | Difficult to maintain | Use domain.feature.key pattern |
| Missing translations | Shows key name | Add entries to all .strings files |
| Format strings in keys | Ambiguous values | Use Swift interpolation |
| Duplicate keys | Confusing maintenance | Search before adding |
Testing Patterns
func testLocalizationKeys() {
// Verify all keys exist in Localizable.strings
let keys = ["app.name", "common.save", "sidebar.today"]
for key in keys {
let localized = String(localized: key)
XCTAssertNotEqual(localized, key, "Key not found: \(key)")
}
}
Running Tests
# Test localization
xcodebuild test -scheme YourApp \
-destination 'platform=macOS' \
-only-testing:'YourAppTests/LocalizationTests/testKeysExist'