@spree/docs 0.1.295 → 0.1.297

package/dist/developer/cli/quickstart.md

@@ -76,14 +76,6 @@ spree restart
 
 Not appropriate for Gemfile changes (use `spree bundle install`, then Ctrl+C and re-run `spree dev`), Dockerfile / `.ruby-version` changes (use `spree build`), or compose file changes (Ctrl+C and re-run `spree dev`).
 
-### `spree update`
-
-Pull the latest Spree Docker image and recreate containers. Migrations run automatically on startup.
-
-```bash
-spree update
-```
-
 ### `spree build`
 
 Rebuild the dev image after Dockerfile or `.ruby-version` changes. Only relevant after `spree eject`.
@@ -100,17 +92,27 @@ spree build --yes            # Skip confirmation prompts (for CI)
 
 ### `spree upgrade`
 
-Walk a Spree version upgrade end-to-end inside the dev stack. Runs `bundle update`, applies pending migrations, then walks the version-specific data backfills from the upgrade manifest.
+Upgrade your project to the latest Spree release in one go. It works for both kinds of project:
+
+1. **Update the server**
+   - On a project that runs the prebuilt image, it pulls the latest Spree image and recreates the containers. Database migrations run as the containers start.
+   - On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`, applies pending migrations, and restarts the app so it loads the new gems.
+2. **Run data backfills** — the version-specific steps from the upgrade manifest that convert existing records.
+3. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and Admin SDK in `apps/dashboard` and `apps/seller-dashboard`. Each package moves to the newest release its declared range in `package.json` allows, the same way `bundle update` respects your `Gemfile`. To move to a new major version, change the range in `package.json` first.
 
 ```bash
-spree upgrade                  # Detect target, run the full sequence interactively
-spree upgrade --plan           # Print the plan without executing (DRY_RUN=1)
-spree upgrade --to 5.5         # Cap the walk at a specific target version
-spree upgrade --step <id>      # Re-run a single step idempotently (skips bundle + migrate)
-spree upgrade --yes            # Skip the per-step prompts
+spree upgrade                  # Run every step, asking before each one
+spree upgrade --plan           # List the data backfills without running anything
+spree upgrade --to 6.1         # Set the target version for the data backfills
+spree upgrade --step <id>      # Re-run a single data backfill (runs nothing else)
+spree upgrade --yes            # Skip the prompts
 ```
 
-Production upgrades only need the third stage — `bundle install` and `db:migrate` happen in your deploy pipeline. The CLI runs all three for local development. See [Upgrades](../upgrades.md) for the manual production path.
+Your storefront is your own code, so `spree upgrade` does not change it — it tells you which `@spree/sdk` version to move to.
+
+Production upgrades only need the data backfills — installing gems and migrating happen in your deploy pipeline. See [Upgrades](../upgrades.md) for the manual production path.
+
+> **NOTE:** `spree update` is the old name for this command. It still works, prints a deprecation warning, and will be removed in a future release.
 
 ### `spree eject`
 
@@ -204,7 +206,7 @@ spree encryption init            # Add ACTIVE_RECORD_ENCRYPTION_* keys to the pr
 spree encryption init --print    # Print a fresh set without writing anything (e.g. for your hosting provider)
 ```
 
-It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment), and back the keys up in your secret manager.
+It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree dev` — `spree restart` keeps the old environment), and back the keys up in your secret manager.
 
 ### `spree api`
 

package/dist/developer/core-concepts/translations.md

@@ -116,21 +116,42 @@ Asking the API which resources are translatable means a translation tool doesn't
 
 ## Translating the interface
 
-Spree's own strings — everything in the dashboard and in transactional emails — come from a community-maintained project covering 40+ languages.
+Spree's own text — transactional emails, API error messages and validation messages — ships translated into 43 languages besides English as part of Spree itself. There is nothing to install. A key that a language does not translate yet is shown in English.
 
+The admin dashboard carries its own translations, separate from these. See [Dashboard translations](../dashboard/customization/translations.md).
 
-```bash Spree CLI
-spree bundle add spree_i18n
+Regional variants such as `de-CH` or `pt-BR` hold only what differs from their base language and fall back to it. Regional English (`en-GB` and the like) falls back to `en`.
+
+### Using fewer languages
+
+Loading every language costs startup time and memory. An app that serves only some languages can list them, and Spree then loads only those, plus English:
+
+```ruby server/config/application.rb
+config.i18n.available_locales = [:en, :de, :fr]
 ```
 
-```bash Bundler
-bundle add spree_i18n
+### Changing a translation
+
+> **TIP:** To change what a customer email says, edit it in the dashboard under **Settings → Emails → Templates** instead. Edits apply per store and per language, and need no deploy. See [Templates merchants edit in the dashboard](../customization/emails.md#templates-merchants-edit-in-the-dashboard) and the [Emails user guide](/user/settings/emails).
+
+Locale files are for the text the dashboard does not edit: API error messages, checkout requirements, validation messages and staff emails. To change a word or add a language, add the key to a locale file in your app. Your file wins over the one Spree ships.
+
+```yaml server/config/locales/de.yml
+de:
+  spree:
+    checkout_requirements:
+      email_required: Bitte geben Sie Ihre E-Mail-Adresse ein
 ```
 
+Every key lives under `spree`. To read one from your own Ruby code, use its full key:
+
+```ruby server/app/services/my_app/checkout_check.rb
+I18n.t('spree.checkout_requirements.email_required')
+```
 
-That's the whole installation. Locales are picked up automatically; nothing needs copying into your app.
+> **INFO:** `Spree.t` still works in 6.0 but is deprecated and will be removed in 6.1. Use `I18n.t` with the full `spree.` key instead.
 
-> **INFO:** See the [supported locales](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales) in the Spree I18n repository. Contributions are welcome if yours is incomplete.
+Corrections to the translations Spree ships are welcome as pull requests to the locale files in the [Spree repository](https://github.com/spree/spree/tree/main/spree/core/config/locales).
 
 ## Related
 

package/dist/developer/create-spree-app/quickstart.md

@@ -111,7 +111,7 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 |---------|-------------|
 | `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin Dashboard dev server when `apps/dashboard` exists |
 | `spree stop` | Stop backend services |
-| `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
+| `spree upgrade` | Upgrade Spree — the server, database and `@spree/*` packages |
 | `spree eject` | Switch from prebuilt image to building from `server/` |
 | `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
 | `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
@@ -148,10 +148,10 @@ Open [http://localhost:3001](http://localhost:3001) to see your store.
 To update to the latest Spree version:
 
 ```bash
-spree update
+spree upgrade
 ```
 
-This pulls the latest Docker image and recreates the containers. The entrypoint automatically runs database migrations.
+This updates the server (the Docker image, or the Spree gems on an ejected project), runs database migrations and data backfills, and updates the `@spree/*` packages of the project and its dashboard apps. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for details.
 
 To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
 

package/dist/developer/customization/checkout.md

@@ -53,7 +53,7 @@ that doesn't apply never appears at all:
 applicable: ->(cart) { cart.customer&.company.present? }
 ```
 
-`message` is stored verbatim — wrap it in `Spree.t` yourself if it needs translating.
+`message` is stored verbatim — wrap it in `I18n.t` yourself if it needs translating.
 
 ## Adding a step
 

package/dist/developer/how-to/custom-api-authentication.md

@@ -76,7 +76,7 @@ module MyApp
 
       def authenticate
         token = params[:token] || extract_bearer
-        return failure(Spree.t('api.unauthorized')) if token.blank?
+        return failure(I18n.t('spree.api.unauthorized')) if token.blank?
 
         payload = verify_with_jwks(token)
 
@@ -92,7 +92,7 @@ module MyApp
 
         success(user)
       rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIssuerError, JWT::InvalidAudError, KeyError => e
-        failure(Spree.t('api.unauthorized'))
+        failure(I18n.t('spree.api.unauthorized'))
       end
 
       private

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -226,7 +226,7 @@ bin/rails db:encryption:init    # prints a set; put it in env vars or encrypted
 ```
 
 
-Recreate the containers so they pick up the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
+Recreate the containers so they pick up the new `.env` (`spree dev` — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
 
 > **WARNING:** Never change or lose the keys once data is encrypted — the encrypted records become unreadable.
 
@@ -296,7 +296,7 @@ Spree::Checkout::Registry.add_requirement(
 
   The requirement appears in the Cart API's `requirements` array (so a storefront rendering the feed generically needs zero changes) *and* blocks completion. `register_step` adds whole steps (spliced into `checkout_steps` at `before:`/`after:` anchors); built-in steps are customized through `Registry.base_steps` — an ordered `{ name => applicability }` hash you can mutate directly (`base_steps.delete('confirm')`).
 - **The API `requirements` array now carries a stable `code`** on every entry (`email_required`, `out_of_stock`, `guest_checkout_not_allowed`, ...). Additive change — existing consumers keep working.
-- **The delivery requirement is keyed `delivery_method`, not `shipping_method`.** Its entry is now `{ step: 'delivery', field: 'delivery_method', code: 'delivery_method_required' }`. A storefront that renders the feed generically needs no change; one that keys off the field or code to highlight a specific input must switch both tokens. The `Spree.t('checkout_requirements.shipping_method_required')` translation key was renamed to `checkout_requirements.delivery_method_required` — override it under the new key.
+- **The delivery requirement is keyed `delivery_method`, not `shipping_method`.** Its entry is now `{ step: 'delivery', field: 'delivery_method', code: 'delivery_method_required' }`. A storefront that renders the feed generically needs no change; one that keys off the field or code to highlight a specific input must switch both tokens. The `spree.checkout_requirements.shipping_method_required` translation key was renamed to `spree.checkout_requirements.delivery_method_required` — override it under the new key.
 - **"Logic between steps" has no backend home by design.** Side effects hang off data writes (workflow hooks such as `Carts::Complete`'s `before_finalize` and `Carts::AddItem`'s `after_item_added`) and events (`cart.updated`, `order.placed`) — not step transitions.
 
 ## Statuses: derived, then persisted
@@ -779,6 +779,18 @@ Other changes that come with it:
 - **Alba moved into `spree_core`**, with its configuration, so core's staff emails render in installations without `spree_api`.
 - **Your own mailers keep working.** A mailer that inherits `Spree::BaseMailer` and calls `mail` with its own ERB views is wrapped in the new email layout, and the `spree/shared/mailer_hero` and `mailer_button` partials remain for its views. See [Your own mailers](../customization/emails.md#your-own-mailers).
 
+## Translations ship with Spree
+
+Spree's translations for emails, API messages and validation messages are now part of Spree itself, in 43 languages besides English. Regional English (`en-GB` and the like) now falls back to `en`. A key a language does not translate yet falls back to English, unless your app configured its own `config.i18n.fallbacks`. See [Translations](../core-concepts/translations.md#translating-the-interface).
+
+- **Remove `spree_i18n` from your Gemfile.** Its last release is empty and only warns. Older releases load their own, larger files over Spree's.
+- **Use `I18n.t` with the full key.** `Spree.t(:free)` becomes `I18n.t('spree.free')`, and `Spree.t(:x, scope: :api)` becomes `I18n.t('spree.api.x')`. `Spree.t` keeps working until 6.1 with a deprecation warning.
+- **A missing key is plain text.** `Spree.t` used to return a `<span class="translation_missing">` HTML element for a key it could not find. It now returns what `I18n.t` returns.
+- **Untranslated keys fall back to English.** Spree's translations are complete only in English. With `config.i18n.fallbacks = true`, as Rails generates for production, Spree adds English after your default locale. An app that sets its own fallback list or turns fallbacks off keeps its choice.
+- **`spree/testing_support/i18n` does nothing.** Set `config.i18n.raise_on_missing_translations = true` in your test environment to catch missing keys.
+- **Kaminari is no longer loaded.** It came in through `spree_i18n`. Spree paginates with Pagy, and the `Spree::Base.page` bridge for a custom Kaminari `page_method_name` is gone. Add `kaminari` to your Gemfile if your own code uses it.
+- **Translations for removed screens are gone.** Keys used only by the old admin and storefront, and by the v2 API, were removed. If your code reads one, copy it into your app's locale files.
+
 ## Deprecated in 6.0, removed in 6.1
 
 Every rename keeps the legacy name working for one release with a deprecation warning. The notable ones:
@@ -825,6 +837,7 @@ Before 6.0 a cart was an incomplete order, so extensions written for 5.x (paymen
 | `metafields` / `public_metafields` associations | `custom_fields` / `storefront_custom_fields` |
 | `.with_metafield_key`, `.with_metafield_key_value` | `.with_custom_field_key`, `.with_custom_field_key_value` |
 | `Spree.metafields` | `Spree.custom_fields` |
+| `Spree.t`, `Spree.translate` | `I18n.t` with the full key, e.g. `I18n.t('spree.free')` |
 | `CustomFieldDefinition#name`, `#metafield_type`, `#display_on` | `#label`, `#field_type`, `#storefront_visible` (columns renamed) |
 | `Spree::SearchProvider::Meilisearch` | `SpreeMeilisearch::SearchProvider` (moved to the `spree_meilisearch` gem) |
 | `Spree::SearchProvider::ProductPresenter` | `SpreeMeilisearch::ProductPresenter` (moved to the `spree_meilisearch` gem) |

package/dist/developer/upgrades/quickstart.md

@@ -9,6 +9,38 @@ The upgrade process is fairly easy and well described. Of course, it all boils d
 
 We strongly advise upgrading Spree incrementally, rather than in one big go.
 
+## How to upgrade
+
+An upgrade updates the server, migrates the database, runs the version's data backfills, and updates the `@spree/*` packages of your dashboard apps. Always read the guide for the version you're moving to first — it lists the behavior changes to review.
+
+**Spree CLI:**
+
+```bash
+    spree upgrade
+    ```
+
+    One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](../cli/quickstart.md#spree-eject) project, then runs migrations, data backfills and the package updates. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for its options.
+
+  **Without CLI:**
+
+Run from the project root:
+
+    ```bash
+    cd server
+    bundle update $(bundle list --name-only | grep ^spree)
+    bin/rails spree:install:migrations db:migrate
+    bin/rails spree:upgrade
+    cd ..
+
+    # The project root and each dashboard app have their own package.json
+    pnpm update "@spree/*"
+    (cd apps/dashboard && pnpm update "@spree/*")
+    (cd apps/seller-dashboard && pnpm update "@spree/*")
+    ```
+
+    On npm or Yarn, run `npm update` or `yarn upgrade` instead, naming each `@spree/*` package from that `package.json` (they do not accept the `"@spree/*"` pattern).
+
+
 ## Support
 
 If you're stuck and would want to get some professional help, you can [contact us directly](https://spreecommerce.org/contact/) and request a quote for our consulting services.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.295",
+  "version": "0.1.297",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",