Support Store Profile root and arbitrary locales

docs/guides/en/extensions/store.md

@@ -9,9 +9,16 @@ provider commerce operations and must not contain credentials.
 persists the profile during registration or synchronization rather than calling it for every list
 or detail view.
 
-Return `relatedAppIds` and a strict `i18nMap` containing `ko`, `ja`, and `en`. Each locale contains
-media-key images with optional alt text, an intro (`helpsWith`, `recommendedFor`), and FAQs. Return
-the persisted metadata directly without a `profile` wrapper.
+Return `relatedAppIds`, optional `root` content, and an `i18nMap` keyed by any non-empty Desk locale code. Root is not a locale. Add only locales
+that contain authored content; `ko`, `ja`, and `en` are not pre-created or required. Each locale
+contains media-key images with optional alt text, an intro (`helpsWith`, `recommendedFor`), and
+FAQs. Return the persisted metadata directly without a `profile` wrapper.
+
+AppStore treats images, intro fields, and related apps as extension-first fallbacks: a non-empty
+extension value is shown read-only in the Developer GUI. FAQs are additive instead. Extension FAQs
+are shown first and remain read-only, while Developer GUI FAQs can be appended and edited.
+For each field, locale fallback is `ko → root → en` for Korean, `en → root` for English, and
+`locale → en → root` for every other locale.
 
 ## TypeScript
 
@@ -32,7 +39,7 @@ Use the `extension/store` DTOs and keep stable IDs separate from localized label
 - Registration uses an app token; profile reads do not need provider credentials.
 - Sanitize externally sourced text and URLs before returning them.
 - Increment or re-register when presentation metadata changes according to the release process.
-- Test all locales, missing optional assets, invalid URLs, schema discovery, and a real
+- Test every locale you author, arbitrary locale codes, missing optional assets, invalid URLs, schema discovery, and a real
   registration/sync readback.
 
 See the [Go Extension reference](../../../reference/go/EXTENSIONS.md).

docs/guides/ja/extensions/store.md

@@ -8,9 +8,16 @@ operation を実装する Extension ではなく、credential を含めてはい
 `extension.store.metadata.getStoreProfile` が必須です。`store:v1` を登録すると AppStore は
 registration/sync 時に profile を読み、list/detail request ごとには app Function を呼びません。
 
-`relatedAppIds` と `ko`、`ja`、`en` をすべて含む strict `i18nMap` を返します。各 locale は media
-key image と optional alt text、intro（`helpsWith`、`recommendedFor`）、FAQ を含みます。
-`profile` wrapper なしで persisted metadata を直接返します。
+`relatedAppIds`、optional `root` content、Desk の non-empty locale code を key にする `i18nMap` を返します。root は locale ではありません。実際に
+作成した locale だけを追加し、`ko`、`ja`、`en` を事前に作成したり、すべて埋めたりする必要は
+ありません。各 locale は media key image と optional alt text、intro（`helpsWith`、
+`recommendedFor`）、FAQ を含みます。`profile` wrapper なしで persisted metadata を直接返します。
+
+AppStore は image、intro field、related app を extension-first fallback として扱います。
+extension value が空でなければ Developer GUI では read-only です。FAQ は例外として加算され、
+extension FAQ を先に read-only で表示した後、Developer GUI FAQ を追加・編集できます。
+Field ごとの locale fallback は、韓国語では `ko → root → en`、英語では `en → root`、その他の
+locale では `locale → en → root` の順です。
 
 ## TypeScript
 
@@ -31,7 +38,7 @@ err := app.Use(store.Extension().GetStoreProfile(handler.GetStoreProfile))
 - Registration は app token を使い、profile read に provider credential は不要です。
 - 外部由来の文言と URL は返す前に sanitize します。
 - Release 手順に従って metadata 変更時の version または re-registration を処理します。
-- 3 locale、optional asset 不足、invalid URL、schema discovery、実際の registration/sync readback
+- 作成したすべての locale、任意の locale code、optional asset 不足、invalid URL、schema discovery、実際の registration/sync readback
   を test します。
 
 [Go Extension reference](../../../reference/go/EXTENSIONS.md) も参照してください。

docs/guides/ko/extensions/store.md

@@ -8,9 +8,16 @@ operation을 구현하는 Extension이 아니며 credential을 포함하면 안
 `extension.store.metadata.getStoreProfile`이 필수입니다. `store:v1`을 등록하면 AppStore가 등록 또는
 sync 시 profile을 읽어 저장하며, list/detail 요청마다 app Function을 호출하지 않습니다.
 
-`relatedAppIds`와 `ko`, `ja`, `en`을 모두 포함하는 strict `i18nMap`을 반환합니다. 각 locale은 media
-key image와 optional alt text, intro(`helpsWith`, `recommendedFor`), FAQ를 포함합니다. `profile`
-wrapper 없이 persisted metadata를 직접 반환합니다.
+`relatedAppIds`, optional `root` content, Desk의 non-empty locale code를 key로 사용하는 `i18nMap`을 반환합니다. root는 locale이 아닙니다. 실제로
+작성한 locale만 추가하며 `ko`, `ja`, `en`을 미리 만들거나 모두 채울 필요는 없습니다. 각 locale은
+media key image와 optional alt text, intro(`helpsWith`, `recommendedFor`), FAQ를 포함합니다.
+`profile` wrapper 없이 persisted metadata를 직접 반환합니다.
+
+AppStore는 이미지, intro 필드, 관련 앱을 extension 우선 fallback으로 처리합니다. extension 값이
+비어 있지 않으면 Developer GUI에 read-only로 표시됩니다. FAQ는 예외로 합산합니다. extension
+FAQ를 먼저 read-only로 표시하고, 그 뒤에 Developer GUI FAQ를 추가·수정할 수 있습니다.
+필드별 locale fallback은 한국어에서 `ko → root → en`, 영어에서 `en → root`, 그 외 locale에서
+`locale → en → root` 순서입니다.
 
 ## TypeScript
 
@@ -31,7 +38,7 @@ err := app.Use(store.Extension().GetStoreProfile(handler.GetStoreProfile))
 - 등록은 app token을 사용하며 profile 조회에는 provider credential이 필요하지 않습니다.
 - 외부에서 가져온 문구와 URL을 반환하기 전에 sanitize합니다.
 - Release 절차에 따라 metadata 변경 시 version 또는 re-registration을 처리합니다.
-- 세 locale, optional asset 누락, invalid URL, schema discovery, 실제 registration/sync readback을
+- 작성한 모든 locale, 임의 locale code, optional asset 누락, invalid URL, schema discovery, 실제 registration/sync readback을
   테스트합니다.
 
 [Go Extension 레퍼런스](../../../reference/go/EXTENSIONS.md)도 확인하세요.

docs/reference/typescript/extensions/store.md

@@ -2,7 +2,7 @@
 
 Use the Store Extension to provide localized App Store introduction metadata without hardcoding app-specific copy in App Store.
 
-App Store calls the metadata function during registration or re-registration, validates the result, and persists it. App Store reads the stored effective profile for list and detail queries; it does not call the app function for every customer-facing read.
+App Store calls the metadata function during registration or re-registration, validates the result, and persists it as the `extension` source. App Store combines it with any Developer GUI fallback when serving list and detail queries; it does not call the app function for every customer-facing read.
 
 ## Required Function
 
@@ -17,11 +17,8 @@ The function returns the persisted metadata directly. Do not wrap it in a `profi
 ```typescript
 type StoreProfileMetadata = {
   relatedAppIds: string[];
-  i18nMap: {
-    ko: StoreProfileLocalizedContent;
-    ja: StoreProfileLocalizedContent;
-    en: StoreProfileLocalizedContent;
-  };
+  root?: StoreProfileLocalizedContent;
+  i18nMap: Record<string, StoreProfileLocalizedContent>;
 };
 
 type StoreProfileLocalizedContent = {
@@ -35,10 +32,15 @@ type StoreProfileLocalizedContent = {
 ```
 
 - `relatedAppIds` lists apps that work with this app.
+- `root` is optional default content. It is not a locale and is never copied into `i18nMap`.
+- `i18nMap` accepts every non-empty locale code exposed by Desk. Add only locales that have authored content; `ko`, `ja`, and `en` are not pre-created or required.
 - `images[].key` is the opaque relative key returned by the App Store media upload API. Do not assume a storage prefix or pass an external URL.
 - `images[].alt` is limited to 120 characters.
 - Intro and FAQ answers support the limited Markdown syntax validated by App Store.
-- Use empty arrays or empty strings when App Store Developer GUI should provide a fallback value.
+- The SDK output always represents the `extension` source. It never contains Developer GUI values or source wrappers.
+- Use empty image/related-app arrays or whitespace-only/empty intro strings when App Store Developer GUI should provide a fallback value. App Store evaluates those fields per locale/field.
+- FAQs are additive rather than fallback-only: App Store shows extension FAQs first and appends Developer GUI FAQs. Extension FAQs remain read-only in the Developer GUI, while developers can add, edit, or remove GUI FAQs.
+- App Store resolves each field as `ko → root → en` for Korean, `en → root` for English, and `locale → en → root` for every other locale.
 
 ## TypeScript Implementation
 
@@ -70,9 +72,8 @@ export class MyStoreExtension implements StoreExtensionInterface {
 
     return {
       relatedAppIds: [],
+      root: localizedContent,
       i18nMap: {
-        ko: localizedContent,
-        ja: localizedContent,
         en: localizedContent,
       },
     };