[create-pull-request] automated change

Author: shopwareBot

resources/references/adr/2025-08-19-cache-layer-for-navigation-loader.md

@@ -0,0 +1,40 @@
+---
+title: Cache layer for navigation loader
+date: 2025-08-19
+area: framework & discovery
+tags: [performance, cache, categories]
+---
+
+# Cache layer for navigation loader
+
+::: info
+This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
+You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-08-19-cache-layer-for-navigation-loader.md)
+:::
+
+## Context
+We see in multiple performance analysis that the navigation loader can be a bottleneck for the performance of the storefront, especially with a huge number of categories in the first levels of the category tree.
+The navigation loader is responsible for loading the categories and their children, which are then used to render the navigation in the storefront. 
+This process can be quite expensive, not just because of the query time on the DB, but also for hydrating the entities into PHP objects.
+The other part with a huge performance impact is the rendering performance on twig side for the many nested categories, however that is not part of this ADR.
+
+The navigation loader is used in the storefront for every header and every listing page (when they use the sidebar navigation CMS element). 
+However, the data that is loaded is always the same for the same sales channel, because we always show/load the category tree for the main navigation of the sales channel to the depth that is configured in the sales channel config.
+
+Adding support for ESI for the header and footer addresses the same fundamental performance issue, however it does not solve the problem for the listing pages, where the sidebar navigation CMS element is used.
+Additionally, for ESI to be effective you would need a reverse proxy that supports ESI, and you need to disable compression your responses from your webserver, which could increase your infrastructure costs. So ESI is not a viable solution for every use case.
+
+## Decision
+We will implement a cache layer for the navigation loader to improve the performance of the storefront.
+To not only safe the query time, but also the hydration time, we will store the categories as PHP serialized objects. That should be fine, because when the structure of the PHP objects changes, that means there is a new platform version, in which case the cache needs to be cleared anyway.
+Also in order to be most effective and not store too much data, we will only cache the category tree for the main navigation for every sales channel and up to the depths that is configured in the sales channel, because that info is loaded on every header and every listing page (when they use the sidebar navigation CMS element).
+We use the `CacheCompressor` to compress the serialized data before storing it in the cache, which should reduce the size of the cache entries significantly, however it adds some more processing time when reading and writing the cache entries.
+
+This cache layer will work complementary to ESI, because ESI would also cache the rendered HTML of the navigation, the performance impact of ESI will be faster, but category information for the sidebar navigation is still loaded on every listing page, so this change is still beneficial in regard to performance, even when you use ESI.
+
+## Consequences
+* The loaded categories for the main navigation will be cached to the level defined in the sales channel config.
+* Additional categories that might be loaded because e.g. the currently active category is below the configured depth will be loaded dynamically per request and merged with the default categories.
+* The cache needs to be invalidated whenever a category is written or deleted. We use immediate cache invalidation for that, so that the behaviour is as before, even with deactivated HTTP-Cache.
+* We encode the information about the `salesChannelId`, `language`, `root category id` and `depth` in the cache key, so that we can cache the categories for different sales channels and languages.
+* We will add a `CategoryLevelLoaderCacheKeyEvent` so that plugins can modify the cache key if they dynamically influence which categories should be loaded/shown.

resources/references/adr/2025-09-01-adding-a-country-agnostic-language-layer.md

@@ -0,0 +1,103 @@
+---
+title: Adding a country-agnostic language layer
+date: 2025-09-01
+area: discovery
+tags: [administration, storefront, plugin, app, languages, language-pack, translations, crowdin]
+---
+
+# Adding a country-agnostic language layer
+
+::: info
+This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
+You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-09-01-adding-a-country-agnostic-language-layer.md)
+:::
+
+## Context
+Currently, Shopware’s language system uses a specific language locale (e.g. `de-DE` for German in Germany) for its translation, while falling back to another specific locale (e.g. `en-GB` for English in Great Britain).
+
+This works well, but it is quite maintenance-heavy. If you use multiple versions or dialects of a language, such as British and American English, it will result in a lot of duplicated snippets.
+
+### Some facts and figures
+- Shopware has approximately 12,000 snippets.
+- By default, the US translation is an automated copy of the GB translation, which is later adjusted by our community via Crowdin.
+- When running them through a comparison tool, we find about 70 differences. This means that roughly 99.5% of our American snippets are identical to the British ones.
+
+### Current structure
+
+```mermaid
+flowchart LR
+    subgraph "Specific language"
+        deDE("<strong>de-DE</strong><br/><em>German in Germany</em>")
+        deAT("<strong>de-AT</strong><br/><em>German in Austria</em>")
+        esES("<strong>es-ES</strong><br/><em>Spanish in Spain</em>")
+        esAR("<strong>es-AR</strong><br/><em>Spanish in Argentina</em>")
+        enUS("<strong>en-US</strong><br/><em>English in the USA</em>")
+    end
+    subgraph "System default language"
+        enGB("<strong>en-GB</strong><br/><em>English in Great Britain</em>")
+    end
+        
+    deDE-->enGB
+    deAT-->enGB
+
+    esES-->enGB
+    esAR-->enGB
+    
+    enUS-->enGB
+```
+
+## Decision
+Another layer containing a country-agnostic language (e.g., `en` for both `en-GB` and `en-US`) will provide an additional fallback layer. This means dialects are now treated as patch files. In Shopware, `en-GB` will be renamed to `en`, as you have to select a base dialect, retaining its 12,000 snippets, while `en-US` will shrink to around 70 snippets. This also eliminates the need for tools to initially copy-paste or pre-translate from "English to English," which, of course, incurs costs.
+
+## Consequences
+- Every additional dialect’s snippet file (e.g., `en-US` for `en`) will shrink from around 12,000 entries to likely fewer than 100.
+- We will also provide an additional layer to maximize compatibility with existing installations. This means that `en-GB` will still be available as a fallback for other languages like `de-DE`, but `en` will be the primary fallback for everything.
+- We will also provide an additional layer to ensure maximum compatibility with existing translations (e.g. via extensions). This means `en-GB` will remain available as a fallback for other languages such as `de-DE` and `de`, while `en` will serve as the final fallback.
+- Translations provided via the community (Crowdin) will show a lower coverage percentage, but will more accurately reflect the actual differences between `en-US` and `en`.
+- In Crowdin and in our product, the base language is set declaratively, so we will inform the community that British English is our base language, and we simply refer to it as `en`.
+- All snippet files in Shopware’s core will be renamed to the country-agnostic language
+    - `en-GB.json` -> `en.json`, `messages.en-GB.base.json` -> `messages.en.base.json` and so on.
+    - Similarly: `de-DE` -> `de`
+- The community translations / language pack will update their locales to their country-agnostic versions as well (e.g., `es-ES` -> `es`).
+- The system’s default language or active language handling will remain unchanged.
+- Plugins and apps do not require immediate adjustments, as the previous structure will continue to function as before as well.
+
+### New structure
+
+```mermaid
+flowchart LR
+    subgraph "Specific language (German)"
+        deDE("<strong>de-DE</strong><br/><em>German in Germany</em>")
+        deAT("<strong>de-AT</strong><br/><em>German in Austria</em>")
+        de("<strong>de</strong><br/><em>German</em>")
+    end
+    subgraph "Specific language (Spanish)"
+        esES("<strong>es-ES</strong><br/><em>Spanish in Spain</em>")
+        esAR("<strong>es-AR</strong><br/><em>Spanish in Argentina</em>")
+        es("<strong>es</strong><br/><em>Spanish</em>")
+    end
+        subgraph "Specific language (English)"
+        enUS("<strong>en-US</strong><br/><em>English in the USA</em>")
+    end
+    subgraph "Fallback (English)"
+        enGB("<strong>en-GB</strong><br/><em>English in Great Britain</em>")
+        en("<strong>en</strong><br/><em>English</em>")
+    end
+
+    deDE-->de
+    deAT-->de
+    de-->enGB
+
+    esES-->es
+    esAR-->es
+    es-->enGB
+
+    enUS-->en
+    enGB-->en
+
+    style de color:#6f6,stroke:#6f6
+    style es color:#6f6,stroke:#6f6
+    style en color:#6f6,stroke:#6f6
+    
+    style enGB stroke-dasharray: 5
+```