@cartbase/storefront 0.9.0 → 0.11.0

package/src/locales/es.ts

@@ -0,0 +1,467 @@
+import type { StorefrontLocale } from "./types"
+
+/**
+ * SPANISH — neutral European Spanish (es-ES), readable across markets.
+ *
+ * A locale pack, opted into by subpath import, never library copy:
+ *
+ *   import { es } from "@cartbase/storefront/locales/es"
+ *
+ * Typed against the six area shapes, so a label added upstream breaks this
+ * file at compile time rather than falling back to English in the middle
+ * of a Spanish checkout.
+ *
+ * THE TERMINOLOGY IS FIXED, not per translator: carrito, pago, pedido,
+ * envío, entrega, tarjeta regalo, valoración, Agotado, Añadir al carrito,
+ * Seguir comprando. Never usted; the shopper is addressed with the
+ * infinitive or the tú imperative. Buttons carry no final period. Where a
+ * label is a button or a chip the shortest correct wording wins, because
+ * Spanish runs longer than English and the component was laid out in
+ * English.
+ *
+ * Two readings worth knowing, both deliberate: the sort options spell the
+ * relation in words ("Precio: de menor a mayor") because an arrow between
+ * two values is banned in our UI; and "IVA" is used where the English says
+ * VAT, with "Impuestos" kept for the generic word.
+ *
+ * 249 keys, first written 2026-09-13.
+ */
+export const es: StorefrontLocale = {
+  code: "es",
+  name: "Español",
+  products: {
+    selectOption: "Elige",
+    selectVariant: "Elige variante",
+    outOfStock: "Agotado",
+    addToCart: "Añadir al carrito",
+    from: "Desde",
+    original: "Antes:",
+    productInformation: "Información del producto",
+    shippingAndReturns: "Envío y devoluciones",
+    material: "Material",
+    countryOfOrigin: "País de origen",
+    type: "Tipo",
+    weight: "Peso",
+    dimensions: "Dimensiones",
+    fastDelivery: "Entrega rápida",
+    fastDeliveryDescription:
+      "Tu paquete llegará en 3-5 días laborables a tu punto de recogida o a la comodidad de tu casa.",
+    simpleExchanges: "Cambios sencillos",
+    simpleExchangesDescription:
+      "¿No te queda del todo bien? Sin problema, cambiamos tu producto por uno nuevo.",
+    easyReturns: "Devoluciones fáciles",
+    easyReturnsDescription:
+      "Solo tienes que devolver tu producto y te reembolsamos el dinero. Sin preguntas: haremos todo lo posible para que tu devolución sea sencilla.",
+    relatedProducts: "Productos relacionados",
+    relatedProductsDescription:
+      "Quizá también te interesen estos productos.",
+  },
+  store: {
+    allProducts: "Todos los productos",
+    sortBy: "Ordenar por",
+    latestArrivals: "Novedades",
+    priceLowToHigh: "Precio: de menor a mayor",
+    priceHighToLow: "Precio: de mayor a menor",
+    searchTitle: "Búsqueda",
+    searchPlaceholder: "Buscar productos…",
+    searchAction: "Buscar",
+    resultsFor: "Resultados para",
+    resultsCount: "resultados",
+    noResults: "No se han encontrado productos",
+    filters: "Filtros",
+    clearFilters: "Borrar filtros",
+  },
+  cartDrawer: {
+    yourCart: "Tu carrito",
+    item: "artículo",
+    items: "artículos",
+    closeCart: "Cerrar carrito",
+
+    emptyCartTitle: "Tu carrito está vacío",
+    emptyCartMessage: "Todavía no has añadido ningún producto.",
+    browseProducts: "Ver productos",
+
+    awayFromFreeShipping: "para el envío gratis",
+    allRewardsUnlocked: "Todas las recompensas desbloqueadas",
+
+    addGiftWrap: "Añadir envoltorio de regalo",
+    giftNote: "Nota de regalo",
+    orderNote: "Nota del pedido",
+    giftNotePlaceholder: "Añade un mensaje personal...",
+    orderNotePlaceholder: "Instrucciones especiales para este pedido...",
+
+    estimatedRewardPoints: "Puntos de recompensa estimados",
+
+    pairsWellWith: "Combina bien con",
+    youllLoveThis: "Te va a encantar",
+    youMightAlsoLike: "También te puede gustar",
+    addToCart: "Añadir",
+
+    subtotal: "Subtotal",
+    taxAndShipping: "IVA incluido. El envío se calcula en el pago.",
+    shipping: "Envío",
+    free: "Gratis",
+    calculatedAtCheckout: "Se calcula en el pago",
+    total: "Total",
+    secureCheckout: "Finalizar compra",
+    shippingAndTaxCalculatedAtCheckout: "El envío y los impuestos se calculan en el pago",
+
+    discount: "Descuento",
+    tax: "IVA",
+    paymentMethodFee: "Comisión por método de pago",
+    giftCard: "Tarjeta regalo",
+    remainingToPay: "Pendiente de pago",
+
+    continueShopping: "Seguir comprando",
+
+    remove: "Eliminar",
+  },
+  checkout: {
+    deliveryInfo: "Información de entrega",
+    shippingServices: "Método de envío",
+    paymentMethod: "Método de pago",
+    orderSummary: "Resumen del pedido",
+
+    email: "Correo electrónico",
+    country: "País",
+    singleCountryName: undefined,
+    firstName: "Nombre",
+    lastName: "Apellidos",
+    address: "Dirección",
+    apartment: "Apartamento, piso, etc. (opcional)",
+    city: "Ciudad",
+    postalCode: "Código postal",
+    phone: "Teléfono",
+    province: "Estado / provincia",
+
+    saveAddress: "Guardar y continuar",
+    updateAddress: "Actualizar dirección",
+    addToOrder: "+ Añadir al pedido",
+    addCode: "Aplicar",
+
+    deliveryDisabled:
+      "Introduce tu dirección de entrega para ver las opciones de envío disponibles.",
+    noShippingOptions: "No hay opciones de envío disponibles para tu dirección.",
+    paymentDisabled: "Elige un método de envío para continuar.",
+    deliveryPreviewHint: "Introduce tu dirección para elegir un método de entrega.",
+    buyNeedsAddress: "Introduce tu dirección de entrega",
+    buyNeedsDelivery: "Elige un método de entrega",
+
+    codNote: "Contra reembolso. Pueden aplicarse cargos adicionales.",
+    payOnline: "Pago online",
+    cashOnDelivery: "Contra reembolso",
+    termsText:
+      "Al realizar tu pedido aceptas nuestros Términos y la Política de privacidad.",
+
+    useSavedAddress: "¿Usar una dirección guardada?",
+    saveInfo: "Guardar estos datos para la próxima vez",
+
+    chooseAddress: "Elige una dirección",
+
+    items: "artículos",
+    qty: "Cant.",
+    subtotal: "Subtotal",
+    shipping: "Envío",
+    shippingCalc: "Se calcula en el pago",
+    shippingFree: "Gratis",
+    tax: "IVA incl.",
+    taxTooltip: "El IVA del 20% está incluido en los precios",
+    total: "Total",
+    discount: "Descuento",
+    discountCode: "Código de descuento",
+    discountSub: "Ahorra con un código promocional",
+    paymentMethodFee: "Comisión del método de pago",
+    recommended: "Recomendado para ti",
+    recommendedSoon: "Próximamente",
+    recommendedSoonSub: "Recomendaciones personalizadas",
+    remove: "Quitar",
+    secureCheckout: "Pago seguro",
+
+    giftCard: "Tarjeta regalo",
+    giftCardSub: "Canjea una tarjeta regalo",
+    giftCardPlaceholder: "GIFT-XXXX-XXXX",
+    giftCardApplied: "Tarjetas regalo",
+    giftCardRemaining: "Queda por pagar",
+    giftCardEnding: "Tarjeta regalo terminada en",
+
+    companyInvoice: "Factura de empresa",
+    companyName: "Nombre de la empresa",
+    companyVat: "NIF / CIF",
+    companyMol: "Persona responsable",
+    companyAddress: "Dirección de la empresa",
+
+    placeOrder: "Realizar pedido",
+    selectPaymentMethod: "Elige un método de pago",
+
+    processingCard: [
+      "Conectando con el banco...",
+      "Confirmando el pago...",
+      "Registrando el pedido...",
+      "Cuidando cada detalle...",
+    ],
+    processingCod: [
+      "Reservando la entrega...",
+      "Preparando el pedido...",
+      "Cuidando cada detalle...",
+    ],
+
+    econtLoadingOffices: "Cargando oficinas...",
+    econtNearestOffices: "Oficinas más cercanas",
+    econtSearchAnother: "Buscar otra oficina",
+    econtSearchPlaceholder: "Busca por nombre, ciudad o dirección...",
+    econtNoResults: "No se han encontrado oficinas para",
+    econtChange: "Cambiar",
+
+    boxnowLoadingLockers: "Cargando taquillas...",
+    boxnowNearestLockers: "Taquillas más cercanas",
+    boxnowSearchAnother: "Buscar otra taquilla",
+    boxnowSearchPlaceholder: "Busca por nombre, dirección o código postal...",
+    boxnowNoResults: "No se han encontrado taquillas para",
+    boxnowChange: "Cambiar",
+    boxnowUnavailable:
+      "BoxNow no está disponible temporalmente, elige otro método de envío.",
+    boxnowNoLockersInCity:
+      "No hay taquillas de BoxNow en tu ciudad. Elige otro método de envío.",
+    addressErrors: {
+      generic:
+        "No hemos podido guardar tu dirección. Revisa los datos e inténtalo de nuevo.",
+      network:
+        "No hay conexión con el servidor. Revisa tu conexión e inténtalo de nuevo.",
+      validationFailed:
+        "Alguno de los campos no es válido. Revisa los datos e inténtalo de nuevo.",
+      invalidRegion: "Ese país no es válido. Recarga la página.",
+      regionRequired: "La región de envío no es válida. Recarga la página.",
+      cartCompleted:
+        "El pedido ya está finalizado. Revisa tu correo para ver la confirmación.",
+      cartNotFound: "Tu sesión del carrito ha caducado. Recarga la página.",
+      invalidEmail: "Ese correo electrónico no es válido. Revisa cómo está escrito.",
+      invalidPostalCode: "Ese código postal no es válido. Revísalo.",
+      invalidPhone: "Ese número de teléfono no es válido. Revisa los dígitos.",
+      invalidCountry: "Ese país no es válido. Recarga la página.",
+    },
+    paymentErrors: {
+      genericCard:
+        "El pago no se ha podido procesar ahora mismo. Inténtalo de nuevo o elige otro método de pago.",
+      genericCod:
+        "El pedido no se ha podido completar ahora mismo. Inténtalo de nuevo en unos momentos.",
+      cartEmailRequired:
+        "Hace falta un correo electrónico para finalizar la compra. Añade uno para continuar.",
+      cartEmpty: "Tu carrito está vacío. Añade un producto para continuar.",
+      shippingAddressRequired:
+        "Hace falta una dirección de envío para finalizar la compra. Añade una para continuar.",
+      shippingMethodRequired: "Elige un método de envío para continuar.",
+      paymentCollectionRequired: "El pago aún no está listo. Inténtalo de nuevo.",
+      paymentSessionRequired: "El pago aún no está listo. Inténtalo de nuevo.",
+      insufficientInventory:
+        "Uno de los productos ya no está disponible en la cantidad elegida. Actualiza tu carrito para continuar.",
+      checkoutMethodHidden:
+        "El método elegido ya no está disponible para este pedido. Elige otro e inténtalo de nuevo.",
+      requiresAction:
+        "Tu banco necesita confirmar este pago. Sigue los pasos que te indique para continuar.",
+      paymentNotAuthorized:
+        "El pago no se ha aprobado. Inténtalo de nuevo o elige otro método de pago.",
+      paymentNotInitiated:
+        "El pago ha caducado antes de completarse. Recarga la página e inténtalo de nuevo.",
+      paymentIncomplete:
+        "Tus tarjetas regalo ya no cubren el importe total. Elige un método de pago para el resto.",
+      giftCardInsufficientBalance:
+        "El saldo de esa tarjeta regalo ya no cubre el importe. Retírala o elige otro método de pago.",
+      giftCardNotRedeemable:
+        "Esa tarjeta regalo ya no se puede usar. Retírala e inténtalo de nuevo.",
+      accountRequired:
+        "Para finalizar la compra tienes que iniciar sesión. Inicia sesión para continuar.",
+      cartLocked:
+        "Este pedido se está procesando ahora mismo. Espera unos segundos antes de volver a intentarlo.",
+      cartCompleted:
+        "Este pedido ya se ha completado. Revisa tu correo electrónico para ver la confirmación.",
+      cartNotFound:
+        "Tu carrito ya no está disponible. Recarga la página para empezar de nuevo.",
+      shippingOptionNotFound:
+        "El método de envío elegido ya no está disponible. Elige otro.",
+      invalidProvider: "El método de pago elegido no se puede usar. Elige otro.",
+      shippingPriceMissing:
+        "No se ha podido calcular el coste del envío. Elige otro método de envío.",
+      stripeNotConfigured:
+        "El pago con tarjeta no está disponible en este momento. Elige otro método de pago.",
+      validationFailed:
+        "Faltan algunos datos del pedido. Revisa el formulario e inténtalo de nuevo.",
+      cardDeclined:
+        "El banco ha rechazado esa tarjeta. Prueba con otra tarjeta o contacta con tu banco.",
+      insufficientFunds:
+        "Esa tarjeta no tiene saldo suficiente. Prueba con otra tarjeta.",
+      expiredCard: "Esa tarjeta ha caducado. Prueba con otra tarjeta.",
+      incorrectCvc:
+        "El código de seguridad no coincide. Revisa el código de seguridad de tu tarjeta e inténtalo de nuevo.",
+      incorrectCardNumber:
+        "El número de tarjeta no parece correcto. Revisa los dígitos e inténtalo de nuevo.",
+      invalidExpiry:
+        "La fecha de caducidad no parece correcta. Revisa el mes y el año.",
+      authenticationRequired:
+        "Tu banco necesita confirmar este pago. Sigue los pasos que te indique para continuar.",
+      processingError:
+        "No se ha podido procesar la tarjeta. Inténtalo de nuevo en unos momentos.",
+      rateLimited:
+        "Se han hecho demasiados intentos de pago. Espera unos minutos e inténtalo de nuevo.",
+      paymentExpired:
+        "El pago ha caducado antes de completarse. Recarga la página e inténtalo de nuevo.",
+      amountMismatch:
+        "El importe del pedido ha cambiado. Recarga la página e inténtalo de nuevo.",
+      networkError:
+        "Se ha perdido la conexión. Revisa tu conexión a internet e inténtalo de nuevo.",
+      cartAlreadyCompleted:
+        "Este pedido ya se ha completado. Revisa tu correo electrónico para ver la confirmación.",
+      outOfStock:
+        "Uno de los productos ya no está disponible en la cantidad elegida. Actualiza tu carrito para continuar.",
+      invalidRegion:
+        "Este destino de envío no está disponible. Recarga la página e inténtalo de nuevo.",
+      shippingMethodMissing: "Elige un método de envío para continuar.",
+    },
+    giftCardErrors: {
+      invalidGiftCard:
+        "Ese código de tarjeta regalo no es válido. Revisa el código e inténtalo de nuevo.",
+      rateLimited: "Demasiados intentos. Espera unos minutos e inténtalo de nuevo.",
+      cartCompleted:
+        "Este pedido ya está finalizado. Revisa tu correo para ver la confirmación.",
+      cartNotFound: "Tu carrito ha caducado. Recarga la página e inténtalo de nuevo.",
+      validationFailed: "Ese código no es válido. Revísalo e inténtalo de nuevo.",
+      generic:
+        "La tarjeta regalo no se ha podido aplicar ahora mismo. Inténtalo de nuevo en un momento.",
+    },
+    promotionErrors: {
+      generic:
+        "Este código de descuento no se puede aplicar ahora mismo. Revisa el código e inténtalo de nuevo.",
+      needsEmail:
+        "Este código de descuento necesita una dirección de correo electrónico. Añade la tuya arriba e inténtalo de nuevo.",
+      exhausted: "Esta promoción se ha agotado y ya no está disponible.",
+      promotionNotFound:
+        "Este código de descuento no es válido. Revísalo e inténtalo de nuevo.",
+      promotionInactive: "Este código de descuento ya no está activo.",
+      promotionMisconfigured:
+        "Este código de descuento no se puede aplicar ahora mismo. Revisa el código e inténtalo de nuevo.",
+      promotionUnsupportedType:
+        "Este código de descuento no se puede aplicar ahora mismo. Revisa el código e inténtalo de nuevo.",
+      cartCompleted:
+        "Este pedido ya se ha realizado. Revisa tu correo electrónico para ver la confirmación.",
+      cartNotFound:
+        "No encontramos tu carrito. Recarga la página e inténtalo de nuevo.",
+      validationFailed:
+        "Este código de descuento no es válido. Revísalo e inténtalo de nuevo.",
+    },
+  },
+  order: {
+    orderConfirmed: "Pedido confirmado",
+    confirmationSent: "Hemos enviado una confirmación a",
+    orderNumber: "Pedido",
+    orderDate: "Fecha",
+    summary: "Resumen del pedido",
+    subtotal: "Subtotal",
+    shipping: "Envío",
+    discount: "Descuento",
+    tax: "Impuestos",
+    total: "Total",
+    paymentMethodFee: "Comisión por método de pago",
+    contactInfo: "Datos de contacto",
+    delivery: "Entrega",
+    paymentMethod: "Método de pago",
+    paymentMethodTitles: {
+      card: "Tarjeta de crédito / débito",
+      cod: "Contra reembolso",
+      manual: "Pago manual",
+      paypal: "PayPal",
+    },
+    needHelp: "¿Necesitas ayuda?",
+    contactUs: "Contacta con nosotros",
+    returnsExchanges: "Devoluciones y cambios",
+    orderPlaced: "Realizado",
+    processing: "En proceso",
+    shipped: "Enviado",
+    delivered: "Entregado",
+    free: "Gratis",
+    continueShopping: "Seguir comprando",
+    qty: "cant.",
+    tracking: "Seguimiento",
+  },
+  reviews: {
+    sectionTitle: "Valoraciones",
+    reviewSingular: "valoración",
+    reviewPlural: "valoraciones",
+    sortAria: "Ordenar",
+    sortDefault: "Recomendadas",
+    sortNewest: "Más recientes",
+    sortRatingDesc: "Mejor valoradas",
+    sortRatingAsc: "Peor valoradas",
+    verified: "Compra verificada",
+    verifiedTitle: "Comprador real, verificado mediante un enlace de pedido",
+    loadMore: "Mostrar más",
+    loading: "Cargando...",
+    dateToday: "hoy",
+    dateYesterday: "ayer",
+    dateDaysAgo: "hace {n} días",
+    showPhoto: "Ver foto",
+    playVideo: "Reproducir vídeo",
+    close: "Cerrar",
+    expiredTitle: "Este enlace de valoración ha caducado",
+    expiredBody:
+      "El enlace era válido durante 60 días desde tu compra. Si quieres dejar una valoración, escríbenos a {email}.",
+    invalidTitle: "Este enlace de valoración no es válido",
+    invalidBody:
+      "Puede que hayas abierto un enlace antiguo. Si tienes alguna duda, escríbenos a {email}.",
+    alreadyTitle: "¡Gracias por tu valoración!",
+    alreadyBodyWithProduct: "Ya hemos recibido tu valoración de {name}.",
+    alreadyBody: "Esta valoración ya se ha enviado.",
+    greeting: "Hola",
+    headingRate: "Comparte tu opinión",
+    headingPhoto: "Solo queda un paso",
+    introRate:
+      "Una valoración breve con tus palabras ayuda a quienes están pensando en la misma elección.",
+    introPhoto:
+      "Tu puntuación está guardada. Añade una foto del producto y consigue un {pct}% de descuento en tu próximo pedido.",
+    productLabel: "Producto",
+    ratingLabel: "Puntuación",
+    ratingOutOf: "{n} de 5",
+    ratingAria: "{n} de 5 estrellas",
+    bodyLabel: "¿Qué te gustó y qué no?",
+    bodyPlaceholder:
+      "Descríbelo con tus palabras. Cuanto más detalle, más útil para el próximo cliente.",
+    consentNote:
+      "Al enviar la valoración aceptas que la publiquemos en la página del producto.",
+    continue: "Continuar",
+    submitting: "Enviando...",
+    bonusBadge: "Extra",
+    photoTitle: "Enséñalo y llévate un {pct}%",
+    photoSubtitle:
+      "Añade una foto o un vídeo corto del producto y te regalamos un {pct}% de descuento para tu próximo pedido.",
+    dropHint: "Arrastra los archivos aquí o haz clic para elegir",
+    dropLimits: "Hasta {n} fotos (JPG/PNG/WEBP, 8 MB), 1 vídeo (MP4/MOV, 50 MB, 60 s)",
+    skip: "Omitir",
+    skipAria: "Omitir",
+    submitPhoto: "Enviar y obtener el {pct}%",
+    waitingUpload: "Esperando la subida...",
+    remove: "Quitar",
+    thanksTitle: "¡Gracias!",
+    thanksBody: "Hemos recibido tu valoración y ya está publicada en la página del producto.",
+    rewardTitle: "Tu descuento del {pct}%",
+    copy: "Copiar",
+    copied: "Copiado",
+    copyAria: "Copiar el código",
+    rewardNote:
+      "También te hemos enviado el código por correo. Úsalo en tu próximo pedido: es válido para un solo uso.",
+    codeUnavailable:
+      "La foto se ha guardado. Algo ha fallado al generar tu código de descuento: escríbenos a {email} y te lo enviamos enseguida.",
+    viewProduct: "Ver producto",
+    toStore: "Volver a la tienda",
+    errUnsupported: "El archivo {name} no tiene un formato compatible.",
+    errMaxImages: "Máximo {n} fotos.",
+    errImageTooLarge: "La foto {name} supera los {mb} MB.",
+    errMaxVideos: "Máximo {n} vídeo.",
+    errVideoTooLarge: "El vídeo supera los {mb} MB.",
+    errVideoTooLong: "El vídeo dura más de {s} segundos.",
+    errVideoMeta: "No hemos podido leer la duración del vídeo.",
+    errUploadFailed: "No se ha podido subir {name}. Inténtalo de nuevo.",
+    errRateLimited: "Se han enviado demasiadas valoraciones desde esta dirección. Inténtalo más tarde.",
+    errAlreadySubmitted: "Esta valoración ya se ha enviado.",
+    errExpired: "El enlace de valoración ha caducado.",
+    errGeneric: "Algo ha fallado. Inténtalo de nuevo.",
+    errPhotoSave: "La foto no se ha podido guardar. Inténtalo de nuevo.",
+  },
+}

package/src/locales/index.ts

@@ -0,0 +1,19 @@
+/**
+ * THE LOCALE LAYER.
+ *
+ * The library speaks international ENGLISH by default and knows nothing
+ * about any other language. A language is a PACK the store imports:
+ *
+ *   import { es } from "@cartbase/storefront/locales/es"
+ *   <StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
+ *
+ * Import a pack by its own subpath (`/locales/es`, `/locales/bg`) rather
+ * than from here, so a store that ships one language does not bundle the
+ * others. This barrel carries the type, the provider and English only.
+ *
+ * Shipping: English, Spanish, Bulgarian (2026-09-13). Adding a language is
+ * one file in this folder plus its export path, and nothing else.
+ */
+export { en } from "./en"
+export { StorefrontLocaleProvider, useStorefrontLocale } from "./provider"
+export type { PropLabelAreas, StorefrontLocale } from "./types"

package/src/locales/provider.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+import { createContext, useContext, type ReactNode } from "react"
+import { CheckoutProvider } from "../checkout/context"
+import { OrderLabelsProvider } from "../order/context"
+import { ProductLabelsProvider } from "../products/context"
+import type { StorefrontLocale } from "./types"
+import { en } from "./en"
+
+const StorefrontLocaleContext = createContext<StorefrontLocale>(en)
+
+/**
+ * ONE PROVIDER FOR THE STORE'S LANGUAGE.
+ *
+ *   import { es } from "@cartbase/storefront/locales/es"
+ *   <StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
+ *
+ * It mounts the three pure label contexts (products, checkout, order) so
+ * every component inside them is localized with no further wiring.
+ *
+ * IT DOES NOT MOUNT THE CART DRAWER, and that is deliberate rather than an
+ * omission: `CartDrawerProvider` carries the cart's state, its client and
+ * its persistence callbacks, so it belongs where the app owns that state,
+ * not inside a language wrapper. Hand it the pack instead:
+ *
+ *   const locale = useStorefrontLocale()
+ *   <CartDrawerProvider cart={cart} labels={locale.cartDrawer}>
+ *
+ * Same for the two areas that read labels from a prop:
+ *
+ *   <StoreTemplate labels={locale.store} />
+ *   <ReviewWidget labels={locale.reviews} />
+ *
+ * DEFAULT IS ENGLISH. A component rendered outside this provider reads the
+ * library's own English defaults, so nothing renders blank or crashes for
+ * want of a provider.
+ */
+export function StorefrontLocaleProvider({
+  locale,
+  children,
+}: {
+  locale: StorefrontLocale
+  children: ReactNode
+}) {
+  return (
+    <StorefrontLocaleContext.Provider value={locale}>
+      <ProductLabelsProvider labels={locale.products}>
+        <CheckoutProvider labels={locale.checkout}>
+          <OrderLabelsProvider labels={locale.order}>{children}</OrderLabelsProvider>
+        </CheckoutProvider>
+      </ProductLabelsProvider>
+    </StorefrontLocaleContext.Provider>
+  )
+}
+
+/**
+ * The whole locale, for the packs this provider cannot mount (the cart
+ * drawer's, the store template's and the reviews widget's) and for the
+ * code that needs the language itself, e.g. `<html lang={locale.code}>`.
+ */
+export function useStorefrontLocale(): StorefrontLocale {
+  return useContext(StorefrontLocaleContext)
+}

package/src/locales/types.ts

@@ -0,0 +1,49 @@
+import type { CartDrawerLabels } from "../cart-drawer/labels"
+import type { CheckoutLabels } from "../checkout/labels"
+import type { OrderLabels } from "../order/labels"
+import type { ProductLabels } from "../products/labels"
+import type { ReviewsUiLabels } from "../reviews-ui/labels"
+import type { StoreLabels } from "../store/labels"
+
+/**
+ * A LOCALE IS ONE OBJECT COVERING THE WHOLE STOREFRONT.
+ *
+ * Before this (2026-09-13) every area shipped its own English defaults and
+ * its own Bulgarian file, so localizing a store meant importing six packs
+ * and mounting four separate providers, and a global package shipped
+ * Bulgarian copy to every merchant on earth. Alexander's ruling: the
+ * library is international ENGLISH, and a language is a pack the store
+ * opts into.
+ *
+ * So: English is the library's own default and lives in each area's
+ * `labels.ts` beside its type. Every other language is a locale pack
+ * imported by subpath — `@cartbase/storefront/locales/es`,
+ * `/locales/bg` — and is typed against these six shapes, which means a
+ * missing translation is a COMPILE ERROR rather than a silent fall back to
+ * English in the middle of a Spanish checkout.
+ *
+ * Adding a language is one file in `src/locales/` plus its export path.
+ * Nothing else in the package changes, and no component knows a language
+ * exists.
+ */
+export interface StorefrontLocale {
+  /** BCP 47 code, for the app's own persistence and for `<html lang>`. */
+  code: string
+  /** The language's own name, for a switcher that does not want Intl. */
+  name: string
+  products: ProductLabels
+  store: StoreLabels
+  cartDrawer: CartDrawerLabels
+  checkout: CheckoutLabels
+  order: OrderLabels
+  reviews: ReviewsUiLabels
+}
+
+/**
+ * The two areas that read labels from a PROP rather than a context
+ * (`store` and `reviews`) are handed their pack by the app:
+ * `<StoreTemplate labels={locale.store} />`. The other four are served by
+ * `StorefrontLocaleProvider`. That split is the components' existing
+ * shape, not a decision of this layer.
+ */
+export type PropLabelAreas = Pick<StorefrontLocale, "store" | "reviews">

package/src/order/index.ts

@@ -5,7 +5,6 @@
  */
 export { OrderLabelsProvider, useOrderLabels } from "./context"
 export { defaultOrderLabels, type OrderLabels } from "./labels"
-export { bulgarianOrderLabels } from "./labels-bg"
 
 export {
   OrderConfirmationHeader,

package/src/primitives/select-field.tsx

@@ -27,10 +27,19 @@ export type SelectFieldProps = React.SelectHTMLAttributes<HTMLSelectElement> & {
   label: string
   children: React.ReactNode
   className?: string
+  /**
+   * A mark shown inside the control, before the value: a flag, a currency
+   * symbol. Decorative and click-through, so the whole field still opens the
+   * select. The value and the floating label make room for it.
+   */
+  leading?: React.ReactNode
 }
 
 export const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>(
-  function SelectField({ label, required, disabled, children, className, value, ...props }, ref) {
+  function SelectField(
+    { label, required, disabled, children, className, value, leading, ...props },
+    ref
+  ) {
     const hasValue = value !== undefined && value !== null && value !== ""
 
     return (
@@ -41,7 +50,8 @@ export const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>
           disabled={disabled}
           value={value}
           className={cn(
-            "w-full h-[44px] px-3 pt-[14px] pb-[2px] pr-9 text-sm rounded-lg border transition-colors duration-150 appearance-none outline-none",
+            "w-full h-[44px] pt-[14px] pb-[2px] pr-9 text-sm rounded-lg border transition-colors duration-150 appearance-none outline-none",
+            leading ? "pl-10" : "px-3",
             "focus:border-primary focus:bg-primary/5",
             disabled
               ? "bg-muted border-border text-muted-foreground cursor-not-allowed"
@@ -51,9 +61,15 @@ export const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>
         >
           {children}
         </select>
+        {leading && (
+          <span className="absolute left-3 top-1/2 -translate-y-1/2 pointer-events-none flex items-center">
+            {leading}
+          </span>
+        )}
         <span
           className={cn(
-            "absolute pointer-events-none left-3 top-[14px] text-sm leading-4 origin-top-left",
+            "absolute pointer-events-none top-[14px] text-sm leading-4 origin-top-left",
+            leading ? "left-10" : "left-3",
             "transition-transform transition-colors duration-150 ease-out",
             hasValue ? "text-muted-foreground" : "text-muted-foreground",
             hasValue ? "-translate-y-2 scale-[0.77]" : "translate-y-0 scale-100"

package/src/products/index.ts

@@ -5,7 +5,6 @@
  */
 export { ProductLabelsProvider, useProductLabels } from "./context"
 export { defaultProductLabels, type ProductLabels } from "./labels"
-export { bulgarianProductLabels } from "./labels-bg"
 
 export {
   optionsAsKeymap,

package/src/reviews-ui/index.ts

@@ -10,7 +10,6 @@ export {
   defaultReviewsUiLabels,
   type ReviewsUiLabels,
 } from "./labels"
-export { bulgarianReviewsUiLabels } from "./labels-bg"
 
 export {
   formatLabel,