Localize an iOS app
Translate Apple String Catalogs or legacy resources without losing shared locales, then verify them in Xcode and the app.
An iOS app can keep the same localized lookup calls while its resource files gain another language. Lingo.dev translates those resources; Xcode and the app still determine which bundle, table, locale, and variation the user sees.
Use the format the project already loads. String Catalogs keep several languages in one .xcstrings file, while .strings and .stringsdict resources use per-locale files. This difference determines where the result is written and what needs protecting during an update.
Decide which resources are authoritative #
For a String Catalog project, identify the development language, supported target languages, and catalogs loaded by the app. Xcode 15 introduced .xcstrings, commonly named Localizable.xcstrings. Several catalogs can divide messages by feature or bundle; include each one that serves the screen you are localizing.
For legacy resources, identify the relevant .lproj directories, string tables, and plural dictionaries. Base.lproj can contain base interface resources; do not assume its presence alone tells the translator which source language or string table to use. Keep the project's development-language setting and file configuration consistent.
Connect the screen's text to localized lookup calls before translating. File translation does not replace hardcoded UI strings or register resources with an Xcode target. Keep comments that explain the speaker and screen for reviewers. The established String Catalog handler retains them but does not include them in translation-unit hints, so put required generation context in the localization engine's supported guidance.
Configure a shared String Catalog #
Install and link the current CLI from the project root:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo linkFor a catalog at that path, the resulting .lingo/config.json should have this shape:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr"],
"files": [{ "pattern": "App/Localizable.xcstrings" }]
}Keep the identifiers generated by linking instead of copying the placeholders. The extension selects xcode-xcstrings. Each target writes into the same catalog path, adding locale entries while retaining the source and other locales. A separate targetPath is not valid for this shared-file format.
The source value lives inside the shared structure:
{
"sourceLanguage": "en",
"strings": {
"Welcome": {
"comment": "Greeting on the signed-in home screen",
"localizations": {
"en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
}
}
},
"version": "1.0"
}After translation, look for the requested locale entries beside en. The handler also supports source plural and device variation leaves, and skips entries marked shouldTranslate: false. If an entry has no source localization, its key becomes the source text; a technical key is not a substitute for the intended message. Apple String Catalogs explains these selection rules and why the current source and existing catalog must stay aligned.
Keep legacy files on their own path #
For a legacy project, use these file entries instead of the shared catalog entry:
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]Include only resources the project actually has. The extensions select their handlers; Spanish output belongs in App/es.lproj/. Keep the project's development-language setting consistent with this source selection.
The string keys and formatting placeholders belong to the runtime contract. Preserve %@, positional arguments, and the types expected by the caller. A .stringsdict contains plural-variable structure that must remain coherent with its format string. Use Apple strings and strings dictionaries for the distinct contracts rather than treating either as arbitrary XML or text.
Translate and inspect the merged result #
Preserve the current catalog in version control or a separate copy before replacement. To protect local edits, submit without --wait and inspect lingo pull --dry-run before retrieval. Reconcile any divergence instead of forcing an overwrite. Waiting writeback lacks pull's fresh conflict check; see Preserve reviewed translations.
For a clean first translation, use the following command only while the catalog remains unchanged during the wait. Before adding locales to an existing project, complete ordinary source updates for existing locales, retrieve and inspect them, then keep that source revision fixed while adding and backfilling. Add a language explains the required order:
lingo push --backfill-missing --waitShared catalogs receive per-locale planning even though the file already exists. Inspect the requested locale entries rather than looking for a new filename. A plain first push can establish the source baseline without translating. After ordinary source changes, use lingo push --wait; without waiting, retrieve the recorded result with lingo pull in the submitting checkout.
For a wording correction, edit the target entry in Xcode. CLI --force can still reuse translations embedded in an unchanged catalog. To regenerate one entry after changing guidance, use the catalog correction procedure, which preserves the source and neighboring translations.
lingo purge skips String Catalogs because their source and targets share a path. To regenerate a selected translation, use the String Catalog correction workflow.
Verify through Xcode and representative screens #
Open the output in Xcode and check that the catalog or legacy file is included in the intended target and bundle. Build using the project's existing scheme. Run a target-language configuration and inspect a screen containing a simple label, a formatted value, and a plural or device variation.
Compare the target-language placeholders with the calling code. Exercise counts that select different plural forms in each language; English categories are not a complete specification for every target. Check that untouched locales remain present in the merged catalog. Review long labels, accessibility text, truncation, and right-to-left behavior where applicable.
Xcode's build checks can detect resource problems, while a language reviewer or an applicable measurement checks meaning. lingo check does not establish .xcstrings completeness or correct Apple plural behavior.
Make automation preserve the shared file #
Keep sources, accepted targets, configuration, and .lingo/lock.json together, then choose the GitHub App or a CI runner for recurring work. The runner manages its own authentication, state, and reviewable writeback. Review a String Catalog diff as a change to a shared file: identify the source revision, changed locales, and preserved locales before accepting it.
For cross-platform projects, use the separate Android and Flutter workflows for XML qualifiers and ARB generation. Each platform still needs its own resource-loading and rendered-screen checks.