Feature: Resolving translated fields based on current locale, while also resturning a correct length aware paginator for the results

docs/product-listing.md

@@ -28,11 +28,13 @@ use Modules\Core\Catalog\ProductSort;
 
 $service = app(ProductService::class);
 
-// List everything, paginated
-$result = $service->list(perPage: 24, page: 1);
+// List everything, paginated — returns a real Illuminate\Pagination\LengthAwarePaginator,
+// built from the localized Meilisearch hits (not Scout's own paginateRaw() result — see
+// "Meilisearch driver quirk" below), so it behaves like any other Laravel paginator.
+$products = $service->list(perPage: 24, page: 1);
 
 // Filter by collection, brand, and/or price range
-$result = $service->list(
+$products = $service->list(
     filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0),
     perPage: 24,
     page: 1,
@@ -40,13 +42,14 @@ $result = $service->list(
 
 // Sort — cheapest/priciest first, or newest first. Omit for Meilisearch's default
 // relevance ordering (irrelevant here since the query is always empty).
-$result = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
+$products = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
 
-$result['data'];               // array of Meilisearch documents (plain arrays, not models)
-$result['meta']['total'];
-$result['meta']['per_page'];
-$result['meta']['current_page'];
-$result['meta']['last_page'];
+$products->items();            // array of Meilisearch documents (plain arrays, not models)
+$products->total();
+$products->perPage();
+$products->currentPage();
+$products->lastPage();
+$products->links();            // in a Blade view — renders pagination links as usual
 
 // Single product, by primary key
 $product = $service->getById(367);   // array, or null if not found
@@ -79,9 +82,8 @@ needs, listing and detail alike:
 | `variants` | `$product->variants` | Per variant: `id`, `sku`, `stock`, `purchasable`, `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (variant-specific images). |
 | `reviews`, `review_count`, `average_rating` | `Modules\Core\Review\Models\ProductReview` | See "Reviews" below. |
 
-`description` and other translated attributes are indexed as-is, including any HTML markup
-(e.g. from a Shopify `Body (HTML)` import) — **not stripped**. Any view rendering a description
-sourced from `ProductService`'s results must treat it as trusted HTML.
+`name`/`description` (and any other `TranslatedText` attribute) are indexed per-locale — see
+"Locale resolution" below for how `ProductService` resolves them down to one value per request.
 
 **`ProductOption`/`ProductOptionValue` names need a different translation accessor.** Unlike
 `Product`/`Collection`/`Brand`, their `name` is a plain locale-keyed array cast, not
@@ -90,6 +92,33 @@ indexer's `translatedName()` reads the array directly instead. See `docs/lunar.m
 
 ---
 
+## Locale resolution: `name`, `description`, and any other translated attribute
+
+Lunar's base `ScoutIndexer` explodes every `TranslatedText` attribute into one `{handle}_{locale}`
+field per store language at index time (`name_el`, `name_en`, `description_el`, ... — and the same
+for any custom translated attribute a store adds, e.g. `seo_title`/`seo_description`). Every raw
+document in Meilisearch carries all of them side by side, since a document is written once but
+read across many different-locale requests.
+
+`ProductService` resolves these back down to a single value per request. For every result it
+returns (`list()`'s items, `getById()`, `getBySlug()`), it:
+
+1. Reads which `Product` attributes are `TranslatedText` from `Lunar\Base\AttributeManifest` — the
+   same source Lunar's own indexer reads — rather than a hardcoded `['name', 'description']` list,
+   so a store's own custom translated attributes are picked up automatically with no change here.
+2. For each one, resolves `{handle}_{currentLocale}`, falling back to `{handle}_{storeDefaultLocale}`
+   (`LanguageCache::defaultLocale()`) if the current locale has no translation — e.g. a product with
+   no English copy yet still shows its Greek name on `/en/` rather than rendering blank.
+3. Assigns the result to a plain `{handle}` key and **strips every raw `{handle}_{locale}` key** —
+   callers only ever see `$product['name']`/`$product['seo_title']`/etc., never the per-locale
+   fields the index actually stores.
+
+`description` and other translated attributes are otherwise indexed as-is, including any HTML
+markup (e.g. from a Shopify `Body (HTML)` import) — **not stripped**. Any view rendering a
+description sourced from `ProductService`'s results must treat it as trusted HTML.
+
+---
+
 ## Reviews
 
 `Modules\Core\Review\Models\ProductReview` (`product_reviews` table) is indexed per-product as