Fix iOS Base Internationalization in Xcode: Steps for Developers

Base internationalization keeps one set of Interface Builder files, stored in Base.lproj, and moves translatable text into per-language assets so you never duplicate storyboards for each language. Use it whenever your project relies on storyboards or xib files and you want a single layout to maintain while translators work on separate string resources. The payoff is fewer duplicated interface files and a cleaner handoff, since Xcode generates the per-language strings or fills String Catalogs for you.

TL;DR:

• Base internationalization minimizes duplicated files by keeping one shared layout file and separate translation overlays in individual language folders.
• Switching the project’s development language without updating the Base content can cause mismatched source text and outdated strings, leading to localization errors.
• String Catalogs introduced in WWDC 2023 streamline string management and automatically sync new strings, helping reduce manual export steps.
• Pseudolocalization with tools like Double Length or RTL testing helps identify layout issues caused by longer translated strings or right-to-left language requirements.
• Automated services like Arkian can simplify delivering validated, ready-to-import translation bundles without replacing existing Xcode export workflows.

Table of Contents

• What base internationalization does and how it maps to Xcode project folders
• Enable base internationalization and add languages (step-by-step in Xcode)
• How Interface Builder strings become localized: .storyboard/.xib to strings and String Catalogs
• Testing localization: pseudolocalization, right-to-left checks, and layout verification
• Practical best practices and common pitfalls when using base internationalization
• How centralized localization production fits into an iOS base-internationalization workflow
• When base internationalization is the right choice versus alternatives
• Getting your localized iOS strings production-ready with Arkian
• Sources
• FAQ

What base internationalization does and how it maps to Xcode project folders

Base internationalization splits your project into two kinds of folders. Base.lproj holds the actual storyboard or xib file, meaning the layout, constraints, and control types. Each [lang].lproj folder (fr.lproj, ja.lproj, and so on) holds only the translated content that overlays that layout at runtime, typically a generated .strings file keyed by object identifiers.

According to Apple’s documentation on internationalizing the interface, base internationalization has been enabled by default since Xcode 5, and it exists specifically so localizers never need to open or modify the storyboard itself. When Xcode adds a new localization to a storyboard, it produces a generated .strings file containing each translatable string, keyed by its element identifier, with a comment showing the object type for context.

At runtime, the system picks the best match between the user’s preferred languages and the localizations your app ships, then loads that language’s .strings file over the shared Base layout. If no match exists, it falls back to your declared development language.

A few points worth being precise about:

• Base is a folder name, not a language code, so it never appears in a locale identifier or App Store language list.
• The development language you declare in project settings should match the actual text written into the Base storyboard, since Xcode treats Base content as that language’s source text.
• Changing the development language later does not rewrite Base.lproj automatically, so mismatches between the declared language and the real UI text are a common source of confusion.

Enable base internationalization and add languages (step-by-step in Xcode)

Most modern projects have this on already, but new targets, older projects, and packages migrated between Xcode versions are worth checking directly.

1. Open your project settings, select the project (not the target), and go to the Info tab.
2. Under Localizations, confirm Use Base Internationalization is checked. If it is not, enable it and Xcode will prompt you to choose which storyboard and xib files to include.
3. Confirm your development language in the same panel: this is the reference language Xcode treats as authoritative when generating strings for every other localization.
4. Click the plus button under Localizations to add a new language. Xcode will list your storyboards and xibs and ask which files to localize for that language.
5. Xcode creates the new [lang].lproj folder and generates a .strings file per selected storyboard, containing every user-facing string with its object identifier and a type comment.
6. Hand that .strings file (or the equivalent String Catalog entries, covered next) to your translator, who edits only the right-hand values, never the keys.

Removing or changing the development language is where projects get into trouble. If you switch it, Xcode does not retroactively translate Base.lproj content, so you have to update the Base storyboard text yourself and regenerate the generated .strings for every other language, or translators end up working from stale source text. Watch for encoding issues, too: legacy .strings files are UTF-16 by convention, and hand-edited or improperly saved files can throw parsing errors at build time that look unrelated to localization at first glance.

Pro Tip: Before adding a new language, build and run once with only the base language enabled so you know the storyboard compiles clean. It is much easier to isolate a UTF-16 or key mismatch error when you have not just added five languages at once.

How Interface Builder strings become localized: .storyboard/.xib to strings and String Catalogs

There are two supported pipelines from your Base storyboard to a translator-ready file, and which one you use depends on your Xcode version and how much of the project has migrated.

The legacy path is the generated .strings file described above: one file per storyboard per language, keyed by object identifier, regenerated whenever you run Xcode’s “Export Localizations” command. The modern path, introduced with String Catalogs at WWDC 2023, centralizes every localizable string, whether it comes from Swift code, SwiftUI views, Interface Builder objects, or Info.plist entries, into a single .xcstrings file per language group. Xcode discovers new strings automatically as you build and keeps the catalog in sync, so you no longer wait for an explicit export step to see new keys appear.

A few things to know when working across both formats:

• String Catalogs compile down to .strings and .stringsdict at build time, so the runtime behavior for your app does not change, only the authoring format does.
• Xcode’s Migration Assistant can convert existing .strings files into a catalog, and Apple’s own guidance is to migrate gradually rather than all at once, since catalogs and legacy files can coexist in the same target during the transition.
• Entries a String Catalog can no longer find a source for are marked Stale, which gives you a built-in signal for cleanup rather than a silent orphaned key.
• For translator handoff, you still export a localization package, either an XLIFF file or an .xcloc bundle, via Product > Export Localizations, and re-import the translated version through Product > Import Localizations once it comes back.

That export/import boundary is also where centralized production tools plug in, since a service can generate the .strings or .xcstrings content and hand back a package shaped for that exact import step, which the later sections cover in more detail.

Testing localization: pseudolocalization, right-to-left checks, and layout verification

Auto Layout is not optional if you are supporting more than one language. Constraints that pin exact widths or that assume a fixed character count will clip or truncate translated text the moment a string runs longer than your source language, and German, Finnish, and several other languages routinely produce longer strings than English.

The standard way to catch this before a translator ever touches your project is pseudolocalization. Xcode’s scheme editor lets you run your app with a pseudolanguage active, and the Zendesk engineering team’s walkthrough on testing layout for localization recommends the Double Length pseudolanguage specifically, which pads every string to roughly double its length so you can see immediately which labels, buttons, and cells break.

Practical steps for building this into your workflow:

• Edit your scheme, go to Run > Options, and set the app language to Double-Length Pseudolanguage or pass the NSDoubleLocalizedStrings launch argument directly.
• Use Interface Builder’s preview language picker to spot-check individual storyboard scenes without a full build.
• Switch the scheme to a right-to-left pseudolanguage to confirm mirrored layouts behave correctly, since Apple’s testing guidance treats RTL simulation as a standard part of internationalized app testing alongside locale-specific date and number formatting checks.
• Set AppleLanguages and AppleLocale as scheme launch arguments when you need to test a specific shipped language rather than a pseudolanguage.

Automated translation still needs a human pass. Apple’s WWDC 2026 session on building multilingual-ready apps notes that agent-assisted translation in Xcode can speed up first-draft translation, but native-speaker review through TestFlight remains the recommended step before anything ships. Treat machine or agent output as a starting point, not a final string.

Practical best practices and common pitfalls when using base internationalization

Most base internationalization problems trace back to a handful of recurring habits.

• Keep the Base storyboard text and your declared development language genuinely in sync. If you change the project’s development language, update the Base content to match rather than assuming Xcode will do it for you, since Apple’s documentation is explicit that Base.lproj files do not update automatically when you switch languages.
• Avoid building strings through concatenation. Use format specifiers with named arguments instead, handle plural forms with a .stringsdict entry (or the equivalent pluralization rules in a String Catalog), and lean on Automatic Grammar Agreement for languages with gender-dependent phrasing, since word order and inflection vary too much across languages for concatenated fragments to translate cleanly.
• Watch for stale entries. String Catalogs flag strings whose source has disappeared with a Stale marker, which is your cue to either restore the source or delete the key, rather than leaving translators to guess at unused text.
• Keep storyboard object identifiers stable across UI edits. Renaming or recreating objects changes the keys in your generated .strings file, which can silently orphan existing translations; if you need to regenerate strings after a UI change, Apple’s ibtool command line utility can extract fresh keys directly from the storyboard.

Pro Tip: Run a full localization export right after any significant storyboard rework, even if you are not sending files to translators that week. Catching orphaned keys early is far cheaper than untangling them months later across five language files.

How centralized localization production fits into an iOS base-internationalization workflow

Once your export step produces an XLIFF, .xcloc, or String Catalog file, the actual translation and packaging work is where small teams tend to lose time, especially without dedicated localization staff or access to a full translation management system.

A specialized service can automate turning source strings into structured, validated .strings or .xcstrings output, then package the result into files shaped for direct import back into Xcode. A few specific ways this shows up in a base internationalization workflow:

• Teams without repository access can still get translator-reviewed .xcloc or XLIFF files back through Arkian’s iOS strings localization service, without granting source control permissions to an outside translator.
• Projects that route content through an intermediate format before it reaches Xcode can use structured JSON output as a pipeline step.
• The generated folder structure is organized to map cleanly onto Xcode’s own .lproj layout, so importing a completed language package is closer to a drop-in than a manual rebuild.

This fits best when you already have a working Base storyboard and export pipeline and need validated, delivery-ready language bundles rather than another translation management platform to configure.

When base internationalization is the right choice versus alternatives

Base internationalization plus String Catalogs is the right call for any Interface Builder-heavy app that wants one layout to maintain across every shipped language. If you are starting a new project in SwiftUI, the localized string and markdown-interpolation APIs built into SwiftUI cover most of the same ground without a storyboard in the picture at all. Libraries and packages are a separate case: they generally need their own bundled localization rather than depending on a host app’s Base.lproj.

The trade-offs worth naming honestly: migrating a large legacy project to String Catalogs takes real time, build-time discovery of strings can surprise you if you are used to the explicit export step, and translator ergonomics differ enough between XLIFF, .xcloc, and raw .strings that it is worth deciding early which format your translation process expects.

— Arkian

Getting your localized iOS strings production-ready with Arkian

If you have the export step working but keep stalling at getting accurate, delivery-ready translations back into Xcode, that is the specific gap Arkian is built to close. Rather than setting up a full translation management system for a two- or three-person team, you send source strings through Arkian and get back structured .strings output, packaged for import, alongside optional multilingual voice and metadata production if your app needs narrated content or store listing translations too.

For iOS projects specifically, the Localize iOS .strings Files page walks through the exact input and output format Arkian produces, and the pricing page lists the Arkian Membership plan at a monthly subscription alongside other credit packs for production jobs. Check availability for your language pairs and see whether the output maps to your import step before committing a full localization pass to it.

Sources

• Internationalizing the User Interface — Apple Developer Documentation
• Testing your layout for localization — Zendesk Engineering

FAQ

What is the difference between Base and a language folder?

Base.lproj holds your storyboard or xib’s actual layout and controls, while each language-specific .lproj folder holds only the translated strings that overlay that shared layout. Base is a folder name for the reference UI, never a language code itself.

Do I need Auto Layout to use base internationalization?

Yes in practice, since translated strings are rarely the same length as your source text and fixed-size elements will clip or overlap without flexible constraints. Apple’s testing documentation and independent engineering guides both treat Auto Layout as a prerequisite for resilient localized interfaces.

Should I use String Catalogs or the older generated .strings files?

String Catalogs, introduced at WWDC 2023, are Apple’s current recommended approach because Xcode discovers and syncs strings automatically at build time rather than requiring a manual export. Existing projects can migrate gradually with Xcode’s Migration Assistant, and legacy .strings files can coexist with catalogs during the transition.

How do I test my app in a language I have not translated yet?

Use a pseudolanguage, such as Double-Length Pseudolanguage or the NSDoubleLocalizedStrings launch argument, set through your scheme’s Run options, to see how longer text affects your layout before real translations exist. This approach is specifically recommended in Apple’s testing documentation and in engineering write-ups on localization layout testing.

Can Arkian replace my Xcode localization export step?

No, Arkian works alongside your existing export step rather than replacing it, taking the strings you export and returning structured, packaged translations shaped for Xcode’s import tools. It is meant for teams that need validated language bundles without setting up a full translation management system.

Recommended

• Localization Strings — JSON, iOS, Android, TS, YAML