To validate a translation’s placeholders on your Mac, compare each argument’s position, type, and intended use with the source message. Use Xcode’s mismatch diagnostics, then inspect plural substitutions and test the rendered label with distinct sample values.

This guide is for someone reviewing a Mac app’s localized labels in Xcode. The task is to check one message and its translations against the values supplied by the app. All labels below are synthetic English examples; they illustrate formatting mechanics rather than actual translations.

What belongs in a message’s argument contract?

An argument contract is a review record describing the values a message receives: their positions, formatting types, meanings, and expected uses. It is a practical checklist derived from the source code and catalog, rather than a separate Apple file format.

Swift’s String.LocalizationValue supports localizable strings with interpolated runtime values. Its documentation also distinguishes using the source text as the localization key from supplying a separate key and default value. Consequently, an identifier alone may not reveal the message’s arguments: inspect the default source text and its call site. String.LocalizationValue

Consider the format string Added %lld items to %@. For this illustration, the app supplies an integer count followed by an object-backed collection label. Write down the contract before editing the translation:

Argument position Meaning Expected format Illustrative value
1 Number of added items %lld 7
2 Destination collection label %@ Canvas

Apple’s format reference defines %@ as an object conversion, %d as a signed 32-bit integer, %f as a double conversion, and ll as the integer length modifier for long long. It also documents positional forms such as %1$@. Preserve the complete type information; changing %lld to %d changes the expected integer type. The reference is archived, so use it for format syntax alongside current catalog documentation. String Format Specifiers

Add the arguments’ meanings to the review record even when their types are identical. For Moved %@ to %@, a type check cannot distinguish the item label from the destination label. Correct syntax still needs the correct relationship between values and words.

How do you find the authoritative source in Xcode?

Start with the project open in Xcode and identify the catalog containing the message. If the source has changed, choose Product > Build to refresh extracted strings. Select the catalog in the Project navigator, choose Editor > Assistant, and select the message key to view its source. Apple documents this workflow for locating and updating catalog entries. Localizing and varying text with a string catalog

Check which values the call site actually supplies, in which order, and through which localization API. Apple recommends localizable APIs such as String(localized:); an initializer with a separate defaultValue uses its first parameter as the key and its second as the default source string. This matters when a neutral identifier such as collection.added.summary owns the message. Preparing your app’s text for translation

Record three things together: the catalog and key, the default source wording, and the ordered argument meanings and types. If these disagree, resolve the disagreement before adjusting translations. Otherwise, you could make a translation match an outdated source instead of the app’s current inputs.

Provide context for future edits as well. Apple supports comments on localizable strings to explain their use. A useful synthetic comment would say that argument 1 is the item count and argument 2 is the destination collection label. That gives a localizer information a format specifier cannot express. Preparing your app’s text for translation

How do you check counts, types, and argument positions?

Apple introduced String Catalog validation for common problems, including mismatched format specifiers, with fixes available for some issues. Inspect any diagnostic Xcode presents for the entry. Treat an offered correction as a proposed syntax repair and verify that it preserves the message’s meaning. Build multilingual-ready apps

For a simple message without plural substitutions, use this review sequence:

  1. Identify every argument-consuming placeholder in the source and candidate text.
  2. Assign each placeholder to its argument position.
  3. Compare its complete format type with the contract.
  4. Check that every required value appears where the wording expects it.
  5. Investigate added, omitted, or repeated references individually.

Positional notation lets a translation change word order while retaining argument identity. In %2$@: added %1$lld items, the first visible placeholder references argument 2 and the second references argument 1. Apple documents the n$ positional syntax. String Format Specifiers

The following decision table applies to the illustrative two-argument contract above. These are proposed review outcomes, not results from running Xcode:

Candidate format text Review outcome Reason
Added %lld items to %@ Matches the simple contract Count first, destination second
%2$@: added %1$lld items Matches after reordering Explicit positions retain both argument identities
Added %d items to %@ Correct the integer type Argument 1 no longer uses the expected length modifier
Added %lld items Investigate the omission The destination required by this message is absent
Added %1$lld items to %1$@ Correct the references Argument 1 is referenced with conflicting types; argument 2 is absent
Added %1$lld items to %2$@ (%2$@) Review the repetition There are three occurrences but only two distinct referenced arguments

Keep occurrence count separate from distinct argument count. The final row intentionally demonstrates the difference: repeating argument 2 does not create a third supplied value. Whether that repetition belongs in the wording is an editorial decision. For this task, flag it until its purpose is established.

Likewise, do not count every percent character as an argument. Apple defines %% as a literal percent sign. A format label such as Scale: %lld%% contains one value placeholder and one escaped percent sign. String Format Specifiers

Why do plural substitutions need a different check?

Plural messages require reviewing the selection mechanism as well as the text that displays a value. In its String Catalog session, Apple explains that substitutions can contain dictionaries of plural cases. The inspector shows the controlling argument’s position and C-style format specifier. A substitution can therefore depend on an argument even when a particular branch does not print that argument numerically. Discover String Catalogs

For a synthetic item-count message, compare One item added with %lld items added. The first branch spells out the quantity; the second prints it. A rule demanding an identical visible placeholder count in every branch would reject the first unnecessarily. Apple’s documented strings dictionary behavior explicitly allows the numeric format specifier to be omitted from plural forms and gives spelling out the number as an option. Stringsdict file format

Use this branch-aware review instead:

  • Verify the substitution’s controlling argument position and type in the inspector.
  • Inspect every plural branch present for the target localization.
  • Check each displayed placeholder against the argument it references.
  • Explain any omitted numeric display through the branch wording.
  • Check other message arguments separately; spelling out a count does not explain a missing collection label.

For two independently varying counts, preserve their separate roles. A synthetic message about items and collections needs the item count to control the item substitution and the collection count to control the collection substitution. Apple documents multiple substitutions within one message and explains that runtime output combines their selected plural cases. Discover String Catalogs

How do you confirm the corrected message on your Mac?

After repairing the entry, build the app and inspect any remaining catalog diagnostics. Then run the relevant screen in the target localization. Apple’s supported workflow is to choose Product > Scheme > Edit Scheme, select Run, open Options, choose App Language and the appropriate App Region, click Close, and run the selected destination. Testing localizations when running your app

Choose sample values that make swaps visible. For two count arguments, use different numbers, such as 2 and 7. For two text arguments, use distinct labels such as Tile and Canvas. These are illustrative test inputs: their purpose is to reveal which supplied value appears in each part of the message.

For pluralized messages, exercise values that reach the branches under review. When two substitutions vary independently, include combinations that change one count while holding the other fixed. Inspect both the selected wording and the placement of each displayed value. A successful rendering of one combination leaves the other branches unexamined.

Keep translation state separate from your contract check. Apple describes the catalog’s green checkmark as the translated state after text has been entered. Record the actual checks you performed—argument mapping, type comparison, branch inspection, and rendered examples—rather than treating that state indicator as evidence of all four. Localizing and varying text with a string catalog

The message is ready to move forward when its placeholders resolve to the intended supplied arguments, their types match, and any branch-specific omission or repetition has a clear explanation. Keeping that compact contract beside the message makes the next source or translation edit easier to assess.

Sources