Arkian logo
Start free
Menu
← All articles

Stop Skeleton Drift: Localization File Formats for Developers

Stop Skeleton Drift: Localization File Formats for Developers

Engineer reviewing multilingual file workflow

For lossless interchange, use XLIFF. For runtime strings, ship platform-native formats like JSON, .properties, .strings, PO, or YAML depending on your stack. Use TMX only when exchanging translation memory between tools, and reach for ICU MessageFormat once a language needs more than a simple singular/plural split. None of it works reliably without valid BCP 47 language tags and consistent UTF-8 encoding underneath.

TL;DR:

  • Most localization workflows rely on XLIFF for lossless content exchange and on platform-native formats like JSON or .strings for runtime loading, depending on the project ecosystem.
  • Proper use of BCP 47 language tags and UTF-8 encoding is crucial to prevent character encoding issues and ensure consistent localization results across tools and platforms.
  • Validation steps such as schema validation, MessageFormat syntax checks, and round-trip reassembly tests should be integrated into CI processes to catch integration faults early.
  • Managing multimedia assets and visual elements requires tracking by locale with consistent naming conventions to prevent outdated or mismatched assets in multilingual releases.
  • Automating format conversions and packaging with tools like Arkian reduces manual effort, improves accuracy, and supports small teams with limited localization infrastructure.
Arkian
Simplify Your Localization Workflow
Arkian automates multilingual scripts, voice outputs, validation, and structured language packages for small teams without complex TMS tools.
Explore Arkian

Table of Contents

What Are the Main Localization File Formats?

Every localization pipeline eventually touches the same handful of file types. Knowing what each one is actually built for saves you from picking a format that fights your toolchain later.

  • XLIFF: XML standard for exchanging translatable content between tools, bilingual (source and target side by side).
  • TMX: XML format for translation memory exchange, bilingual or multilingual, not meant to rebuild original files.
  • JSON: key-value or nested object format used heavily in web and mobile apps, monolingual per file (one file per locale).
  • .properties: Java’s flat key-value format, monolingual, historically limited to Latin-1 unless converted.
  • .strings: Apple’s key-value format for iOS and macOS apps, monolingual, simple but strict about escaping.
  • PO/MO: gettext’s plain-text and compiled binary pair, bilingual in the PO source, widely supported by CAT tools.
  • YAML: indentation-based key-value format popular in Rails and static site generators, monolingual, sensitive to whitespace.
  • CSV: flat spreadsheet format sometimes used for quick translator handoff, but fragile with nested structures or embedded commas.

The bilingual versus monolingual distinction matters more than it sounds. Bilingual formats like XLIFF and PO carry source and target text in one file, which is what most translation tools and TMS platforms expect for import and export. Monolingual formats like JSON or .strings only hold one language per file, so a translated app usually means one file per locale sitting side by side in a folder structure. Most professional CAT tools and TMS platforms accept XLIFF and PO natively; JSON, YAML, and .properties usually need a filter or converter before they reach a translator’s desk.

XLIFF: Role, Structure, and Integration Gotchas

XLIFF exists because someone needed a neutral, tool-agnostic way to move translatable content in and out of a CAT tool without losing formatting or context. The typical flow is extraction, translation, then reassembly: your build pulls strings out of the source app, wraps them in XLIFF, a translator or CAT tool fills in the target text, and your pipeline merges the result back into the original structure.

The XLIFF 2.1 core specification defines the building blocks: a file element wraps everything, unit groups translatable content, and segment holds the actual source and target pairs. The “skeleton” is the non-translatable scaffolding, the markup and structure that has to survive the round trip untouched. When the skeleton and the XLIFF content drift out of sync, reassembly breaks or silently corrupts formatting, a problem Microsoft’s localization documentation flags as one of the most common integration failures.

Author directly in XLIFF when you’re preserving complex inline markup; convert to it at build time when your source is already JSON or resource files. Stick with 2.1 or the newer 2.2 unless a legacy tool locks you into 1.2, and run every file through a validator before it reaches a translator.

Pro Tip: Add a round-trip reassembly test to your CI pipeline. If the merged file doesn’t match the original structure byte-for-byte outside the translated text, you’ll catch skeleton drift before it ships.

TMX and Why Translation Memory Exchange Still Matters

TMX is not a file interchange format. It is a portability format for translation memory, the accumulated database of previously translated segments that CAT tools reuse to speed up new work.

TMX earns its place in a stack when you need to:

  • Migrate a translation memory from one CAT tool or vendor to another.
  • Feed accumulated translations into a new tool without re-translating from scratch.
  • Seed a brand-new project with existing approved translations for consistency.
  • Support multiple target languages in a single file, since TMX allows more than one language pair per document.

The GALA overview of TMX 1.4b is explicit that the format exchanges translation units for reuse, not the structural markup XLIFF needs to reconstruct an app or document. If your goal is rebuilding the original source file with translated content in place, TMX is the wrong tool for that job.

Platform-Native Resource Formats: JSON, .properties, .strings, PO, YAML

These are the formats your app actually loads at runtime, and each comes from a different ecosystem with its own quirks.

  • JSON fits web and mobile apps well, especially React, Vue, and most JavaScript frameworks. It’s monolingual per file and easy to parse, but nested objects can confuse translators unfamiliar with the schema, and escaping quotes inside strings trips up hand-editing.
  • .properties is Java’s default, monolingual, and still occasionally requires the old native2ascii conversion step for non-Latin characters if you’re on a legacy toolchain.
  • .strings is Apple’s format for iOS and macOS, monolingual, straightforward, but strict about escaping percent signs and quotes inside format strings.
  • PO (gettext) is bilingual in its source form, has strong multiline and comment support for translator context, and is the format most open-source CAT tools handle natively.
  • YAML shows up in Rails and static site generators. It’s monolingual and readable, but whitespace errors and multiline block scalars are a frequent source of silent breakage.

A common pattern: author source strings in whatever your framework expects, then convert to XLIFF at build time for the actual translation handoff, which is the approach ICU’s localization guidance recommends when you want interchange benefits without abandoning your native runtime format. Arkian’s own breakdown of supported JSON, iOS, Android, TS, and YAML outputs covers the same conversion logic for teams packaging multiple platforms at once.

ICU MessageFormat, Plurals, and Runtime Message Complexity

Plain key-value strings break down fast once a language needs more than “one item” versus “many items.” Slavic languages can have three or more plural categories; Arabic has six. ICU MessageFormat handles this with plural and select constructs that route to the correct grammatical form, pulling the actual category rules from CLDR.

Don’t reach for ICU everywhere. If your product only ships in languages with simple one/other plural rules, plain string interpolation is fine and easier for translators to edit. Adopt ICU MessageFormat specifically for languages that need more than two plural categories, or for messages that vary by gender or nested conditions.

The tradeoff is translator cognitive load. MessageFormat syntax is unfamiliar to most linguists, so pair it with a linter that catches malformed syntax before it reaches runtime, and give translators a rendered preview rather than raw curly-brace syntax to edit blind.

Pro Tip: Run a MessageFormat validation pass in CI on every string file. A single unmatched brace can crash message rendering in production, and it’s far cheaper to catch in a pull request than in a crash report.

Encoding, Language Tags, and Essential Metadata

Format choice means nothing if the encoding or language tags underneath are wrong. Two things need to be locked down before any file leaves your repository:

  • Default to UTF-8 everywhere possible; watch for legacy Java .properties files that still expect Latin-1 or a native2ascii conversion step.
  • Use valid BCP 47 language tags like en-US or zh-Hant-TW, never invented or shortened codes, since browsers, CLDR, and translation tools all key off this standard.
  • Reference CLDR for plural rules and locale-specific formatting instead of hardcoding assumptions about how a language pluralizes or formats dates.
  • Store the source language, file-level locale, and contextual notes for translators directly in the file or an accompanying comment, since ambiguous strings are the top cause of mistranslation.

Decision Checklist: Pick the Right Format for Your Project

Run through this order before locking in a format for a new project:

  1. Identify your runtime platform first. iOS wants .strings, Android wants XML resources, web frameworks usually want JSON or YAML.
  2. Decide if you need lossless reassembly. If you’re preserving complex inline markup or structure, author or convert to XLIFF before translation.
  3. Check plural and variable complexity. Two or more plural categories per language means ICU MessageFormat; simple cases can stay in plain interpolated strings.
  4. Confirm your translator toolchain. If translators work in a CAT tool or TMS, they likely expect XLIFF or PO, not raw JSON.
  5. Account for CI and build constraints. Decide whether conversion happens at commit time or build time, and test that conversion round-trips cleanly.

Ask translators whether their tool imports your chosen format natively. Ask engineers whether the build pipeline can convert cleanly both directions. Ask product managers which languages are on the roadmap, since that answer decides whether ICU MessageFormat is worth the added complexity now or later.

Arkian’s Approach: Automated Validation and Packaging for Small Teams

Arkian automates the parts of this process that eat the most engineering time: validating structure, handling skeleton mapping, and packaging output for JSON, iOS, Android, TS, and YAML without requiring a translator to touch a repository.

The CI checks worth adopting regardless of tooling:

  • Schema validation on every exported file before it merges.
  • MessageFormat linting for plural and select syntax errors.
  • BCP 47 tag verification against the IANA subtag registry.
  • Round-trip reassembly smoke tests to catch skeleton drift early.

Automating these steps removes the manual back-and-forth that usually happens when a translator’s CAT tool export doesn’t match the engineering team’s expected schema, cutting friction on both sides of the handoff.

Handling Binary and Multimedia Assets in Localization Workflows

Text formats are only half the job once your product ships voice prompts, video subtitles, or image assets with embedded text. Binary and multimedia localization needs a different discipline than string files, because you can’t diff or merge audio the way you can merge JSON.

Voice and audio assets typically get organized by locale folder, with a naming convention that ties each file back to its source script line by ID, not by filename guesswork. If a script changes after recording, you need a way to flag which audio files are now stale rather than silently shipping outdated narration next to updated on-screen text. Subtitle and caption files (SRT, VTT) behave more like text formats, but timing codes make them fragile: a translated line that runs longer than the original can push captions out of sync if nobody checks duration.

Images with embedded text, app icons with taglines, onboarding graphics, marketing banners, are the easiest asset type to forget entirely. They don’t live in your string catalog, so they don’t show up in extraction reports, and teams routinely ship five language versions of an app with one leftover English screenshot. The fix is treating visual assets as a tracked localization deliverable with the same per-locale checklist as text, not an afterthought handled by whoever remembers.

Packaging voice and text outputs together, with consistent locale folder naming, is the difference between a coherent multilingual release and five loosely related file dumps. That’s a large part of what Arkian’s structured multilingual TTS production exists to organize automatically.

Automation Tools and Pipelines for Format Conversion and Processing

Manual format conversion is where localization pipelines quietly bleed hours. A team extracting strings by hand, converting them to XLIFF, sending them to a translator, then merging the result back into JSON is doing four separate jobs that should be one pipeline step.

The baseline automation most mature teams build includes a build-time extraction script that pulls translatable strings from source code into a canonical format, a conversion layer that transforms that canonical format into whatever the translator’s tool expects, and a merge step that validates the returned translation before it overwrites production resource files. Continuous integration is where this pays off: a pull request that adds new strings should automatically flag missing translations, malformed placeholders, or an unescaped character rather than waiting for a bug report after release.

Four-stage localization automation pipeline

Open-source tooling in this space includes gettext’s msgfmt and msgmerge for PO/MO conversion, and various XLIFF round-trip libraries depending on your language ecosystem. The gap most teams hit isn’t finding a converter, it’s maintaining the conversion logic as the source format evolves, since a schema change in your JSON structure can silently break a converter nobody has touched in a year.

This is the specific gap Arkian’s automated packaging targets: instead of maintaining custom conversion scripts per platform, small teams can run a single production job that outputs validated JSON, iOS, Android, TS, and YAML packages together, with the structured packaging step handling the format translation that used to require a dedicated build engineer.

Common Challenges and Troubleshooting in Working With Localization File Formats

Most localization bugs trace back to a small set of repeat offenders, and they show up in the same order on almost every project.

Encoding mismatches top the list. A file saved in Latin-1 instead of UTF-8 renders fine on a developer’s machine and then breaks on a different operating system or browser, producing garbled characters that are maddening to trace back to their source. Escaping errors come next, particularly in JSON and .strings files, where an unescaped quote or percent sign inside a translated string can crash a build or silently truncate text at runtime.

Placeholder and variable mismatches cause a different kind of failure: a translator reorders a sentence in a way that’s grammatically correct in their language but breaks the numbered placeholder order the app expects, so the wrong variable populates the wrong slot. This is exactly the failure mode ICU MessageFormat’s structured plural and select syntax is designed to prevent, but only if translators have validation tooling that catches the error before it ships.

Skeleton drift in XLIFF workflows is the quieter problem: someone edits the source app’s structure without regenerating the XLIFF skeleton, and the next reassembly either fails outright or merges translated text into the wrong slot. Round-trip integration tests in CI, checking that a merged file matches the original structure outside the translated content, catch this before it reaches production rather than after a user reports broken text.

Version control conflicts round out the list. Two translators editing the same PO or JSON file in parallel branches produce merge conflicts that are painful to resolve by hand, especially in nested JSON where a single misplaced comma cascades into a dozen conflict markers.

Common Challenges and Troubleshooting in Working With Localization File Formats — overview diagram

Practitioner’s View: Balance Simplicity and Correctness

Most teams over-engineer their localization stack before they need to. Plain key-value formats handle the majority of products fine; ICU MessageFormat and full XLIFF pipelines earn their complexity only once you support languages with real plural or gender rules, or need lossless reassembly of complex markup.

Introduce that complexity selectively, and invest in validation tooling at the same time you introduce it. Onboarding translators to MessageFormat without a preview tool is how syntax errors reach production. The correctness gains are real, but only if the tooling around them keeps translators from having to guess at raw syntax.

— Arkian

How Arkian Helps: Packaging and Validation Without the TMS Overhead

If you’ve read this far, you already know the real cost isn’t picking a format, it’s the manual conversion, validation, and reassembly work that happens after the format is chosen. Arkian automates that layer specifically for small teams: it generates translated strings, structured metadata, and even TTS voice output, then validates and packages everything into JSON, iOS, Android, TS, and YAML files ready to drop into your build, without needing repository access or a full translation management system.

Arkian

That matters most for a team of two or three people who can’t justify standing up a TMS for one app release. Arkian’s localization strings service and structured packaging pages walk through exactly what gets generated and validated before it reaches you. If you want to see it applied to a real release, the Quiet Harbour case study shows the packaging output end to end. Membership pricing and one-off production job options are available; current prices can be found on the pricing page.

Sources

FAQ

What Is an XLIFF File?

An XLIFF file is an XML document built to carry source and target text side by side, so translation tools and localization platforms can exchange content without losing structure. The OASIS XLIFF core specification defines its elements, and Arkian’s own localization strings output can convert to and from it as part of an automated packaging job.

What Are the Four Main Types of Localization File Formats?

There’s no single official “four types” classification, but a practical grouping is interchange formats like XLIFF, translation memory formats like TMX, platform-native runtime formats like JSON or .strings, and messaging formats like ICU MessageFormat for complex plurals and grammar.

What Are the Different Types of Localization?

Localization generally covers software UI strings, document and web content, multimedia assets like voice and video, and metadata such as app store listings or product descriptions. Each type tends to favor a different file format, which is why most real projects end up managing several formats at once rather than one.

What Are the Four Types of Translation?

Common categories include literal (word-for-word), literary, technical, and localization translation, though definitions vary somewhat by source. Localization translation is the category most relevant here, since it adapts not just wording but formatting, plurals, and cultural references for a target locale.

How Do I Choose Between JSON and XLIFF for My Project?

Use JSON when your app loads strings directly at runtime and you’re managing translation in-house or through simple tooling. Use XLIFF when you need lossless interchange with a CAT tool or translation vendor, or convert JSON to XLIFF at build time to get both benefits without maintaining two source formats.