@sayren/store-sdk 0.34.0 → 0.36.0

package/src/client.ts

@@ -63,9 +63,12 @@ import { myAccountSchema, myStoreSchema } from "./schemas/auth";
 import {
   type CategoryCreateRequest,
   type CategoryDeleteStrategy,
+  type CategoryLocalizationRequest,
   type CategoryPatchRequest,
   categoryAttributeSchema,
   categoryCreateRequestSchema,
+  categoryLocalizationRequestSchema,
+  categoryLocalizationSchema,
   categoryPatchRequestSchema,
   categorySchema,
   categorySearchResultSchema,
@@ -84,11 +87,14 @@ import {
 import {
   type CollectionCreateRequestInput,
   type CollectionListParams,
+  type CollectionLocalizationRequest,
   type CollectionPatchRequest,
   type CollectionPreviewRequest,
   type CollectionProductsAddRequest,
   type CollectionProductsReplaceRequest,
   collectionCreateRequestSchema,
+  collectionLocalizationRequestSchema,
+  collectionLocalizationSchema,
   collectionPageSchema,
   collectionPatchRequestSchema,
   collectionPreviewRequestSchema,
@@ -308,18 +314,29 @@ import {
   variantStockSchema,
 } from "./schemas/product";
 import {
+  type InfoSectionLocalizationRequest,
   type InfoSectionRequestInput,
   infoSchemaSchema,
+  infoSectionLocalizationRequestSchema,
+  infoSectionLocalizationSchema,
   infoSectionRequestSchema,
   infoSectionSchema,
   platformCodeSchema,
 } from "./schemas/product-info";
+import {
+  type ProductLocalizationRequest,
+  productLocalizationRequestSchema,
+  productLocalizationSchema,
+} from "./schemas/product-localization";
 import {
   type SavedOptionSetFromProductRequestInput,
   type SavedOptionSetListParams,
+  type SavedOptionSetLocalizationRequest,
   type SavedOptionSetRequestInput,
   savedOptionSetFromProductRequestSchema,
   savedOptionSetFromProductResultSchema,
+  savedOptionSetLocalizationRequestSchema,
+  savedOptionSetLocalizationSchema,
   savedOptionSetRequestSchema,
   savedOptionSetSchema,
 } from "./schemas/saved-option-set";
@@ -592,6 +609,24 @@ export function createStoreClient(options: StoreClientOptions) {
           body: productPatchRequestSchema.parse(body),
         }),
       remove: (productId: string) => storeHttp.requestVoid("DELETE", path`/products/${productId}`),
+      /** 번역(이슈 #134) — 언어별 상품명·상세설명·이미지·옵션 이름 */
+      localizations: {
+        list: (productId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/products/${productId}/localizations`,
+            z.array(productLocalizationSchema),
+          ),
+        put: (productId: string, locale: string, body: ProductLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/products/${productId}/localizations/${locale}`,
+            productLocalizationSchema,
+            { body: productLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (productId: string, locale: string) =>
+          storeHttp.requestVoid("DELETE", path`/products/${productId}/localizations/${locale}`),
+      },
       bulkUpdateStatus: (productIds: string[], status: ProductStatus, idempotencyKey?: string) =>
         storeHttp.request("POST", "/products/bulk/status", bulkResultSchema, {
           body: { productIds, status: productStatusSchema.parse(status) },
@@ -675,6 +710,27 @@ export function createStoreClient(options: StoreClientOptions) {
           savedOptionSetFromProductResultSchema,
           { body: savedOptionSetFromProductRequestSchema.parse(body) },
         ),
+      /** 번역(이슈 #134) — 기본 언어 이름이 키다. 불러올 때 상품 번역으로 복사한다 */
+      localizations: {
+        list: (optionSetId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/saved-option-sets/${optionSetId}/localizations`,
+            z.array(savedOptionSetLocalizationSchema),
+          ),
+        put: (optionSetId: string, locale: string, body: SavedOptionSetLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/saved-option-sets/${optionSetId}/localizations/${locale}`,
+            savedOptionSetLocalizationSchema,
+            { body: savedOptionSetLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (optionSetId: string, locale: string) =>
+          storeHttp.requestVoid(
+            "DELETE",
+            path`/saved-option-sets/${optionSetId}/localizations/${locale}`,
+          ),
+      },
     },
 
     /**
@@ -711,6 +767,27 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       remove: (infoSectionId: string) =>
         storeHttp.requestVoid("DELETE", path`/info-sections/${infoSectionId}`),
+      /** 번역(이슈 #134) — 언어별 제목·본문 */
+      localizations: {
+        list: (infoSectionId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/info-sections/${infoSectionId}/localizations`,
+            z.array(infoSectionLocalizationSchema),
+          ),
+        put: (infoSectionId: string, locale: string, body: InfoSectionLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/info-sections/${infoSectionId}/localizations/${locale}`,
+            infoSectionLocalizationSchema,
+            { body: infoSectionLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (infoSectionId: string, locale: string) =>
+          storeHttp.requestVoid(
+            "DELETE",
+            path`/info-sections/${infoSectionId}/localizations/${locale}`,
+          ),
+      },
     },
 
     /**
@@ -760,6 +837,27 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("POST", "/collections/preview", collectionPreviewSchema, {
           body: collectionPreviewRequestSchema.parse(body),
         }),
+      /** 번역(이슈 #134) — 언어별 제목·설명·SEO */
+      localizations: {
+        list: (collectionId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/collections/${collectionId}/localizations`,
+            z.array(collectionLocalizationSchema),
+          ),
+        put: (collectionId: string, locale: string, body: CollectionLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/collections/${collectionId}/localizations/${locale}`,
+            collectionLocalizationSchema,
+            { body: collectionLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (collectionId: string, locale: string) =>
+          storeHttp.requestVoid(
+            "DELETE",
+            path`/collections/${collectionId}/localizations/${locale}`,
+          ),
+      },
     },
 
     categories: {
@@ -796,6 +894,24 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("DELETE", path`/categories/${categoryId}`, {
           query: (opts?.strategy ? { strategy: opts.strategy } : {}) as Query,
         }),
+      /** 번역(이슈 #134) — 언어별 이름·SEO */
+      localizations: {
+        list: (categoryId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/categories/${categoryId}/localizations`,
+            z.array(categoryLocalizationSchema),
+          ),
+        put: (categoryId: string, locale: string, body: CategoryLocalizationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/categories/${categoryId}/localizations/${locale}`,
+            categoryLocalizationSchema,
+            { body: categoryLocalizationRequestSchema.parse(body) },
+          ),
+        remove: (categoryId: string, locale: string) =>
+          storeHttp.requestVoid("DELETE", path`/categories/${categoryId}/localizations/${locale}`),
+      },
     },
 
     orders: {

package/src/index.ts

@@ -36,6 +36,7 @@ export * from "./schemas/customer";
 export * from "./schemas/customer-delegation";
 export * from "./schemas/fulfillment";
 export * from "./schemas/inventory";
+export * from "./schemas/locale";
 export * from "./schemas/login";
 export * from "./schemas/market";
 export * from "./schemas/misc";
@@ -44,6 +45,7 @@ export * from "./schemas/payment";
 export * from "./schemas/points";
 export * from "./schemas/product";
 export * from "./schemas/product-info";
+export * from "./schemas/product-localization";
 export * from "./schemas/promotion";
 export * from "./schemas/refund-policy";
 export * from "./schemas/saved-option-set";

package/src/schemas/category.ts

@@ -146,3 +146,28 @@ export const categoryDeleteQuerySchema = z.object({
         "`reparent`는 직계 자식을 삭제할 카테고리의 부모로 옮기고, `cascade`는 서브트리를 삭제하고 연결 상품을 미분류로 둔다",
     ),
 });
+
+/**
+ * 카테고리 번역 (이슈 #134) — 언어 하나의 이름·SEO. 카테고리 필드(`name`·`meta*`)는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
+ * 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다(칸 단위 대체).
+ */
+export const categoryLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  name: z.string().nullable().describe("이름. null이면 기본 언어 이름"),
+  metaTitle: z.string().nullable(),
+  metaDescription: z.string().nullable(),
+  metaKeywords: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+export type CategoryLocalization = z.infer<typeof categoryLocalizationSchema>;
+
+/** `PUT /v1/categories/{categoryId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null(기본 언어 값으로 대체)이다 */
+export const categoryLocalizationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(100).nullable().optional(),
+  metaTitle: z.string().max(100).nullable().optional(),
+  metaDescription: z.string().max(300).nullable().optional(),
+  metaKeywords: z.string().max(200).nullable().optional(),
+});
+
+export type CategoryLocalizationRequest = z.infer<typeof categoryLocalizationRequestSchema>;

package/src/schemas/collection.ts

@@ -587,3 +587,28 @@ export const collectionPreviewSchema = z.object({
 });
 
 export type CollectionPreview = z.infer<typeof collectionPreviewSchema>;
+
+/**
+ * 컬렉션 번역 (이슈 #134) — 언어 하나의 제목·설명·SEO. 컬렉션 필드는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
+ * 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다(칸 단위 대체).
+ */
+export const collectionLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  title: z.string().nullable().describe("제목. null이면 기본 언어 제목"),
+  description: z.string().nullable(),
+  metaTitle: z.string().nullable(),
+  metaDescription: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+export type CollectionLocalization = z.infer<typeof collectionLocalizationSchema>;
+
+/** `PUT /v1/collections/{collectionId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null(기본 언어 값으로 대체)이다 */
+export const collectionLocalizationRequestSchema = z.strictObject({
+  title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).nullable().optional(),
+  description: z.string().trim().max(MAX_COLLECTION_DESCRIPTION).nullable().optional(),
+  metaTitle: z.string().trim().max(60).nullable().optional(),
+  metaDescription: z.string().trim().max(160).nullable().optional(),
+});
+
+export type CollectionLocalizationRequest = z.infer<typeof collectionLocalizationRequestSchema>;

package/src/schemas/locale.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+/**
+ * 언어 코드 (이슈 #134) — BCP 47의 언어[-문자][-지역]까지 받는다(`ko`·`en`·`en-US`·`zh-Hant-TW`).
+ * 대소문자는 표준 표기로 맞춘다(언어 소문자, 문자 첫 글자 대문자, 지역 대문자). 맞지 않으면 null이다.
+ */
+const LOCALE_PATTERN = /^([a-z]{2,3})(?:-([a-z]{4}))?(?:-([a-z]{2}))?$/;
+
+export function normalizeLocale(value: string | null | undefined): string | null {
+  const match = value?.trim().replace(/_/g, "-").toLowerCase().match(LOCALE_PATTERN);
+  if (!match) return null;
+  const [, language, script, region] = match;
+  return [
+    language,
+    script ? `${script[0]?.toUpperCase()}${script.slice(1)}` : null,
+    region ? region.toUpperCase() : null,
+  ]
+    .filter(Boolean)
+    .join("-");
+}
+
+/** 상점 기본 언어 — 옛 상점과 언어를 정하지 않은 상점의 값이다 */
+export const DEFAULT_STORE_LOCALE = "ko";
+
+export const localeCodeSchema = z
+  .string()
+  .max(35)
+  .transform((value, ctx) => {
+    const normalized = normalizeLocale(value);
+    if (normalized === null) {
+      ctx.addIssue({
+        code: "custom",
+        message: "언어는 BCP 47 언어 코드입니다(예: ko·en·en-US)",
+      });
+      return z.NEVER;
+    }
+    return normalized;
+  })
+  .describe("언어(BCP 47, 예: ko·en·en-US·zh-Hant-TW)");

package/src/schemas/market.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { currencyCodeSchema } from "./currency";
+import { localeCodeSchema } from "./locale";
 
 /**
  * 판매 권역 (이슈 #130) — 상점이 어느 국가에 어느 통화로 파는지를 정한다.
@@ -9,6 +10,8 @@ import { currencyCodeSchema } from "./currency";
  *
  * 스토어프론트는 요청마다 도메인(`X-Storefront-Host`) → 구매자 국가(`X-Buyer-Country`) → 기본 권역 순으로 권역을 고르고, 주문서가 그 권역·통화를 굳힌다.
  * 외화 권역은 적립금을 켤 수 없다(적립금은 기본 통화 단위다).
+ *
+ * 권역은 언어도 정한다(이슈 #134). `locales`는 이 권역 스토어프론트가 내는 언어이고 첫 언어가 대표 언어다. 비어 있으면 상점 기본 언어 하나다.
  */
 
 const countryCodeSchema = z
@@ -44,6 +47,13 @@ export const marketSchema = z.object({
     .string()
     .nullable()
     .describe("보관 시각. 보관한 권역은 판정에서 빠지고 그 국가·도메인은 풀린다"),
+  locales: z
+    .array(z.string())
+    .optional()
+    .default([])
+    .describe(
+      "이 권역 언어(이슈 #134). 첫 언어가 대표 언어다. 비어 있으면 상점 기본 언어 하나다. 서버는 항상 싣는다",
+    ),
 });
 
 export type Market = z.infer<typeof marketSchema>;
@@ -55,6 +65,13 @@ export const createMarketRequestSchema = z.strictObject({
   domains: z.array(hostnameSchema).max(20).optional(),
   couponsEnabled: z.boolean().optional().describe("기본 false"),
   pointsEnabled: z.boolean().optional().describe("기본 false. 외화 권역은 true로 둘 수 없다"),
+  locales: z
+    .array(localeCodeSchema)
+    .max(20)
+    .optional()
+    .describe(
+      "이 권역 언어(이슈 #134). 주면 목록 전체를 바꾼다. 첫 언어가 대표 언어다. 비우면 상점 기본 언어 하나다",
+    ),
 });
 
 export type CreateMarketRequest = z.infer<typeof createMarketRequestSchema>;
@@ -70,6 +87,13 @@ export const updateMarketRequestSchema = z.strictObject({
   domains: z.array(hostnameSchema).max(20).optional().describe("주면 도메인 목록 전체를 바꾼다"),
   couponsEnabled: z.boolean().optional(),
   pointsEnabled: z.boolean().optional().describe("외화 권역은 true로 둘 수 없다"),
+  locales: z
+    .array(localeCodeSchema)
+    .max(20)
+    .optional()
+    .describe(
+      "이 권역 언어(이슈 #134). 주면 목록 전체를 바꾼다. 첫 언어가 대표 언어다. 비우면 상점 기본 언어 하나다",
+    ),
 });
 
 export type UpdateMarketRequest = z.infer<typeof updateMarketRequestSchema>;

package/src/schemas/order.ts

@@ -284,6 +284,13 @@ export const orderSchema = z.object({
     .describe(
       "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았습니다. 상품을 발송하지 않도록 주의하십시오",
     ),
+  locale: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "구매 언어(이슈 #134, BCP 47). 주문상품의 상품명·옵션 이름은 구매자가 이 언어로 본 값이다. null이면 상점 기본 언어다(언어 기능 이전 주문 포함)",
+    ),
   items: z.array(orderItemSchema),
 });
 
@@ -310,7 +317,7 @@ const pageQuery = {
 
 /**
  * `GET /v1/orders` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 검증 규칙은 서버가 적용한다:
- * `orderNo` 없이 `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜·`orderNo` 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
+ * `orderNo` 없이 `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜·`orderNo` 형식 오류 400 `INVALID_PARAMETER`, 366일 초과 400 `RANGE_TOO_WIDE`,
  * `testPayment`가 `true`·`false`가 아니면 400 `INVALID_PARAMETER`
  */
 export const orderListQuerySchema = z.object({
@@ -321,7 +328,7 @@ export const orderListQuerySchema = z.object({
   orderedTo: z
     .string()
     .optional()
-    .describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일"),
+    .describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 366일"),
   status: orderItemStatusSchema
     .optional()
     .describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),

package/src/schemas/product-info.ts

@@ -188,3 +188,29 @@ export const infoSectionRequestSchema = z.object({
 
 export type InfoSectionRequest = z.infer<typeof infoSectionRequestSchema>;
 export type InfoSectionRequestInput = z.input<typeof infoSectionRequestSchema>;
+
+/**
+ * 안내 섹션 번역 (이슈 #134) — 언어 하나의 제목·본문. 섹션 필드는 상점 기본 언어 값이다. 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다.
+ * 섹션을 연결한 모든 상품이 같은 번역을 보인다.
+ */
+export const infoSectionLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  title: z.string().nullable(),
+  body: z
+    .string()
+    .nullable()
+    .describe("본문 HTML(상세설명과 같은 정화 규칙). null이면 기본 언어 본문"),
+  bodyJson: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+export type InfoSectionLocalization = z.infer<typeof infoSectionLocalizationSchema>;
+
+/** `PUT /v1/info-sections/{infoSectionId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null이다 */
+export const infoSectionLocalizationRequestSchema = z.strictObject({
+  title: z.string().trim().min(1).max(MAX_INFO_SECTION_TITLE).nullable().optional(),
+  body: z.string().nullable().optional(),
+  bodyJson: z.string().nullable().optional(),
+});
+
+export type InfoSectionLocalizationRequest = z.infer<typeof infoSectionLocalizationRequestSchema>;

package/src/schemas/product-localization.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { MAX_PRODUCT_IMAGES, productImageUrlSchema } from "./product";
+import { MAX_NOTICE_VALUE_LENGTH } from "./product-info";
+
+/**
+ * 상품 번역 (이슈 #134) — 언어 하나의 상품명·상세설명·이미지·옵션 이름. 상품 필드는 상점 기본 언어 값이고 번역 레코드가 언어별 값이다.
+ * 비운 칸(null)은 스토어프론트가 기본 언어 값으로 대체한다(칸 단위 대체). 이미지는 목록 통째로 대체한다.
+ * 옵션은 id가 원천이다 — 값 id·추가금·재고는 언어와 무관하고 이름만 언어별이다.
+ */
+
+const translatedOptionValueSchema = z.object({
+  valueId: z.string(),
+  name: z.string().nullable().describe("값 이름. null이면 기본 언어 이름"),
+});
+
+const translatedOptionGroupSchema = z.object({
+  groupId: z.string(),
+  name: z.string().nullable().describe("옵션명. null이면 기본 언어 이름"),
+  values: z.array(translatedOptionValueSchema),
+});
+
+const translatedCustomInputSchema = z.object({
+  inputId: z.string(),
+  label: z.string().nullable().describe("항목명. null이면 기본 언어 항목명"),
+  placeholder: z.string().nullable().describe("입력 안내. null이면 기본 언어 안내"),
+});
+
+const translatedNoticeValueSchema = z.object({
+  key: z.string().describe("고시 칸 키"),
+  label: z.string().describe("칸 이름(원문)"),
+  value: z.string().nullable().describe("셀러 값 번역. null이면 기본 언어 값"),
+});
+
+/**
+ * 조회 응답 — 지금 상품의 옵션명·값·직접 입력 항목, 셀러가 적은 고시 칸을 모두 싣고 번역하지 않은 칸은 null이다.
+ * `optionGroups`는 조합 옵션, `addonGroups`는 추가 선택이다(상품 응답과 같은 구분)
+ */
+export const productLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  name: z.string().nullable().describe("상품명. null이면 기본 언어 상품명"),
+  description: z.string().nullable().describe("상세설명(HTML). null이면 기본 언어 상세설명"),
+  descriptionJson: z.string().nullable().describe("상세설명 에디터 상태(재편집 복원용)"),
+  images: z.array(z.string()).nullable().describe("이미지 목록. null이면 기본 언어 목록"),
+  optionGroups: z.array(translatedOptionGroupSchema),
+  addonGroups: z.array(translatedOptionGroupSchema),
+  customInputs: z.array(translatedCustomInputSchema),
+  notice: z
+    .array(translatedNoticeValueSchema)
+    .optional()
+    .default([])
+    .describe(
+      "셀러가 적은 상품정보제공 고시 칸의 값 번역(이슈 #134). 출처·법정 문구 칸은 싣지 않는다",
+    ),
+  updatedAt: z.string(),
+});
+
+export type ProductLocalization = z.infer<typeof productLocalizationSchema>;
+
+const translatedNameSchema = z.string().trim().min(1).max(50).nullable().optional();
+
+const translatedOptionGroupRequestSchema = z.strictObject({
+  groupId: z.string(),
+  name: translatedNameSchema,
+  values: z.array(z.strictObject({ valueId: z.string(), name: translatedNameSchema })).optional(),
+});
+
+/**
+ * `PUT /v1/products/{productId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 빠진 칸은 null(기본 언어 값으로 대체)이다.
+ * 옵션은 번역할 id만 보낸다. 상품에 없는 id는 400 `PRODUCT_LOCALIZATION_TARGET_NOT_FOUND`다.
+ * 번역한 옵션명·값 이름도 기본 언어와 같은 규칙(대소문자·앞뒤 공백 무시 유일)이고 겹치면 400 `INVALID_OPTION_MODEL`이다
+ */
+export const productLocalizationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(100).nullable().optional(),
+  description: z.string().nullable().optional(),
+  descriptionJson: z.string().nullable().optional(),
+  images: z.array(productImageUrlSchema).min(1).max(MAX_PRODUCT_IMAGES).nullable().optional(),
+  optionGroups: z.array(translatedOptionGroupRequestSchema).optional(),
+  addonGroups: z.array(translatedOptionGroupRequestSchema).optional(),
+  customInputs: z
+    .array(
+      z.strictObject({
+        inputId: z.string(),
+        label: z.string().trim().min(1).max(30).nullable().optional(),
+        placeholder: z.string().trim().min(1).max(100).nullable().optional(),
+      }),
+    )
+    .optional(),
+  notice: z
+    .array(
+      z.strictObject({
+        key: z.string(),
+        value: z.string().trim().min(1).max(MAX_NOTICE_VALUE_LENGTH).nullable().optional(),
+      }),
+    )
+    .optional()
+    .describe(
+      "고시 칸 값 번역. 상품에 셀러 값이 없는 칸 키는 400 `PRODUCT_LOCALIZATION_TARGET_NOT_FOUND`",
+    ),
+});
+
+export type ProductLocalizationRequest = z.infer<typeof productLocalizationRequestSchema>;
+
+/**
+ * 번역할 칸이 비었는가(이슈 #134, 2026-10-18 결정: 완성도 대신 「번역 필요」 표시만) — 상품명, 기본 언어에 본문이 있는 상세설명,
+ * 옵션명·값·직접 입력 항목명, 셀러가 적은 고시 칸. 이미지·입력 안내는 기본 언어 값을 그대로 써도 되는 칸이라 세지 않는다.
+ * 상점 플랫폼(상품 수정·목록)과 관리 목록 응답이 같은 함수다
+ */
+export function productLocalizationNeedsTranslation(
+  localization: Pick<
+    ProductLocalization,
+    "name" | "description" | "optionGroups" | "addonGroups" | "customInputs"
+  > & { notice?: ProductLocalization["notice"] },
+  base: { description?: string | null },
+): boolean {
+  if (!localization.name) return true;
+  if ((base.description ?? "").trim() && !localization.description) return true;
+  const groups = [...localization.optionGroups, ...localization.addonGroups];
+  if (groups.some((group) => !group.name || group.values.some((value) => !value.name))) return true;
+  if (localization.customInputs.some((item) => !item.label)) return true;
+  return (localization.notice ?? []).some((entry) => !entry.value);
+}

package/src/schemas/product.ts

@@ -67,6 +67,18 @@ export const productSummarySchema = z.object({
     .describe(
       "상점을 만들 때 넣은 샘플 상품인가(이슈 #70). 상점 플랫폼이 「샘플」 배지를 단다. 스토어프론트에는 싣지 않는다. 서버는 항상 싣는다",
     ),
+  localizations: z
+    .array(
+      z.object({
+        locale: z.string().describe("언어(BCP 47)"),
+        needsTranslation: z
+          .boolean()
+          .describe("번역할 칸이 비었는가(`productLocalizationNeedsTranslation`과 같은 규칙)"),
+      }),
+    )
+    .optional()
+    .default([])
+    .describe("번역 레코드가 있는 언어(이슈 #134). 상점 기본 언어는 싣지 않는다"),
 });
 
 export type ProductSummary = z.infer<typeof productSummarySchema>;
@@ -372,7 +384,7 @@ export const discountSchema = z.object({
 
 export type Discount = z.infer<typeof discountSchema>;
 
-export const productSchema = productSummarySchema.extend({
+export const productSchema = productSummarySchema.omit({ localizations: true }).extend({
   prices: z
     .array(storedProductCurrencyPriceSchema)
     .optional()

package/src/schemas/saved-option-set.ts

@@ -174,3 +174,65 @@ export const savedOptionSetListQuerySchema = z.object({
   sort: savedOptionSetSortSchema.optional().describe("정렬 (기본 updatedAt.desc)"),
   ...pageQueryShape({ defaultSize: 20, maxSize: 200 }),
 });
+
+/**
+ * 저장 옵션 번역 (이슈 #134) — 저장 옵션에는 id가 없어 **기본 언어 이름이 키**다(`baseName`·`baseLabel`).
+ * 상품이 불러올 때 상품 번역으로 함께 복사하고(상품 저장 트랜잭션), 그 뒤로는 상품 번역이 원천이다 — 저장 옵션 번역을 고쳐도
+ * 이미 불러온 상품은 그대로다. 기본 언어 이름을 바꾸면 그 이름의 번역은 읽지 않는다.
+ */
+export const savedOptionSetLocalizationSchema = z.object({
+  locale: z.string().describe("언어(BCP 47)"),
+  groups: z.array(
+    z.object({
+      baseName: z.string().describe("기본 언어 옵션명"),
+      name: z.string().nullable().describe("번역 옵션명. null이면 기본 언어 이름"),
+      values: z.array(
+        z.object({
+          baseName: z.string(),
+          name: z.string().nullable(),
+        }),
+      ),
+    }),
+  ),
+  customInputs: z.array(
+    z.object({
+      baseLabel: z.string().describe("기본 언어 항목명"),
+      label: z.string().nullable(),
+      placeholder: z.string().nullable(),
+    }),
+  ),
+  updatedAt: z.string(),
+});
+
+export type SavedOptionSetLocalization = z.infer<typeof savedOptionSetLocalizationSchema>;
+
+/**
+ * `PUT /v1/saved-option-sets/{optionSetId}/localizations/{locale}` 본문 — 레코드 전체를 바꾼다. 번역할 이름만 보낸다.
+ * 저장 옵션에 없는 기본 언어 이름은 400 `OPTION_SET_LOCALIZATION_TARGET_NOT_FOUND`, 번역 이름 중복은 상품과 같은 규칙으로 400 `INVALID_OPTION_MODEL`이다
+ */
+export const savedOptionSetLocalizationRequestSchema = z.strictObject({
+  groups: z
+    .array(
+      z.strictObject({
+        baseName: z.string(),
+        name: nameSchema.nullable().optional(),
+        values: z
+          .array(z.strictObject({ baseName: z.string(), name: nameSchema.nullable().optional() }))
+          .optional(),
+      }),
+    )
+    .optional(),
+  customInputs: z
+    .array(
+      z.strictObject({
+        baseLabel: z.string(),
+        label: z.string().trim().min(1).max(30).nullable().optional(),
+        placeholder: z.string().trim().min(1).max(100).nullable().optional(),
+      }),
+    )
+    .optional(),
+});
+
+export type SavedOptionSetLocalizationRequest = z.infer<
+  typeof savedOptionSetLocalizationRequestSchema
+>;

package/src/schemas/store.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { storeRoleSchema } from "./auth";
+import { localeCodeSchema } from "./locale";
 import { refundPolicyPatchSchema, refundPolicySchema } from "./refund-policy";
 import { shippingPolicyPatchSchema, shippingPolicySchema } from "./shipping-policy";
 
@@ -307,6 +308,11 @@ export const updateStoreRequestSchema = z
     privacyUrl: policyDocumentUrlSchema
       .optional()
       .describe("개인정보 수집이용 동의 문서 주소(https). `null`을 주면 지운다"),
+    defaultLocale: localeCodeSchema
+      .optional()
+      .describe(
+        "상점 기본 언어(이슈 #134). 상품·카테고리 필드가 이 언어 값이고 번역이 없는 칸은 이 값으로 보인다. 바꿔도 저장된 값은 그대로다",
+      ),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",
@@ -358,6 +364,11 @@ export const storeSchema = z.object({
     .describe("이용약관 문서 주소. 정하지 않았으면 null이고 동의 이력에도 주소가 남지 않는다"),
   privacyUrl: z.string().nullable().describe("개인정보 수집이용 동의 문서 주소"),
   memberCount: z.number().int(),
+  defaultLocale: z
+    .string()
+    .optional()
+    .default("ko")
+    .describe("상점 기본 언어(이슈 #134, BCP 47). 서버는 항상 싣는다"),
   createdAt: z.string(),
 });