docs: document translation system extension points - #2395
Merged
Conversation
Add a dedicated 'Extension points' page under concepts/framework/translations that catalogs every way developers and hosts can customize the translation and snippet system: the shopware.translation configuration override, shipping snippet files, distributing plugin translations, the StorefrontSnippetsExtension and translation events, the Flysystem storage backend, service decoration, and the CLI commands and scheduled task. Also update the built-in translation handling page to lead with the new shopware.translation configuration override (recommended) and demote decoration to an advanced fallback, and link the new page from the section index.
Developer Docs healthcheckStatus: Completed with |
Copilot started reviewing on behalf of
Martin Krzykawski (MartinKrzykawski)
July 24, 2026 08:50
View session
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands the Shopware 6 developer documentation around the translation/language system by cataloging extension points and updating existing translation docs to reflect the recommended configuration override approach.
Changes:
- Adds a new “Extension points” page that inventories translation/snippet extension mechanisms from configuration to decoration.
- Updates the “How to extend or modify” section in the built-in translation system doc to lead with
shopware.translationconfiguration overrides. - Updates the translations index to include a
PageRefto the new extension points page.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| concepts/framework/translations/index.md | Adds navigation entry (PageRef) to the new extension points page. |
| concepts/framework/translations/extension-points.md | New comprehensive catalog of translation system extension points and where to hook in. |
| concepts/framework/translations/built-in-translation-system.md | Reworks extension guidance to recommend config overrides first, with decoration as an advanced option. |
Comments suppressed due to low confidence (1)
concepts/framework/translations/extension-points.md:212
- Table entries should not end with punctuation (see docs style guide: resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md:101). The “Purpose” cells in this commands table currently end with periods; please remove the trailing punctuation to match the repository’s table style.
| `translation:install` | Download and install translations for the given `--locales` or `--all`. |
| `translation:update` | Update all installed translations from the repository. |
| `translation:list` | List the locales configured for installation and update. |
| `translation:lint-filenames` | Validate (and with `--fix` migrate) snippet file names. |
| `snippet:validate` | Validate snippet files for missing or extraneous keys. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Martin Krzykawski (MartinKrzykawski)
added
the
Improvement
Remove trailing punctuation from table cells and the ellipsis table header per the documentation style guide (04-fonts-and-formats/01-text.md), and use fully-qualified, copy/paste-able service ids in the decoration table.
- Drop the 'recommended'/'advanced' labels and value-laden framing in the extend section so developers choose the approach themselves. - Remove semicolons from prose. - Reference the canonical configuration override, field reference, and Flysystem sections on the built-in translation handling page instead of repeating them in the extension points page.
David Neustadt (dneustadt)
approved these changes
Jul 27, 2026
Marcel Brode (marcelbrode)
requested changes
Jul 27, 2026
- Break the intro into a bullet list of the system's parts. - Lead with the snippet module (edit in Administration, ship snippet files) as the lightest option and link to the existing snippet guides; move the download-system configuration lower in the ordering. - Clarify that the 'messages' domain is reserved for language-defining base files and must not be used for regular snippet files. - Frame StorefrontSnippetsExtension as the programmatic path below the snippet module rather than the default. - Reframe extension translation distribution around hosting your own repository instead of contributing to shopware/translations. - Use 'ID' instead of 'id' in prose.
An accidental </content> tag at the end of the file failed the developer-portal build with 'Invalid end tag'. Remove it.
- Switch UK spellings to en-US (behaviour -> behavior, synchronising -> synchronizing) as the docs standard. - Use 'replacement semantics' wording and drop the blank frontmatter line in the extension points page.
Martin Krzykawski (MartinKrzykawski)
requested a review
from Marcel Brode (marcelbrode)
July 28, 2026 07:16
Marcel Brode (marcelbrode)
approved these changes
Jul 28, 2026
Su (sushmangupta)
approved these changes
Jul 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents all extension points of the Shopware 6 translation / language system, resolving the "Evaluate extension points" technical TODO (shopware/shopware#17758).
concepts/framework/translations/extension-points.md— a comprehensive catalog with an "I want to… → use this" table, ordered from lightest (configuration) to most invasive (decoration):shopware.translationconfiguration override (recently added in feat(core): make built-in translation config overridable via config/packages shopware#18601)StorefrontSnippetsExtension(storefront.snippetspre/post events) and theTranslationLoadedEvent/TranslationRemovedEvent/SnippetsThemeResolveEventeventsUpdateTranslationsTaskscheduled task@internal/finalboundariesbuilt-in-translation-system.md— the "How to extend or modify" section previously covered only decoration and predated the config override; it now leads with theshopware.translationoverride (recommended) and keeps decoration as an advanced fallback.index.mdwith aPageRefto the new page.Related links
Checklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted..wordlist.txt(and sorted it) if spellcheck flags new legitimate terms.Notes
No pages were moved, renamed, or deleted, so no
.gitbook.yamlredirects are needed. Spellcheck required no new wordlist entries (wording was adjusted to stay within the existing dictionary). All code samples and the extension-point inventory were verified againsttrunkinshopware/shopware(src/Core/System/Snippet/). markdownlint passes and everyPageRef/link target resolves.