xcode-localization-workflow

Xcode Localization Workflow

Purpose

Make an Apple app understandable and usable in its supported languages, regions, and interface directions. This workflow owns the durable localization path: String Catalog setup, source-code extraction, translator context, translation handoff, and locale-aware UI evidence. It treats Xcode 27 agent translation as an optional beta-era acceleration, never as the reason to adopt localization or as proof that a translation is ready to ship.

Use Xcode String Catalogs (.xcstrings) as the default catalog format for current Xcode projects. They centralize extracted strings, translations, plural variants, and device-specific variants. They do not make arbitrary runtime strings, poor source context, date/number formatting, or clipped layouts localizable by themselves.

When To Use

• Use this workflow when adding, repairing, migrating to, or reviewing a String Catalog.
• Use it for localizable SwiftUI, UIKit, AppKit, Foundation, attributed text, bundle/table, plural, device-variation, XLIFF, or translation-context work.
• Use it when an Xcode-hosted or external agent is asked to add languages or translate a catalog.
• Hand project inspection, source membership, build, and Xcode-managed project mutation to xcode-build-run-workflow.
• Hand locale-aware test design and execution to xcode-testing-workflow; hand visual destination selection and physical-device evidence to xcode-device-hub-workflow.
• Hand accessibility semantics, Dynamic Type, VoiceOver, and bidirectional-layout concerns to apple-ui-accessibility-workflow.
• Hand agent setup, permissions, and live Xcode 27 MCP capability discovery to xcode-coding-intelligence-workflow.

Single-Path Workflow

1. Establish the localization contract before editing. Record the development language, supported language-and-region pairs, audience, tone, terminology, names that must remain unchanged, and which content is intentionally not user-facing. Put durable translator-facing guidance in TRANSLATION.md when the project needs more than a few code comments.
2. Inspect the app for user-visible text and its owning bundle. Do not localize identifiers, logging, protocol values, stable machine-readable data, accessibility identifiers, or text that a product requirement explicitly preserves. Do localize visible labels, actions, errors, empty states, onboarding, notifications, and format strings.
3. Add Localizable.xcstrings through Xcode's String Catalog file template when the target has no catalog. Keep one default catalog until a catalog has a real ownership boundary, such as Navigation or a separately shipped feature. Use a named table or tableName only when the corresponding catalog exists.
4. Make source text discoverable and contextual:
   • SwiftUI view literals such as Text("Continue") are localizable by default; use the API's comment parameter when the visual role or meaning is ambiguous.
   • Use String(localized:table:bundle:locale:comment:) for a resolved Foundation string, including UIKit and AppKit controls. Use AttributedString(localized:...) when localized Markdown or attributed content is required.
   • Use LocalizedStringResource when a localized resource must cross an API or process boundary before resolution. Specify the owning bundle for code in a framework or Swift package rather than silently reading the app's main bundle.
   • Prefer static literals or explicit static keys with a development-language default. Do not expect Xcode extraction to resolve a dynamically constructed key, table, or comment.
   • Never concatenate translated fragments, inject grammatical punctuation outside the localized sentence, or use English singular/plural branching in code. Put values into one localizable interpolated string so translators can reorder or inflect them.
5. Build every relevant target. Xcode discovers localizable API calls and updates the catalog on build; inspect each new or changed entry in the catalog's source view. Treat a clean build as extraction evidence, not as translation or visual-fit evidence.
6. Add the requested language and region variants in the catalog or project localization settings. Provide translator comments that explain role, audience, variable meaning, constraints, and whether a term is a product name. Enable Xcode's automatic comment generation only as a supplement to deliberately written context.
7. Model language-specific variation in the catalog:
   • For count-dependent text, start with interpolation, build, then choose Vary by Plural. Review the forms Xcode creates for every target language; do not assume English's one/other rules apply elsewhere.
   • Add device variants only when the wording genuinely differs by device, not to hide a layout problem.
   • Prefer localized FormatStyle APIs for dates, numbers, measurements, lists, and names. Do not translate preformatted English data or bake locale-specific formatting into a catalog string.
8. Translate and review. Enter known translations in Xcode or export an .xcloc package for a localization service, then import and review the resulting diff. Mark uncertain strings as needing review. A person fluent in the target language and region must review terminology, grammar, tone, placeholders, and cultural suitability before release.
9. Validate the product, not merely catalog completeness. Build the affected targets; run locale-specific tests where available; inspect representative long-text, Dynamic Type, right-to-left, plural, device-variant, error, onboarding, and system-dialog states. Use simulator evidence for normal visual behavior and a physical device where hardware or production-only behavior matters.
10. Use Xcode 27 agent translation only after the stable path above is in place. Confirm the installed Xcode version, the agent surface, permission boundary, and live String Catalog tool inventory through xcode-coding-intelligence-workflow. Preserve glossary and project guidance, review the generated catalog/XLIFF changes, and retain Xcode's machine-translation provenance. Do not present agent output as human-reviewed translation.