appstoreconnect-translation

App Store Connect Translation & Localization Best Practices

Metadata localization is one of the most critical steps for driving international user acquisition, boosting App Store Optimization (ASO) rankings, and improving conversion rates (CVR). When configuring localized metadata in App Store Connect, you must adhere to Apple's rigid constraints and specific business logic.

---

🌐 Golden Rule: Primary Locale Parity

Every field populated in the primary locale MUST also be populated in every other configured locale.

This rule applies universally across all localization layers:

Localization Layer	Scope
App Store Version Localization	description, keywords, whatsNew (non-v1.0), supportUrl, marketingUrl
App Info Localization	name, subtitle, privacyPolicyUrl, privacyChoicesUrl
In-App Purchase / Subscription Localization	name, description
Beta Build Localization	whatsNew (TestFlight notes)

Why this matters:

• Leaving a field blank in a secondary locale causes Apple to fall back to the primary locale value, which may be in the wrong language for that market — harming user trust and store conversion.
• For mandatory fields like supportUrl, an empty value in any locale can trigger an App Review rejection.
• Incomplete localizations are a leading cause of inconsistent App Store pages across regions.

Operational Rule for MCP Tool Execution: Before completing any localization task, always verify that every field set in the primary locale has a corresponding value in all target locales. If the user has not provided locale-specific content for a given field, default to carrying over the primary locale value verbatim rather than leaving the field empty. Prompt the user only when a field genuinely requires locale-specific adaptation (e.g., translated descriptions, region-specific URLs).

---

1. Core Metadata Localization Guide

A. App Store Version Metadata (App Store Version Localization)

• App Description (Description)
  • Length Limit: Maximum 4,000 characters.
  • Formatting Principle: Keep the first 2-3 lines highly engaging and clear, as this is the "above the fold" content shown before the "More" toggle. Use lists or emojis to partition key features and value propositions.
• Search Keywords (Keywords)
  • Length Limit: Maximum 100 characters (including separators).
  • Separator Rule: Use half-width commas (,) without spaces. Spaces consume characters and cause indexing issues.
  • ASO Optimization: Consolidate functional keywords, synonyms, and category terms. Combine them to fill 90–99 characters to maximize your indexing potential.
  • ⚠️ Translation Keyword Rule: After translating keywords to a target language, always count the resulting character length. Translated keywords are almost always shorter than the primary locale due to CJK character density differences. You MUST expand the keyword list with additional synonyms, use-case terms, and long-tail phrases to reach 90–99 characters. Never submit translated keywords below 80 characters — this wastes indexing slots and directly harms ASO rankings in that market.
• First-Version Constraint (v1.0 / Prepare For Submission)
  • ⚠️ Crucial Trap: If the App Store version is the very first release (v1.0), the whatsNew (What's New in This Version) parameter MUST be set to nil (empty) during creation or update.
  • Reason: Since a first version has no previous version to compare to, Apple's API does not allow release notes. Passing text to this field will result in a 409 STATE_ERROR - Attribute 'whatsNew' cannot be edited at this time API rejection. This field is only allowed for subsequent app updates (v1.1, v2.0, etc.).
• Support URL (supportUrl)
  • Required: Mandatory for all App Store versions; omitting it will cause submission rejection. Must be a fully qualified https:// or http:// URL.
• Marketing URL (marketingUrl)
  • Optional: Fully qualified https:// or http:// URL. Leave empty if not applicable.