@spree/docs 0.1.296 → 0.1.297

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/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

@@ -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/package.json

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