/xcode-localization-workflow

name: xcode-localization-workflow
description: Plan, implement, review, and validate Apple-platform localization with Xcode String Catalogs. Use for .xcstrings setup, localizable SwiftUI and Foundation text, string tables, comments, plural and device variants, XLIFF handoff, locale UI checks, or Xcode 27 agent-assisted translation.

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 physic