To round-trip a Mac app’s translations, export an Xcode Localization Catalog, preserve its plural structure and argument mappings, then import and test the returned package. This guide uses a synthetic selection label to show exactly what to hand off and check.

The task is for someone preparing translator deliverables in Xcode on a Mac: send one count-dependent message for translation and bring it back with its behavior intact. The example label is Selected 3 tiles in 2 groups. Both counts can change independently, so the deliverable must preserve more than readable wording.

Define the message contract before exporting

Treat the message contract as a small specification: which entry the app looks up, which runtime values it supplies, and which values control grammatical variation. Apple documents that String.LocalizationValue supports localizable strings with interpolation, including values supplied at runtime. Its documentation also describes using a static key and a separate default value when the identifier should differ from the displayed source text. String.LocalizationValue

For this worked example, record the following contract beside the translation request. These are illustrative requirements for the synthetic label, not an Apple file format.

Contract element Requirement for this example
Message purpose Summarize the current selection
English source Selected 3 tiles in 2 groups. with both numbers supplied at runtime
Argument 1 Tile count; controls the form of tile
Argument 2 Group count; controls the form of group
Numeric representation Retain the type and format specifier Xcode records for each argument
Translation freedom Reorder the sentence while preserving each argument’s meaning
Required behavior Each noun agrees with its own count

Also record the actual catalog, table, and key from the project. Do not invent a replacement key during translation. Apple’s preparation guide explains that localizable APIs populate catalogs during a build and that the table or tableName parameter selects the catalog. It also supports comments that explain the string’s context. Preparing your app’s text for translation

A useful synthetic comment is: Selection summary. Argument 1 is the number of selected tiles. Argument 2 is the number of groups containing those tiles. Both counts vary independently. Keep each count attached to its corresponding noun. This gives the translator enough information to distinguish two arguments even when they share a numeric type.

Prepare independent plural variations in the catalog

Start with the message in the app’s localizable source, then build the project. In the string catalog editor, Control-click the relevant key and choose Vary by Plural. Apple documents that Xcode determines the interpolation’s format specifier, adds the language’s plural forms, and initially fills the variant fields with the existing value. Those prefilled values still need editing. Localizing and varying text with a string catalog

For the English source, the intended rendered results include Selected 1 tile in 1 group., Selected 3 tiles in 1 group., and Selected 1 tile in 2 groups. A single choice based only on the tile count cannot produce every combination correctly.

Apple’s String Catalog demonstration supports varying multiple arguments through substitutions. Each substitution contains plural cases, and its inspector identifies the argument position and C-style format specifier. The runtime combines the selected substitutions into the surrounding message. Discover String Catalogs

Use that mechanism for the two independent counts. Keep the words that must agree with a count inside the corresponding variation, rather than leaving a fixed plural noun in the surrounding sentence. Give the substitutions meaningful names where the editor permits it, then inspect their mappings: the tile substitution must still use argument 1, and the group substitution must use argument 2.

Do not require every target localization to reproduce the English branch inventory. Apple documents that Xcode adds language-specific plural variations. Adding variation in the source localization also propagates variation to translations; adding it only in another localization affects that localization alone. Review the actual target branches before export. Localizing and varying text with a string catalog

Preserve argument identity when the wording moves

A placeholder’s position in the sentence and its argument number serve different purposes. A translator may need the group count to appear before the tile count without changing the order in which the app supplies those values.

Apple’s format-specifier reference documents positional notation using n$. For example, %1$lld refers to argument 1 with a long long integer conversion, while %2$lld refers to argument 2 with that conversion. %d denotes a different integer representation; it is not a shorter spelling of %lld. The reference is archived documentation, so use it for these established formatting rules alongside the current catalog workflow. String Format Specifiers

Consider the illustrative format fragment Groups: %2$lld; tiles: %1$lld. With argument 1 equal to 3 and argument 2 equal to 2, its intended output is Groups: 2; tiles: 3. This fragment demonstrates argument order only; it does not implement grammatical plural selection and should not replace the catalog’s substitutions.

Review placeholders by meaning, index, and type. Checking only that two percent signs remain would miss a swapped count. Checking only types would also miss the swap because both values are integers. Conversely, changing the application’s argument order merely to match one translation would change the contract for every other translation using that entry.

For the handoff, ask the translator to preserve the exported argument associations and formatting types while adapting the wording. A structural change to a substitution needs explicit review against the contract. A change in word order can be entirely appropriate.

Export a package the translator can return

Before exporting, enable the project’s Use Compiler to Extract Swift Strings build setting so Swift localizable strings are included. Select the project in the Project navigator, choose Product > Export Localizations, select the required localizations and destination, and export. Apple documents these steps and the resulting .xcloc package. Exporting localizations

The two catalog extensions have distinct jobs. The project’s .xcstrings file holds its String Catalog. The exported .xcloc package is the translator handoff; its Localized Contents folder contains XLIFF, and its Notes folder can carry supporting text. Send the package with the contract note rather than reducing the message to a two-column list of visible sentences. Exporting localizations

Check that the translation tool supports String Catalog variations in XLIFF. Apple explains that catalog-derived variation identifiers encode the string key and variation configuration, and documents the Localization Prefers String Catalogs setting for that export representation. These structures need to survive the return trip. Discover String Catalogs

Use this practical deliverable checklist. It is a workflow recommendation derived from the documented package structure and the example’s contract.

  • Return the translated .xcloc package with its relevant resources intact.
  • Preserve message identifiers and variation paths unless an intentional structural change is documented.
  • Supply target text for the target localization’s required plural branches.
  • Preserve argument identities, numeric types, and substitution mappings.
  • Identify any source changes received after the export so they can be reconciled before import.

If the translator’s tool cannot preserve varied entries, use Xcode to edit the exported localization or enter translations into the project’s catalog. Apple documents editing XLIFF targets and editing String Catalogs in Xcode; subsequent exports include catalog changes. A flat text exchange alone leaves the variation structure for someone to reconstruct. Editing XLIFF and string catalog files

Import the return and inspect the actual differences

Keep the original export available for comparison. When the translated package returns, select the project and choose Product > Import Localizations. Select the Xcode Localization Catalog folder. In the import interface, inspect warnings and errors through Issues View, and inspect the changes through File View before completing the import. Apple states that the comparison editor displays the imported version on the left and the current project version on the right. Importing localizations

For catalog-originated strings, Apple documents importing translations back into the appropriate String Catalog. After import, reopen the selection-summary entry and inspect both substitutions, their argument mappings, and their target branches. Discover String Catalogs

Use a focused diagnostic sequence if something looks wrong. If an entry is absent, compare its table and key with the original export. If plural variants are absent, compare the returned variation structure. If counts appear beside the wrong nouns, compare argument mappings. If only one combination reads incorrectly, inspect that branch’s text before changing the application code. This sequence follows the example’s dependencies; it is not a claim that Xcode automatically detects every contract violation.

Test unequal counts to expose swapped arguments

A successful import establishes that Xcode accepted the deliverable. The example still needs behavioral checks. Use the app’s test data or a development fixture to render the following combinations. These expected sentences illustrate the English source contract; target wording and branch selection must follow the target localization.

Tile count Group count Expected English source output What it helps reveal
1 1 Selected 1 tile in 1 group. Both singular forms
3 1 Selected 3 tiles in 1 group. Independent tile variation
1 2 Selected 1 tile in 2 groups. Independent group variation
3 2 Selected 3 tiles in 2 groups. Unequal values that expose argument swaps

Add a zero-count check if the app can display an empty selection. Also choose values that exercise every plural category required by each target localization. The four rows above cover the English singular/plural combinations, not every possible target branch.

To run the Mac app in a target localization, choose Product > Scheme > Edit Scheme, select Run, and open Options. Set App Language and, when needed, App Region, close the editor, select the Mac run destination, and run. Apple documents this scheme-based testing workflow. Testing localizations when running your app

Read the rendered message and inspect its fit in the desktop interface. If the counts remain attached to the correct nouns, each required branch behaves correctly, and the returned structure matches the intended contract, the translation round trip has preserved the behavior this label needs. Keep the contract note with the deliverable so the next wording change can be checked against the same explicit requirements.

Sources