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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
[skip ci] documentation added internationalization section
Damian Legawiec535ef7320900
diff --git a/docs/developer/customization/i18n.mdx b/docs/developer/core-concepts/i18n.mdxsimilarity index 72%rename from docs/developer/customization/i18n.mdxrename to docs/developer/core-concepts/i18n.mdxindex cb7dfab6da..d2e187a07e 100644--- a/docs/developer/customization/i18n.mdx+++ b/docs/developer/core-concepts/i18n.mdx@@ -1,24 +1,33 @@---title: Internationalization-section: customizationorder: 8description: >-- This guide covers how Spree uses Rails' internationalization features, and how- you can leverage and extend these features in your Spree contributions and- extensions.+ Spree is ready out of the box to make your brand a global one.----## Default Locale+## Overview-Each [**Store**](/developer/core-concepts/stores) has their own `default_locale` attribute. Alongside that, you can also set `supported_locales` which will enable multi-language capabilities for that Store.+With Spree you can use different currencies, languages, payment methods per region. You can translate the UI and have different translations for product descriptions, taxons, etc to improve conversions and customer satisfaction.-For locales, we use symbols such as `en`,`es-MX` etc - full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/master/config/locales).+## Store Default Locale-## Default Currency+Each [Store](stores) has their own `default_locale` attribute. Alongside that, you can also set `supported_locales` which will enable multi-language capabilities for that Store.-Each [**Store**](/developer/core-concepts/stores) has their own `default_currency` attribute. Alongside that, you can also set `supported_currencies` which will enable multi-currency capabilities for that Store.+You can change both in the Admin Panel in `Configurations -> Store` or via rails console / API.+<Info>+For locales, we use symbols such as `en`,`es-MX` etc - full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/master/config/locales)..+</Info>++## Store Default Currency++As with locale each [Store](stores) has their own `default_currency` attribute. Alongside that, you can also set `supported_currencies` which will enable multi-currency capabilities for that Store.++You can change both in the Admin Panel in `Configurations -> Store` or via rails console / API.++<Info>For currencies, we use [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) symbols, eg. `USD` , `CAD`, `EUR`+</Info>## Resource Translations@@ -26,20 +35,24 @@ As of Spree 4.6, resources with user-facing content fields now have built in sup| Resource | Translatable Fields || ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Product | name, description, slug, meta_description, meta_keywords, meta_title |-| Taxon | name, description, permalink |-| Taxonomy | name |-| Option Type | name, presentation |-| Option Value | name, presentation |-| Property | name, presentation, filter_param |-| Product Property | value, filter_param |-| Store | name, meta_description, meta_keywords, seo_title, facebook, twitter, instagram, customer_support_email, description, address, contact_phone, new_order_notifications_email |+| Product | `name`, `description`, `slug`, `meta_description`, `meta_keywords`, `meta_title` |+| Taxon | `name`, `description`, `permalink` |+| Taxonomy | `name` |+| Option Type | `presentation` |+| Option Value | `presentation` |+| Property | `presentation` |+| Product Property | `value` |+| Store | `name`, `meta_description`, `meta_keywords`, `seo_title`, `facebook`, `twitter`, `instagram`, `customer_support_email`, `description`, `address`, `contact_phone` |Our translatable resources are configured with Mobility’s [Table Backend](https://github.com/shioyama/mobility#table-backend-like-globalize) storage strategy. The way this works is that each translatable resource has a corresponding translations table in the database, in which translation values are stored - for example, product translations are stored in `spree_product_translations`.-As of 4.6, data for translatable fields exists solely in the the translation tables so that there is a single source of truth. In the database, the translatable fields on the resource itself will always null. Even if there is only data for a single language, the data for those fields will be stored in the corresponding translations table. In the code, the data will still be accessible via attribute accessors like `.name` and `.description` in the code.\-\-Read more about how to work with translations by reading [Mobility's usage docs](https://github.com/shioyama/mobility#usage).+<Note>+As of 4.6, data for translatable fields exists solely in the the translation tables so that there is a single source of truth. In the database, the translatable fields on the resource itself will always null. Even if there is only data for a single language, the data for those fields will be stored in the corresponding translations table. In the code, the data will still be accessible via attribute accessors like `.name` and `.description` in the code.+</Note>++<Info>+You can read more about how to work with translations by reading [Mobility's usage docs](https://github.com/shioyama/mobility#usage).+</Info>### Resource Translations Implementation@@ -50,7 +63,7 @@ Due to some shortcomings of the Mobility gem, not all Active Record Query Interf* selecting `distinct` when ordering by a translated field raises an error. To work around this, explicitly select the translated field that you are ordering by. For example, instead of `Spree::Product.order(:name).distinct` do `Spree::Product.select(:name).order(:name).distinct`* calling `first_or_create` or `first_or_initialize` on a clause that checks for a translated field does not work correctly with Mobility. For example, the following line of code will not perform as expected: `Spree::Product.where(name: ‘Denim Shirt').first_or_create!` Instead, you’ll need to rewrite it as an if statement that calls either `first` or `create` like so:-```+```rubyif Spree::Product.where(name: 'Denim Shirt').any?Spree::Product.where(name: 'Denim Shirt').firstelse@@ -60,27 +73,17 @@ end* Joining on a resource with translations and then filtering by a translated field on the resource that you joined does not work correctly. For example, the following statement will not select the correct products: `Spree::Product.joins(:taxons).where(taxons: {name: "30% Off"})`. Instead, you can make use of the `join_translation_table` method in in the `TranslatableResourceScopes` Module. The above query can be rewritten like this:-```+```rubySpree::Product.joins(:taxons).joins_translation_table(Spree::Taxon).where(Spree::Taxon.translation_table_alias => {name: "30% Off"})```-### Spree 4.5 and lower--If you are using Spree version 4.5 or lower and are currently unable to upgrade, you need to install [Spree Globalize extension](https://github.com/spree-contrib/spree_globalize) to enable translations. This extension uses [Globalize](https://github.com/globalize/globalize) library under the hood.+<Info>+ If you are using Spree version 4.5 or order and are currently unable to upgrade, you can install [Spree Globalize extension](https://github.com/spree-contrib/spree_globalize) to enable translations. This extension uses [Globalize](https://github.com/globalize/globalize) library under the hood. We do not recommend this approach and we will not be providing support for it. We recommend upgrading to the Spree 4.6 or newer.+</Info>-This gem will allow you to translate:--* Products-* Promotions-* Option Types-* Taxonomies-* Taxons-* Properties-* Shipping Methods--## The spree_i18n project+## The `spree_i18n` projectSpree now stores all of the translation information in a separate GitHub project known as [Spree I18n](https://github.com/spree/spree_i18n). This is a stand alone project with a large number of volunteer committers who maintain the locale files. This is basically the same approach followed by the Rails project which keeps their localizations in [rails-i18n](https://github.com/svenfuchs/rails-i18n).@@ -105,7 +108,7 @@ Please submit Pull Requests or issues directly to [Spree I18n](https://github.coSpree maintains its localization information in a YAML file using a naming convention similar to that of the Rails project. Each of the localization filenames contains a prefix representing the language code of the locale. For example, the Russian translation is contained in `config/locales/ru.yml`.-Spree has over 43 locale files and counting. See the \[GitHub Repository]\(https://github.com/spree/spree_i18n/tree/master/config/locales) for a complete list.+Spree has over 43 locale files and counting. See the [GitHub Repository](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales) for a complete list.### Required Files@@ -121,11 +124,11 @@ This section is only applicable for optional`spree_frontend` and `spree_backendWhen reviewing the source of any view in Spree you'll notice that all text is rendered by passing a string to a helper method similar to:-```+```erb<%= Spree.t(:price) %>```-The _Spree.t()_ helper method looks up the currently configured locale and retrieves the translated value from the relevant locale YAML file. Assuming a default locale, this translation would be fetched from the en translations collated from the application, `spree_i18n` and `rails-i18n`. Its relative key within those translation files would need to be this:+The `Spree.t()` helper method looks up the currently configured locale and retrieves the translated value from the relevant locale YAML file. Assuming a default locale, this translation would be fetched from the en translations collated from the application, `spree_i18n` and `rails-i18n`. Its relative key within those translation files would need to be this:```yamlen:@@ -135,6 +138,6 @@ en:## Localizing Extensions-Spree extensions can contain their own `config/locales` directory where developers can include YAML files for each language they wish to support.+[Spree extensions](/developer/extending-spree/3rd-party-extensions) can contain their own `config/locales` directory where developers can include YAML files for each language they wish to support.We strongly urge all extension developers to ensure all customer facing text is rendered via the `Spree.t()` helper method even if they only include a single default language locale file (as other users can simply include the required YAML file and translations in their site extension).diff --git a/docs/mint.json b/docs/mint.jsonindex 3047f7a9db..8115d8494d 100644--- a/docs/mint.json+++ b/docs/mint.json@@ -88,7 +88,8 @@"developer/core-concepts/taxes","developer/core-concepts/promotions","developer/core-concepts/shipments",- "developer/core-concepts/addresses"+ "developer/core-concepts/addresses",+ "developer/core-concepts/i18n"]},