Skip to main content

Localize Lists Like Alice, Bob, and Carol Without Hard-Coded Conjunctions

2026-11-18

Localize Lists Like Alice, Bob, and Carol Without Hard-Coded Conjunctions

Your permission sheet says "Camera, Photos, and Location". Your book screen shows "Anita, Jean, and Peter". Your destructive action offers "Save, Share, or Delete". In US English those strings look finished. Ship the same joined(separator: ", ") or array.join(", ") helper to French, Japanese, or Arabic and readers still see English commas and an English "and". Switch the device to British English and the Oxford comma may disagree with what your designer expected. List formatting is CLDR data: separators, conjunctions, and word order change by locale. This guide shows how to replace hand-built joiners with platform list formatters on iOS, Android, and the web, and how to bind them to the language your app actually selected.

It assumes you already avoid string concatenation for full sentences, as covered in our guide to stopping concatenating strings in app localization, and that you format dates and numbers with locale-aware APIs, as covered in localizing app dates, times, and numbers. List patterns sit between those two topics: the items are already localized strings, and the only remaining job is joining them with the right separators and conjunction for the reader's language.

The short answer

  1. Keep each list item as its own localized string. Format the list only at the edge of the UI.
  2. Call the platform list formatter (ListFormatter, ICU ListFormatter, or Intl.ListFormat) instead of hard-coding ", ", " and ", or ", and ".
  3. Pass the locale your app resolved for the current session, not the device default.
  4. Pick the semantic type on purpose: and for inclusive lists, or for exclusive choices, unit for measurement sequences.
  5. Use the formatter for standalone lists. Put fixed grammar around a list inside a translator-owned message when the list sits inside a full sentence.
  6. Prefer formatToParts / formatToValue when chips or links need per-item styling, and test empty, one, two, and many-item cases under a non-English app language.

Why hard-coded list joiners fail

The usual helper joins with a comma and patches " and " before the last item. That encodes three English decisions at once: the separator, the conjunction, and whether an Oxford comma appears before the conjunction. None of those decisions travels with a translation catalog.

The same failure shows up in support threads. A Stack Overflow thread titled Localization of lists (score 9, about 1,550 views) asks whether the conjunction is localized and what format string works for an arbitrary-length list such as "Bat, Cat and Dog". Another asks how to turn API data ["Anita", "Jean", "Peter"] into a natural sentence fragment for US English versus Swedish: Localizing a naturally-formatted list of API data. On the web, developers ask whether the Intl API can place "and" before the last name in ['john','harry','darren']; the accepted path is Intl.ListFormat. RTL apps hit a related failure when a dynamic comma-separated list is dropped into an ICU MessageFormat string without locale list patterns: RTL languages: comma-separated lists.

Libraries still ship English joiners as defaults. Dart helpers such as joinDisplayList document caller-controlled joiner, doubleJoiner, and lastJoiner parameters that default to ', ', ' and ', and ', and '. That is the English Oxford pattern with knobs, not CLDR list data. The fix on Apple platforms is usually a one-line change. The Worm iOS project replaced book.authors.joined(separator: ", ") and a pending Localize marker with ListFormatter.localizedString(byJoining:), and updated tests that had asserted the English "Author1, Author2" shape.

Use the platform list formatter

Every major platform ships a locale-aware list formatter backed by Unicode CLDR list patterns. Choose the type and width, then pass the locale your product already resolved.

iOS and macOS

ListFormatter is "an object that provides locale-correct formatting of a list of items using the appropriate separator and conjunction." The convenience API is enough for string arrays:

let appLocale = Locale(identifier: selectedLanguageTag) // the app's resolved language
let authors = ["Anita", "Jean", "Peter"]

let formatter = ListFormatter()
formatter.locale = appLocale
let byline = formatter.string(from: authors)
// or:
let byline2 = ListFormatter.localizedString(byJoining: authors)

On newer SDKs, prefer the FormatStyle path so you can set type and width next to member formatting:

let byline = authors.formatted(
    .list(type: .and, width: .standard)
    .locale(appLocale)
)

let choices = ["Save", "Share", "Delete"].formatted(
    .list(type: .or, width: .standard)
    .locale(appLocale)
)

Apple's list(memberStyle:type:width:) documentation shows the same idea for numbers formatted as currency inside a list. The swift-foundation ListFormatStyle source describes caching of unique configurations, so reuse a style rather than rebuild it on every render.

Set the list formatter's locale from the app's selected language, because ListFormatter.localizedString(byJoining:) and Android ListFormatter.getInstance() follow the device or default FORMAT locale unless you pass the app language explicitly. Per-app language settings make this bug easy to miss in QA: the device stays English while the app UI is French, and the byline quietly keeps English "and".

Android

Use android.icu.text.ListFormatter. Create an instance for the app locale and the semantic type:

val appLocale = Locale.forLanguageTag(selectedLanguageTag)
val formatter = ListFormatter.getInstance(
    appLocale,
    ListFormatter.Type.AND,
    ListFormatter.Width.WIDE
)
val byline = formatter.format(listOf("Anita", "Jean", "Peter"))

ListFormatter.Type documents three meanings: AND for "Alice, Bob, Charlie, and Delta", OR for exclusive alternatives, and UNITS for sequences such as "5 pounds, 12 ounces". Width controls how abbreviated the separators and conjunction become. When you need offsets for styling, call formatToValue and read the FormattedList field positions instead of splitting the finished string.

Web and JavaScript

Intl.ListFormat is Baseline-ready in modern browsers. The constructor takes type (conjunction, disjunction, unit) and style (long, short, narrow):

const appLocale = selectedLanguageTag; // BCP 47 tag from your in-app language setting
const authors = ["Anita", "Jean", "Peter"];

const byline = new Intl.ListFormat(appLocale, {
  type: "conjunction",
  style: "long",
}).format(authors);

const choices = new Intl.ListFormat(appLocale, {
  type: "disjunction",
  style: "long",
}).format(["Save", "Share", "Delete"]);

Locale identity matters even within English: MDN's en-GB example formats a three-item conjunction without an Oxford comma, while en-US output includes it. That difference is locale data, not a designer toggle. Can I use reports broad engine support; still feature-detect or gate on your minimum runtime before calling the constructor in older WebViews.

For chips, links, or bold names, use formatToParts. Each part is an element or a literal. Style the elements; leave the literals alone so you do not reintroduce English commas by hand.

Pick type and width from meaning

Choose list type from meaning rather than English wording: use or for exclusive choices and unit for measurement sequences such as 5 pounds, 12 ounces, because a conjunction pattern inserts "and" where the UI needs "or" or no conjunction. A permissions summary is usually and. A radio-style destructive confirmation is or. A height shown as feet and inches is unit, which is the same CLDR family Android exposes as Type.UNITS and the web exposes as type: "unit".

Width is a separate choice. Long styles keep full conjunction words. Short and narrow styles shorten separators for compact chrome such as toolbar subtitles. Do not invent a third style by trimming the long output with replace(" and ", " & "); that reintroduces English assumptions and breaks locales whose conjunction is not the substring " and ".

Keep list output standalone

Keep list formatter output for standalone item lists only; do not drop it into a surrounding translated sentence, because Apple documents that sentences, phrases with punctuation, and appositions may not work well when joined. The localizedString(byJoining:) discussion states the tip directly: use the method for strings ready to display in a bullet-point list; sentences, phrases with punctuation, and appositions may not work well when joined together. Apple's overview for ListFormatter adds that the formatter is not aware of the surrounding context and does not customize capitalization, so a formatted result may not be grammatically correct inside a sentence.

When the UI needs "There are three pets: a dog, a fish, and a cat.", give translators a message with a placeholder for the whole list, or a pluralized message that does not require joining fragments with English grammar. Format the pet names with the list formatter, then substitute the finished list into a translator-owned template only when your localization process has validated that pattern for every shipped locale. If agreement, case, or word order around the list changes by language, prefer one message per shape instead of composing prose in code.

Failure modes to plan for

Empty lists, single items, and pairs need explicit product rules. Formatters generally return an empty string for no items and the item itself for a one-element list. Decide whether the UI should hide the row, show a localized "None", or keep a placeholder before you call the formatter.

Do not parse a formatted list back into items. Once you split on "," you have assumed English separators. Keep the source array as data and format only for display, the same discipline duration and number formatting require.

Mixed content needs care. If list items are user-generated names, you still need the locale-correct joiner, but you may also need truncation, bidirectional isolation, or grapheme-safe limits covered elsewhere in this series. If items are themselves formatted numbers or durations, format each member first with its own locale-aware API, then pass the display strings into the list formatter, or use a member style on Apple platforms so both layers share one locale.

Avoid asserting exact formatter strings in unit tests. Assert that a French app language does not contain the English substring " and " for a three-item conjunction, or compare against golden values generated on a known ICU version for a small locale matrix. Pinning "Anita, Jean, and Peter" as a universal expected string will fail as soon as QA runs under fr-FR or en-GB.

How to verify before release

  1. Under an in-app language that is not English, open every screen that shows a joined name list, permission list, or exclusive choice list.
  2. Confirm separators and conjunctions match the app language, not the device language, when those differ.
  3. Check and versus or versus unit surfaces separately; a wrong type reads as a meaning error, not only a translation error.
  4. Exercise zero, one, two, and five or more items.
  5. Spot-check en-US versus en-GB if you ship both, to confirm Oxford-comma behavior comes from the locale tag.
  6. For styled lists, confirm formatToParts / formatToValue still emit locale literals you did not hard-code.
  7. Run one RTL locale and confirm punctuation and order still read correctly without mirrored English commas pasted from code.

What to do next

Inventory call sites that use joined(separator:), string.Join, array.join, or hand-written " and " patches. Replace each with a platform list formatter bound to the app's selected locale and the correct semantic type. Add a regression test that fails when a non-English app language still renders an English conjunction. If you already ban string concatenation for sentences, treat hard-coded list joiners as the same class of bug: English grammar living in code instead of in locale data.