Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 46 · Polish and Platform Features

Accessibility and Localization

Make SwiftUI apps usable by everyone and ready for every language: VoiceOver labels, Dynamic Type, contrast, reduce motion, String Catalogs, plurals and right-to-left layouts.

An app is only finished when people can actually use it. Some of them cannot see the screen and rely on VoiceOver. Some need larger text. Some are sensitive to motion, some cannot tell red from green, and many speak a language other than yours and read from right to left. Accessibility and localization sound like extra work, but SwiftUI builds a surprising amount of both into standard views. This lesson shows what you get for free and the few things you must add yourself.

You will learn how VoiceOver reads a view tree, how to label and group elements, how to support Dynamic Type and good contrast, how to respect reduced motion, and how to prepare strings, plurals and layouts for other languages with String Catalogs. The real SwiftUI code is read-only here. Two TryIt stand-ins run the underlying rules: plural categories for several languages, and the contrast ratio formula. Read text and images and buttons and controls first if labels and controls are new to you.

Design for every user

VoiceOver Screen reader for blind users.
Dynamic Type Text sizes the user chooses.
Contrast Readable colors in any light.
Localization Languages, plurals, RTL.

Standard views already do most of the work.

1 / 2

How VoiceOver sees your app

VoiceOver does not look at pixels. It reads the accessibility tree, a simplified copy of your view hierarchy where each meaningful element has a label, a value, traits and actions. A Button("Save") becomes "Save, button". A Toggle reads its title, its state and says it can be switched. Standard controls get this automatically, which is a strong reason to use them instead of tap gestures on plain views (see gestures).

Problems start with views whose meaning is only visual. An icon-only button has no text, so VoiceOver would say just "button". Add a label:

Swift
Button {
    deleteItem()
} label: {
    Image(systemName: "trash")
}
.accessibilityLabel("Delete item")

The label says what it is. The related modifiers each have a job:

  • accessibilityLabel(_:): the short name, such as "Delete item".
  • accessibilityValue(_:): the current value, such as "50 percent". Sliders and steppers do this themselves.
  • accessibilityHint(_:): what happens, only when it is not obvious ("Opens the receipt"). Keep it short; users can switch hints off.
  • accessibilityAddTraits(_:): roles such as .isHeader, .isButton, .isSelected or .isImage.
  • accessibilityHidden(_:): remove decorative elements from the tree.
  • accessibilityIdentifier(_:): not spoken; a stable name for UI tests.

A Label("Delete", systemImage: "trash") gives you the text for free, which is often the easiest solution. For images that are purely decoration, use Image(decorative: "divider") so VoiceOver skips them.

Grouping

A row that shows an avatar, a name, a date and a price would be read as four separate stops. Combine them into one sensible sentence:

Swift
HStack {
    Image(systemName: "bag")
    VStack(alignment: .leading) {
        Text(order.title)
        Text(order.date, style: .date)
    }
    Spacer()
    Text(order.total, format: .currency(code: "USD"))
}
.accessibilityElement(children: .combine)

.combine merges the children's labels into one element, .ignore drops them so you can supply your own label, and .contain keeps them separate but groups them for navigation. Custom gestures should be mirrored by accessibilityAction(named:), so a swipe-to-archive also exists as an "Archive" action in VoiceOver's actions rotor.

Dynamic Type

Users choose a text size in Settings, including seven extra "accessibility" sizes that can make body text very large. If your app uses the semantic text styles, it scales automatically:

Swift
Text("Today")
    .font(.title2)       // scales with the user's setting
Text("Fixed")
    .font(.system(size: 14))   // also scales, relative to body, but avoid mixing

Prefer .font(.body), .headline, .caption and so on over fixed sizes. For other dimensions that should grow with text, such as an icon next to a label, use @ScaledMetric:

Swift
@ScaledMetric(relativeTo: .body) private var iconSize = 24

Layouts must survive large text. A horizontal row that fits at the default size can truncate badly at the largest. Test with the biggest accessibility size and switch layouts using @Environment(\.dynamicTypeSize), or let ViewThatFits or AnyLayout choose between a horizontal and a vertical arrangement. Do not cap sizes lightly; if you must limit a cramped control, use .dynamicTypeSize(...DynamicTypeSize.xxxLarge) rather than fixing a point size, and never limit the main reading text. See how SwiftUI layout works for the tools that make this flexible.

Contrast and color

Text must stand out from its background. The WCAG guideline asks for a contrast ratio of at least 4.5 to 1 for normal text and 3 to 1 for large text (about 18 pt regular or 14 pt bold). The ratio comes from the relative luminance of the two colors, which weights green most because the eye is most sensitive to it.

Swift Check the contrast ratio of two colors

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Notice that the popular bright orange fails even for large text on white. The fix is a darker variant, not bigger text. In SwiftUI, use semantic colors (Color.primary, .secondary, system backgrounds) and asset-catalog colors with light, dark and high-contrast variants. Read @Environment(\.colorSchemeContrast) if you need to adjust yourself.

Never use color as the only signal. A red/green status dot excludes about one man in twelve. Add an icon or text, and check @Environment(\.accessibilityDifferentiateWithoutColor). Similarly, accessibilityReduceTransparency asks you to drop blurred, see-through backgrounds.

Reduce motion

Parallax, zooming and large sliding movements can cause nausea. Read the preference and swap them for gentle fades:

Swift
@Environment(\.accessibilityReduceMotion) private var reduceMotion

var body: some View {
    CardView()
        .transition(reduceMotion ? .opacity : .move(edge: .bottom))
}

The animations lesson shows the same environment value applied to withAnimation. Auto-playing video and endlessly looping effects deserve the same treatment.

Localization with String Catalogs

Localization means your app speaks the user's language and follows local conventions. SwiftUI makes the common case almost free: string literals passed to Text, Button, Label, Toggle and similar views are treated as localization keys.

Swift
Text("Welcome back")         // looked up in the catalog, falls back to the key
Text(verbatim: "ID-4821")    // never localized
let title = String(localized: "Settings")   // for non-view strings

A String Catalog (Localizable.xcstrings) is a single file Xcode manages. When you build, it scans your code for keys, lists them, tracks which languages are translated and marks stale entries. You add languages in the project settings, then fill in translations in the catalog editor or export and import a translation package. Use a descriptive comment for each key (String(localized: "Open", comment: "Button that opens a file")) because the same English word can need different translations.

Never build sentences by joining pieces. Word order differs, so use interpolation, which the catalog turns into placeholders:

Swift
Text("Hello, \(user.name)! You have \(unreadCount) unread messages.")

Dates, numbers and currencies should use formatters, which follow the user's region: Text(price, format: .currency(code: "EUR")) and date.formatted(date: .abbreviated, time: .omitted).

Plurals

"1 file" versus "2 files" looks easy until you meet other languages. English has two forms, but Russian has one, few, many and other, Arabic has six, and Japanese has just one. The CLDR standard names these plural categories, and a String Catalog lets you "Vary by Plural" so a translator fills in each form the language needs. The code stays the same:

Swift
Text("\(fileCount) files")   // catalog row varies by plural for each language

Because you cannot run the catalog here, the next TryIt implements a few CLDR plural rules and a tiny catalog lookup so you can see how a number selects a phrase.

Swift Plural categories and a catalog lookup

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Look at the Russian row: 1 and 21 take the one form, 2 and 22 take few, and 0, 5, 11 and 25 take many. A single if count == 1 would be wrong for millions of users. The final line also shows the standard fallback: a missing language shows the development language rather than a blank.

Right-to-left languages

Arabic and Hebrew read from right to left, and the whole interface mirrors. SwiftUI does most of this for you if you use leading and trailing instead of left and right: HStack reverses its children, .padding(.leading, 8) becomes the right-hand padding, and text alignment follows. Hard-code .left or fixed x offsets and your layout will look wrong.

Some images should mirror, such as a "back" chevron or a progress arrow, and SF Symbols already do. Mark your own directional image with .flipsForRightToLeftLayoutDirection(true); do not mirror logos, clocks or photos. Read @Environment(\.layoutDirection) when you need the value. In Xcode, run your app with the scheme options Right-to-Left Pseudolanguage and Double-Length Pseudolanguage to find layout bugs without knowing any translation. Numbers and embedded English words keep their own direction inside right-to-left text, which the text system handles.

Testing it

  • Turn on VoiceOver on a device and navigate your main screen with your eyes closed.
  • Use Xcode's Accessibility Inspector to see labels, traits and contrast warnings for the simulator.
  • Set the largest accessibility text size in the simulator settings and look for truncation.
  • In UI tests, newer SDKs offer performAccessibilityAudit() to flag missing labels and small touch targets; see testing iOS apps.
  • Keep touch targets at least 44 by 44 points.

Check your understanding

Quick check · 5 questions

of 5 answered You scored / 5 · perfect!

  1. 1. An icon-only trash button is read by VoiceOver as just "button". What is the best fix?

    VoiceOver needs a text description of what the control does. A label, or a Label view with text, provides it.
  2. 2. Which text color ratio meets the WCAG minimum for normal-size text?

    Normal text needs at least 4.5 to 1. Large text can pass with 3 to 1.
  3. 3. Why is if count == 1 { singular } else { plural } not enough for localization?

    Languages such as Russian and Arabic use several categories. String Catalogs let each language define the forms it needs.
  4. 4. Which modifier choice makes padding mirror correctly in right-to-left languages?

    Leading and trailing flip with the layout direction, while left and right stay fixed.
  5. 5. A parent view has an avatar, a name and a price. How do you make VoiceOver read them as one item?

    The combine option merges the children's accessibility information into one element.

Summary

  • VoiceOver reads an accessibility tree; standard controls fill it in, custom views need accessibilityLabel, traits and grouping.
  • Use semantic text styles, @ScaledMetric and flexible layouts so Dynamic Type works at every size.
  • Aim for 4.5 to 1 contrast on normal text, never rely on color alone, and honor reduce motion and reduce transparency.
  • String literals in views are localization keys; String Catalogs track translations, comments and plural variations.
  • Plural rules vary by language; always let the catalog choose the form.
  • Use leading and trailing, mirror only directional images, and test with pseudolanguages.

Next: Notifications, Widgets and App Intents.