Arkian logo
Start free
Menu
← All articles

XLIFF Localization Workflow: 4 Stages, Xcode Fixes for Developers

XLIFF Localization Workflow: 4 Stages, Xcode Fixes for Developers

Developer checking an XLIFF file in Xcode

The standard XLIFF localization workflow runs in four stages: extract source text into XLIFF with a skeleton, prepare the file with IDs, notes, and placeholder documentation, translate and review against defined states, then validate and reassemble into target files. Expect three artifacts along the way: the source XLIFF paired with its skeleton, the translated XLIFF, and the final validated output files ready for build or release, often checked by a validator or CI hook.

TL;DR:

  • Use descriptive resource keys, document each placeholder’s type and order in translator notes, and add screen context before handing files to translators.
  • Assign review authority explicitly: translators can mark segments translated, but only an authorized reviewer should mark them final after linguistic and technical checks.
  • Run schema, placeholder, and tag checks in CI, then build and visually test localized output for right to left layout, font support, and truncation.
  • Preserve unknown elements and custom attributes through round trips; XLIFF 1.2 lacks native plural support, while XLIFF 2.x modules depend on tool support.
Arkian
Streamline Localization for Small Teams
Arkian automates multilingual scripts, voice outputs, validation, and packaging, helping developers manage localization without a complex translation management system.
Explore Arkian

Table of Contents

Step-by-step XLIFF localization workflow for engineers

The pipeline below follows the sequence that Capstan’s guidance on XLIFF preparation describes as the standard localization process: extract, translate and review, validate, reassemble.

  1. Extract source strings into XLIFF. Your build tool pulls translatable text out of code or resource files and generates an XLIFF document plus a skeleton, a template that preserves the structure of the original file so translated content can be poured back in later.
  2. Prepare the XLIFF for translators. Add unique, descriptive IDs, translator notes, and placeholder documentation before the file leaves your hands.
  3. Translate and review. Translators or reviewers work through the file in an editor or TMS, updating segment states as they go.
  4. Validate the structure. Run schema and placeholder checks against the translated file before anything touches production.
  5. Reassemble and test. Reapply the skeleton to produce target-language files, then run a smoke test on the resulting build.

Extraction looks different depending on platform. On iOS, xcodebuild -exportLocalizations produces an .xcloc bundle containing XLIFF and a skeleton. Android projects typically extract from strings.xml resource sets, while web projects often pull from JSON or key-value resource files before converting to XLIFF. Each path produces the same core artifact: an XML file carrying translatable units next to a structural reference for reassembly, a format Microsoft’s localization file format guidance describes as designed specifically for interoperability between localization tools.

Preparation is where most quality problems get solved or created. Before handoff, check that you have:

  • Unique, human-readable IDs for every translation unit, not auto-generated hashes.
  • Translator notes documenting placeholder order, type, and any runtime values.
  • Non-translatable strings (product names, codes) explicitly flagged.
  • Plural and ICU MessageFormat patterns verified against the target locale’s rules.

During translation and review, use the states your XLIFF version defines rather than inventing your own labeling scheme outside the file. A translator marks a unit “translated,” a reviewer bumps it to “needs-review” or back to “new” if it fails a check, and only a reviewer with sign-off authority should mark a unit “final.” Keep this handoff explicit, especially when translators and developers work in different tools.

Validation and reassembly close the loop: run an XML schema check, confirm every placeholder in the source has a matching placeholder in the target, reapply the skeleton, and build the result.

XLIFF files passing validation before reassembly

Pro Tip: Script the validate-and-reassemble steps into your CI pipeline so a broken placeholder or malformed tag fails the build instead of shipping to a device.

Preparing XLIFF files and source content without creating rework

Preparation mistakes surface weeks later, usually as a crash report or a support ticket about garbled text. The fix starts before extraction even happens.

Store translatable strings in dedicated resource files with descriptive keys, never raw source-string keys that break the moment the English copy changes. Avoid concatenating strings at runtime: a sentence built from three separate translated fragments rarely reads correctly in languages with different word order. Microsoft’s software localization guidance names insufficient context as a leading cause of weak translations, and the fix is straightforward: document placeholder types and order directly in <note> elements, and add UI context (screen name, button label, surrounding copy) wherever your tooling supports it.

  • Use resource files with descriptive keys instead of source text as the key.
  • Document every placeholder’s type and expected runtime value in a note.
  • Add screen or element context so translators aren’t guessing where text appears.
  • Handle plurals with platform-native plural resources where they exist, falling back to ICU MessageFormat patterns inside XLIFF when they don’t.

Adding descriptive keys and translator notes materially improves translation quality, according to Microsoft’s localization documentation, which identifies missing context as the most common root cause of poor translator output. Our guidance on ICU MessageFormat checks covers plural and placeholder validation in more depth if your project leans on runtime-formatted strings. For teams managing resource bundles across multiple platforms, keeping a canonical set of keys also prevents the kind of locale drift covered in our resource bundle localization piece.

Translating and validating XLIFF before you ship

Validation is the stage most small teams skip under deadline pressure, and it’s also the stage where a missed placeholder or an unclosed tag turns into a crash in production.

  1. Run schema validation first. Check the translated file against the XML schema for its XLIFF version, and fail the CI build automatically on any invalid document rather than catching it after reassembly.
  2. Check translation states and placeholders. Automated checks should flag missing targets, placeholders that don’t match between source and target, and tag mismatches introduced during translation.
  3. Test language-specific rendering. Right-to-left layout, font and encoding support, and visual truncation all need a pass once text is in context, since a string that fits in English can overflow in German or wrap unpredictably in Arabic.
  4. Define who signs off. Decide in advance whether a translator, a reviewer, or a project lead has authority to mark a segment “final,” and keep that rule consistent across the project.

Capstan’s CI approach recommends validating schema, running placeholder and token matching, then producing a staging build from the reassembled files, catching broken localizations before they reach a release branch rather than after. A two-pass QA pattern, common in production localization work and described in Posthive’s subtitle translation workflow piece, applies just as well to XLIFF: one pass checks linguistic accuracy, a second checks technical correctness like placeholders and length.

Pro Tip: Keep an automated placeholder-matching script in your repo so a translator accidentally dropping a %s or reordering a numbered placeholder gets caught in minutes, not in a support queue.

XLIFF versions and the elements you can’t afford to strip

The building blocks are consistent across versions, even when the surrounding structure changes. A real file maps roughly as <file> (carrying the original path or href) containing <unit> elements, each holding one or more <seg> segments, each segment pairing a <source> with a <target>.

A few attributes matter more than the rest:

  • id and original: the keys that let your tooling match a translated unit back to its source location.
  • state and trgLang: the status of a segment and its target language, both critical for review handoff.
  • dir: text direction, easy to overlook until a right-to-left string renders wrong.
  • Custom or tool-specific properties: anything your pipeline added that isn’t part of the core spec.

The OASIS XLIFF 2.2 specification instructs processing agents to preserve unknown elements and attributes rather than strip them, a rule that matters in practice because so many toolchains silently drop anything they don’t recognize. XLIFF 1.2 has no native plural support, while XLIFF 2.x introduces modules for plurals and other structured content, though adoption across tools varies. Favor toolchains that honor the preservation rule, and test a full round trip, export, edit, re-import, before trusting a new tool with production content.

Tooling and common troubleshooting for XLIFF workflows

Most XLIFF headaches are tooling quirks rather than format problems, and most have known fixes.

  • “Argument list too long” on Xcode export. This usually comes from deep project paths or exporting too many files at once. Moving your project closer to the filesystem root or trimming the exported path list resolves it in most cases, a workaround confirmed in this Stack Overflow thread on Xcode localization export errors.
  • “Item already exists” on InfoPlist.strings. This happens when multiple targets export a file with the same name. Rename conflicting files to include the target identifier, or remove duplicates before import.
  • Reliable CLI tools. xcodebuild -exportLocalizations and -importLocalizations handle iOS round trips, while dedicated XLIFF converters or custom parsers cover Android and web projects; run schema validation in CI regardless of which tool produced the file.
  • Keep skeletons under version control. Store skeleton files alongside source code and test the full import and reassembly cycle as part of your CI pipeline, catching regressions before a release rather than after.

Our guidance on localizing iOS .strings files and Android XML resource handling covers platform-specific conversion notes if you’re setting this up for the first time.

Pro Tip: Canonicalize every exported filename with its target identifier before import, a one-line renaming script saves hours of collision debugging across multi-target projects.

How Arkian automates and packages XLIFF workflows for small teams

We built our platform to take over parts of this workflow that commonly cost small teams the most time: validation and reassembly. Once a source file comes in, we run automated checks and produce structured, delivery-ready language folders.

  • We automate the creation of multilingual scripts, voice outputs, and structured language packages, reducing manual reassembly and validation work.
  • We integrate validation and packaging into one pass, producing organized output folders instead of a pile of loose files to sort.

A typical run looks like extraction on your end, an XLIFF upload to us, automated validation and packaging, then a download of reviewable target files. Our Quiet Harbour case study documents one version of that handoff for a multilingual app release.

A pragmatic view on what to automate and what to keep manual

Automate the steps that are repetitive and error-prone: schema validation, placeholder matching, and packaging. Keep human review for linguistic quality, since no validator catches an awkward translation. Spend the real effort early, on key naming and placeholder conventions, because that’s where rework compounds. For multi-platform projects, pick one source format and one conversion pipeline rather than maintaining parallel manual processes per platform.

— Arkian

Arkian: a practical automation option for small teams

Once your extraction and preparation conventions are solid, the remaining bottleneck is usually validation and packaging, exactly where manual scripts tend to break down as a project grows. We handle that stage end to end, turning a translated XLIFF file into structured, delivery-ready output.

Arkian

If you’re ready to see a managed run on your own files, start with our language file packaging page.

FAQ

What is the difference between XLIFF and JSON for localization?

XLIFF is an XML-based interchange format built specifically to carry translatable content and metadata between localization tools, while JSON is a general-purpose data format many developers use for simple key-value string resources. Microsoft’s localization file format documentation notes that XLIFF’s design goal is interoperability across tools and original file formats, something plain JSON doesn’t attempt. Teams managing multiple platforms often keep one canonical format and convert to the other as needed during the build.

What does the skeleton do in an XLIFF workflow?

A skeleton is the structural template generated alongside an XLIFF export that preserves the original file’s layout, formatting, and non-translatable content. During reassembly, translated segments get poured back into the skeleton to reconstruct a valid target-language file in its original format.

Which XLIFF elements should never be stripped during processing?

Keep id, original, state, trgLang, and dir attributes intact, along with any custom or tool-specific properties your pipeline relies on. The OASIS XLIFF 2.2 specification directs processing agents to preserve unknown elements and attributes rather than discard them during round-trip editing.

How do I fix Xcode’s “argument list too long” error during localization export?

This error typically stems from deep project paths or exporting too many files in one pass. Moving the project closer to the filesystem root or reducing the number of exported paths resolves it in most cases, a fix confirmed in a widely referenced Stack Overflow thread.

Can small teams run an XLIFF workflow without a full TMS?

Yes, small teams can prepare, validate, and reassemble XLIFF files using CI scripts, open-source validators, and CLI tools without repository access or a traditional translation management system. Our platform packages that same validate-and-reassemble stage into a managed run for teams that want to skip the scripting; see our localization strings service for details.

Sources