Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added plan for metafield translations

Damian Legawiece79ad5d16ec2
diff --git a/CLAUDE.md b/CLAUDE.md
index bb5b569925..fc698b1bf8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,6 +36,7 @@ Current plans:
- `5.4-option-type-enhancements.md` — Add `kind` (dropdown/color_swatch/buttons) to OptionType, `color_code` + `image` to OptionValue for swatch support
- `5.4-6.0-custom-fields-rename.md` — Rename Metafields → Custom Fields (5.4 API bridge + 6.0 model rename)
- `5.4-centralized-translations-admin.md` — Centralized Translations admin page under Products, overview grid + bulk CSV import/export
+- `5.4-metafield-translations.md` — Translate MetafieldDefinition names + Metafield text values (ShortText, LongText, RichText) via Mobility translation tables
Completed plans:
- `5.4-store-api-bridges.md` — Bridge 6.0 naming into 5.4 Store API (implemented, PR #13782)
diff --git a/docs/plans/5.4-metafield-translations.md b/docs/plans/5.4-metafield-translations.md
new file mode 100644
index 0000000000..dd7be407fa
--- /dev/null
+++ b/docs/plans/5.4-metafield-translations.md
@@ -0,0 +1,341 @@
+# Metafield & MetafieldDefinition Translations
+
+**Status:** Draft
+**Target:** Spree 5.4
+**Depends on:** Metafields system (shipped), TranslatableResource / Mobility infrastructure
+**Author:** Damian
+**Last updated:** 2026-04-08
+
+## Summary
+
+Metafields and MetafieldDefinitions do not support translations. Products, Options, and Categories are translatable via Mobility, but custom field values and definition labels are locale-unaware. This plan adds translation support for MetafieldDefinition names (admin labels) and Metafield values (text types only), using Spree's existing Mobility + per-entity translation table pattern.
+
+## Key Decisions (do not deviate without discussion)
+
+- **Only text-like metafield types are translatable** — ShortText, LongText, RichText. Number, Boolean, and Json are NOT translatable. This matches industry consensus (Shopify, Saleor, Vendure all do the same).
+- **No separate locale types** — We do NOT introduce `LocaleShortText` / `LocaleLongText` (Vendure-style). Instead, all text types gain translation support automatically. Mobility's `column_fallback` handles "no translation available, use base value" gracefully.
+- **MetafieldDefinition `name` is translatable** — The admin-facing label for a custom field definition needs translation for multi-language admin UIs.
+- **RichText translations stored as HTML in text column** — Not ActionText. Aligns with `6.0-rich-text-descriptions.md` plan to drop ActionText storage. Translated rich text goes in `spree_metafield_translations.value` as HTML.
+- **Single translation table for all metafield values** — One `spree_metafield_translations` table serves all STI types, consistent with how the base `spree_metafields` table works.
+- **`translatable?` method on Metafield** — Each STI subclass declares whether it supports translations. Controllers and serializers use this to decide behavior.
+
+## Design Details
+
+### Models
+
+#### MetafieldDefinition — Translatable `name`
+
+```ruby
+class Spree::MetafieldDefinition < Spree.base_class
+ include Spree::TranslatableResource
+
+ TRANSLATABLE_FIELDS = %i[name].freeze
+ translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
+end
+```
+
+#### Metafield — Translatable `value` (text types only)
+
+```ruby
+class Spree::Metafield < Spree.base_class
+ include Spree::TranslatableResource
+
+ TRANSLATABLE_FIELDS = %i[value].freeze
+ translates(*TRANSLATABLE_FIELDS, column_fallback: true)
+ # column_fallback: true always — base value is the default-locale value
+
+ # Override in subclasses
+ def translatable?
+ false
+ end
+end
+```
+
+#### STI Subclass Overrides
+
+```ruby
+module Spree::Metafields
+ class ShortText < Spree::Metafield
+ def translatable?
+ true
+ end
+ end
+
+ class LongText < Spree::Metafield
+ def translatable?
+ true
+ end
+ end
+
+ class RichText < Spree::Metafield
+ def translatable?
+ true
+ end
+
+ # For translations, store HTML directly in the translation table's
+ # value column — do NOT use ActionText for translated values.
+ # The base (default locale) value continues to use ActionText
+ # until the 6.0 ActionText removal.
+ end
+end
+```
+
+Non-text types (`Number`, `Boolean`, `Json`) inherit the default `translatable? # => false` and never touch the translation table.
+
+### Translation Tables
+
+#### spree_metafield_translations
+
+| Column | Type | Constraints |
+|---|---|---|
+| `id` | bigint | PK |
+| `spree_metafield_id` | references | not null |
+| `locale` | string | not null |
+| `value` | text | |
+| `created_at` | datetime | |
+| `updated_at` | datetime | |
+
+Unique index: `[spree_metafield_id, locale]`
+
+#### spree_metafield_definition_translations
+
+| Column | Type | Constraints |
+|---|---|---|
+| `id` | bigint | PK |
+| `spree_metafield_definition_id` | references | not null |
+| `locale` | string | not null |
+| `name` | string | |
+| `created_at` | datetime | |
+| `updated_at` | datetime | |
+
+Unique index: `[spree_metafield_definition_id, locale]`
+
+### Mobility Behavior
+
+- **column_fallback** ensures that when no translation exists for the requested locale, the base column value is returned. This is critical — metafield values written before translations were enabled continue to work.
+- **store_based_fallbacks** (Spree's custom Mobility plugin) provides per-store fallback chains. A French store might fall back `fr → en`, a German store `de → en`.
+- For non-translatable types, reads bypass the translation table entirely via `translatable?` check. The Mobility `translates` declaration on the base class only activates the join/lookup when the type supports it.
+
+### API Changes
+
+#### Store API (read-only, locale-aware)
+
+Custom fields are already serialized via `CustomFieldSerializer`. The current locale (from `x-spree-locale` header / `Spree::Current.locale`) determines which translation is returned. No API shape change needed — the `value` field simply returns the translated value for text types.
+
+```json
+{
+ "custom_fields": [
+ {
+ "key": "specs.care_instructions",
+ "name": "Entretien",
+ "type": "short_text",
+ "value": "Lavage a 30C"
+ },
+ {
+ "key": "specs.weight_grams",
+ "name": "Poids",
+ "type": "number",
+ "value": 250
+ }
+ ]
+}
+```
+
+Definition `name` is also translated via Mobility (the definition's `name` method already delegates through Mobility once we add the concern).
+
+#### Admin API — Translation management
+
+Admin serializers expose a `translatable` flag and `translations` hash for managing translations across locales:
+
+**Read (GET):**
+
+```json
+{
+ "key": "specs.care_instructions",
+ "name": "Care Instructions",
+ "type": "short_text",
+ "value": "Machine wash at 30C",
+ "translatable": true,
+ "translations": {
+ "fr": { "value": "Lavage a 30C" },
+ "de": { "value": "Maschinenwaesche bei 30C" }
+ }
+}
+```
+
+Non-translatable types omit `translations` or return an empty object:
+
+```json
+{
+ "key": "specs.weight_grams",
+ "name": "Weight (grams)",
+ "type": "number",
+ "value": 250,
+ "translatable": false
+}
+```
+
+**Write (PATCH):**
+
+```json
+{
+ "translations": {
+ "fr": { "value": "Lavage a 30C" }
+ }
+}
+```
+
+#### MetafieldDefinition Admin API — Name translations
+
+```json
+{
+ "namespace": "specs",
+ "key": "care_instructions",
+ "name": "Care Instructions",
+ "name_translations": {
+ "fr": "Entretien",
+ "de": "Pflegehinweise"
+ }
+}
+```
+
+### Serializer Changes
+
+#### Store CustomFieldSerializer
+
+```ruby
+module Spree::Api::V3
+ class CustomFieldSerializer < BaseSerializer
+ # value already reads from Mobility (current locale with fallback)
+ # name already reads from definition (which is now translatable)
+ # No changes needed — Mobility handles locale resolution transparently
+ end
+end
+```
+
+#### Admin CustomFieldSerializer
+
+```ruby
+module Spree::Api::V3::Admin
+ class CustomFieldSerializer < V3::CustomFieldSerializer
+ typelize translatable: :boolean
+
+ attribute :translatable do |metafield|
+ metafield.translatable?
+ end
+
+ attribute :translations do |metafield|
+ next {} unless metafield.translatable?
+
+ metafield.translations.each_with_object({}) do |translation, hash|
+ hash[translation.locale] = { value: translation.value }
+ end
+ end
+ end
+end
+```
+
+### RichText Translation Details
+
+The base (default locale) RichText value continues to use ActionText via `has_rich_text`. Translated values for non-default locales are stored as HTML strings in `spree_metafield_translations.value`.
+
+When reading a RichText metafield:
+- **Default locale:** ActionText `body.to_s` (existing behavior)
+- **Other locales:** HTML string from the translation table
+
+When writing a RichText translation:
+- Accept HTML string, sanitize on write (same sanitization rules as the base value)
+- Store sanitized HTML in the translation table's `value` column
+
+This asymmetry is temporary — the `6.0-rich-text-descriptions.md` plan will move all rich text to plain HTML columns, at which point RichText metafields will be fully symmetric.
+
+### Translation Coverage Tracking
+
+Extend the existing `ProductTranslationsController` pattern to include metafield translation coverage:
+- Track which metafields have translations per locale
+- Surface in admin UI alongside product/taxon translation coverage
+- Include in the centralized translations admin page (per `5.4-centralized-translations-admin.md` plan)
+
+## Migration Path
+
+### Step 1: Migration
+
+```ruby
+class CreateSpreeMetafieldTranslations < ActiveRecord::Migration[7.2]
+ def change
+ create_table :spree_metafield_translations do |t|
+ t.references :spree_metafield, null: false
+ t.string :locale, null: false
+ t.text :value
+
+ t.timestamps
+ end
+
+ add_index :spree_metafield_translations,
+ [:spree_metafield_id, :locale],
+ unique: true,
+ name: 'index_spree_metafield_translations_uniqueness'
+
+ create_table :spree_metafield_definition_translations do |t|
+ t.references :spree_metafield_definition, null: false
+ t.string :locale, null: false
+ t.string :name
+
+ t.timestamps
+ end
+
+ add_index :spree_metafield_definition_translations,
+ [:spree_metafield_definition_id, :locale],
+ unique: true,
+ name: 'index_spree_mf_def_translations_uniqueness'
+ end
+end
+```
+
+### Step 2: Model changes
+
+1. Add `TranslatableResource` to `MetafieldDefinition` with `translates :name`
+2. Add `TranslatableResource` to `Metafield` with `translates :value, column_fallback: true`
+3. Add `translatable?` method to base `Metafield` (returns `false`)
+4. Override `translatable?` in `ShortText`, `LongText`, `RichText` (returns `true`)
+
+### Step 3: Serializer changes
+
+1. Update Admin `CustomFieldSerializer` to include `translatable` and `translations`
+2. Update Admin `MetafieldDefinitionSerializer` to include `name_translations`
+3. Store API serializers need no changes (Mobility handles locale resolution)
+
+### Step 4: Controller changes
+
+1. Add translation params to Admin metafield update endpoints
+2. Support `translations` hash in permitted params for text-type metafields
+3. Support `name_translations` hash in permitted params for definitions
+
+### Step 5: Tests
+
+1. Model specs: translation read/write for each text type, verify non-text types ignore translations
+2. Serializer specs: verify `translatable` flag and `translations` hash
+3. API integration specs: round-trip translation CRUD
+4. Fallback specs: verify column_fallback and store_based_fallbacks work correctly
+
+## Constraints on Current Work
+
+- **Do not add locale-specific metafield types** (no `LocaleShortText` etc.). The `translatable?` method on existing types is the mechanism.
+- **Do not store translated rich text in ActionText.** Use plain HTML in the translation table.
+- **Do not translate Number, Boolean, or Json metafield values.** If a use case emerges for translatable JSON (e.g. structured locale content), it should be a separate proposal.
+- **When adding new metafield types**, always implement `translatable?` — default to `false` unless the type is text-based.
+
+## Open Questions
+
+1. **Should `description` be added to MetafieldDefinition?** Currently definitions only have `name`. A translatable `description` field could help merchants understand what each custom field is for. Low priority but worth considering.
+2. **Bulk translation import/export for metafields** — Should this integrate with the centralized translations admin CSV import/export (per `5.4-centralized-translations-admin.md`), or be a separate flow?
+3. **Metafield translation via Product translation UI** — When translating a product, should its translatable metafield values appear inline, or require navigating to a separate custom fields translation view?
+
+## References
+
+- `6.0-rich-text-descriptions.md` — ActionText removal plan (affects RichText metafield storage)
+- `5.4-centralized-translations-admin.md` — Centralized translations admin page
+- `5.4-6.0-custom-fields-rename.md` — Metafields → Custom Fields rename
+- Shopify Translations API — metafield as translatable resource, text types only
+- Saleor AttributeTranslation — per-entity translation tables, attribute name + value translation
+- Vendure `localeString`/`localeText` — type-level translation decision, column on translation table