Validate Xcode XLIFF Localization Imports on a Cloud Mac

As a release approaches code freeze, the localization vendor will typically return one or more .xcloc or .xliff files. Double-clicking them to import directly into a developer’s everyday workspace may seem efficient, but it can also write obsolete translation keys, incorrect target languages, and damaged placeholders into the project. A safer approach is to create a disposable validation directory on a cloud Mac: export a baseline from the current commit, preflight the delivered files, then import them, review the differences, and run a build.

Pin down the validation environment

The validation node should start from a clean commit. Do not reuse a workspace where localization files have already been imported, and do not test in a directory with uncommitted changes. Create a temporary branch or separate worktree for each delivery:

git fetch origin
git worktree add ../localization-review origin/main
cd ../localization-review
git switch -c review/localization-batch
xcodebuild -version
git status --short

Record the output of xcodebuild -version, the commit SHA, the target Scheme, and the delivery batch in the log. If the team uses multiple Xcode versions, set DEVELOPER_DIR explicitly so that interactive terminals and automated jobs do not invoke different toolchains.

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcode-select -p
git rev-parse HEAD

The standard for localization validation is not whether a file can be opened. It is whether the same commit, the same Xcode toolchain, and the same export parameters produce explainable results.

When running the process on a GPUMini cloud Mac, first check the currently available configurations in the console, then select a node for validation. This task generally does not require high concurrency, but if a large project must be built in full after import, available memory and disk space still need to be planned for.

Export a baseline from the current project

For an .xcodeproj, export with the project option. For a project that uses a Workspace, use -workspace instead and provide a shared Scheme. The following example exports Simplified Chinese, Japanese, and French; repeat -exportLanguage to add more languages:

mkdir -p Artifacts/Baseline
xcodebuild \
  -project ExampleApp.xcodeproj \
  -scheme ExampleApp \
  -exportLocalizations \
  -localizationPath Artifacts/Baseline \
  -exportLanguage zh-Hans \
  -exportLanguage ja \
  -exportLanguage fr

After the export, save a file manifest before touching the delivered translations:

find Artifacts/Baseline -type f -print0 \
  | sort -z \
  | xargs -0 shasum -a 256 > Artifacts/baseline.sha256

The baseline answers three questions: which units in the current project are translatable, what their source-language content is, and which target languages Xcode recognizes. If a delivered file contains keys that do not exist in the baseline, the translation was often prepared from an older commit. If the baseline contains many newly added untranslated units, the delivery scope may be missing recent features.

Check XLIFF structure and placeholders before import

XLIFF is XML. Start by validating its structure with system tools, then extract the language attributes and translation-unit counts. Do not rewrite XML with regular expressions. Preflight checks may read the files, but fixes should be made in the localization tool or with a reviewed script.

find Incoming -name "*.xliff" -print0 |
while IFS= read -r -d '' file; do
  echo "Checking $file"
  xmllint --noout "$file"
  xmllint --xpath \
    'string(/*[local-name()="xliff"]/*[local-name()="file"][1]/@target-language)' \
    "$file"
  echo
done

Placeholder problems are the most important reason to block an import. %@, %d, positional parameters, and variables generated by String Catalogs must remain semantically consistent between the source and translation. Simply counting percent signs is insufficient because %%, field widths, and positional parameters have different meanings. Use an XML parser to read the source and target of each trans-unit, normalize their placeholders, and compare the resulting multisets.

For user-visible format strings, also spot-check line breaks, escape sequences, and plural branches. Placeholder order may change to suit the language, but positional indices must remain valid when positional parameters are used.

Import in an isolated directory and review the differences

After the preflight checks pass, import each .xcloc package separately. Record the repository state immediately after every import so that any anomaly can be traced to the delivery that introduced it:

mkdir -p Artifacts/Logs
for package in Incoming/*.xcloc; do
  name="$(basename "$package" .xcloc)"
  xcodebuild \
    -project ExampleApp.xcodeproj \
    -importLocalizations \
    -localizationPath "$package" \
    2>&1 | tee "Artifacts/Logs/import-${name}.log"
  test "${PIPESTATUS[0]}" -eq 0 || exit 1
  git status --short
done

A successful import does not mean validation is complete. First use git diff --stat to assess the scope of the changes, then review the diff file by file. Expected changes should be limited to String Catalogs, string resources, or the corresponding language directories. If Schemes, build settings, signing configuration, or unrelated project files have changed, stop and identify the source.

git diff --stat
git diff --check
git diff -- '*.xcstrings' '*.strings' '*.stringsdict' 'project.pbxproj'

git diff --check can detect some trailing whitespace and conflict markers, but it cannot evaluate translation semantics. Generate a summary of added, removed, and modified translation units and retain it as a pipeline artifact alongside the import logs.

Complete the validation loop with a build and re-export

Finally, run a clean build of the target Scheme. If the project contains multiple application targets or extensions, cover the actual release path rather than building only the smallest library target.

set -o pipefail
xcodebuild \
  -project ExampleApp.xcodeproj \
  -scheme ExampleApp \
  -configuration Release \
  -destination 'generic/platform=iOS Simulator' \
  clean build |
  tee Artifacts/Logs/localization-build.log

After the build succeeds, export XLIFF from the imported project again and compare it with the baseline. Re-exporting can reveal translations that were not actually written into the project, incorrect language-code mappings, or translation units that remain untranslated after import. Ignore ordering-only changes and tool-generated metadata during comparison; focus on each unit’s source text, target text, status, and notes.

A maintainable validation pipeline should retain four categories of evidence: toolchain and commit information, preflight reports, import-diff summaries, and build logs. After a failure, do not clean the working directory automatically; preserve it for investigation. After a successful run, remove the temporary worktree so the next delivery cannot inherit stale state.

The final gate can be summarized as follows: the XML is parseable, the target language is correct, placeholder sets match, there are zero unknown translation units, the diff is within the expected scope, and the target Scheme builds successfully. This turns the cloud Mac into a reproducible localization-validation node rather than another import environment that depends on manual memory to maintain.

Frequently asked questions