Fix links, add database info, add grammar and language

guides/plugins/apps/app-sdks/symfony-bundle/index.md

@@ -83,13 +83,7 @@ The registration also dispatches events to react to the different lifecycle even
 
 ### 4. Connecting Doctrine to a Database
 
-The App Bundle brings, by default, a basic Shop entity to store the shop information.
-You can extend this entity to store more information about your app if needed.
-
-Doctrine is, by default, configured to use PostgreSQL. If you want to use MySQL, change the `DATABASE_URL` environment variable in your `.env` file.
-For development, you can also use SQLite by setting the `DATABASE_URL` to `sqlite:///%kernel.project_dir%/var/app.db`.
-
-After choosing your database engine, create your first migration using `./bin/console make:migration` (Requires Migration Bundle `composer req migrations`) and apply it with the command: `bin/console doctrine:migrations:migrate`.
+<<< @/docs/snippets/guide/app_database_setup.md
 
 ### 5. Implement first ActionButtons, Webhooks, Payment
 

guides/plugins/apps/starter/product-translator.md

@@ -7,7 +7,7 @@ nav:
 
 # Starter Guide - Read and Write Data
 
-This guide will show you how to set up an app server with our [app template](https://github.com/shopware/AppTemplate).
+This guide will show you how to set up an app server with our [app bundle](https://github.com/shopware/app-bundle-symfony).
 You will learn how to read and write data to the Shopware Admin API using an example of fetching dynamic translations for products when they are updated.
 
 ## Prerequisites
@@ -19,7 +19,7 @@ You will learn how to read and write data to the Shopware Admin API using an exa
 
 ## Setting up the app template
 
-First we need to create a new Symfony project using Symfony-CLI
+First, we need to create a new Symfony project using Symfony-CLI
 
 ```sh
 symfony new translator-app
@@ -33,7 +33,7 @@ Now we need to install the Shopware App Bundle with Composer:
 composer require shopware/app-bundle
 ```
 
-Modify the `SHOPWARE_APP_NAME` and `SHOPWARE_APP_SECRET` in the env to your app name`./.env` to ensure the app can be installed in a store later.
+Modify the `SHOPWARE_APP_NAME` and `SHOPWARE_APP_SECRET` in the env to your app name`./.env` to ensure you can install the app in a store later.
 Also, configure the `DATABASE_URL` to point to your database:
 
 ```sh
@@ -68,7 +68,7 @@ This will expose your Symfony server on a public URL, so the cloud store can com
 
 The `manifest.xml` is the main interface definition between stores and your app server.
 It contains all the required information about your app.
-Let's start by filling in all the meta information:
+Let's start by filling in all the meta-information:
 
 ```xml
 // release/manifest.xml
@@ -113,7 +113,7 @@ The `<secret>` element is only present in development versions of the app. In pr
 
 ### Permissions
 
-Permissions are needed as this app will need to read product descriptions and translate them:
+The manifest needs permissions as this app will read product descriptions and translate them:
 
 ```xml
 // release/manifest.xml
@@ -169,8 +169,7 @@ in its shops:
 The timeout for the requests against the app server is 5 seconds.
 :::
 
-These four webhooks are provided by the App Bundle,
-so the Bundle does for you the complete lifecycle and handling of Webhooks.
+The App Bundle provides these four webhooks, so the Bundle does the complete lifecycle and handling of Webhooks for you.
 
 ## Handling shop events
 
@@ -225,10 +224,10 @@ Now we can inspect the event payload:
 ### Fetching data from the shop
 
 All `$entity.written` events contain a list of fields that a written event has changed.
-The code above uses this information to determine if the description of a product was changed.
-If the change did not affect the description, the listener early returns because there is nothing else to do for this event.
+The code above uses this information to determine if someone changed the description of a product.
+If the change does not affect the description, the listener early returns because there is nothing else to do with this event.
 
-Now that it is certain that the description of the product was changed, we fetch the description through the API of the shop:
+Now that it is certain that someone changed the description of the product, we fetch the description through the API of the shop:
 
 ```php
 // src/EventListener/ProductWrittenWebhookListener.php
@@ -301,7 +300,7 @@ We will get to the generation of the hash later, but we need to check it first:
 
 ### Writing a translated description
 
-Now that the app can be sure the description has not been translated before it can write the new description like so:
+Now that the app can be sure, the description has not been translated before it can write the new description like so:
 
 ```php
 // src/EventListener/ProductWrittenWebhookListener.php
@@ -326,11 +325,15 @@ Now that the app can be sure the description has not been translated before it c
     }
 ```
 
-Note that the hash of the original description gets saved as a value in the
-custom fields of the product entity. This is possible without any further config since all custom fields are schema-less.
+Note that the hash of the original description gets saved as a value in the custom fields of the product entity.
+This is possible without any further config since all custom fields are schema-less.
 
 The implementation of the `translate` method is disregarded in this example. You might perform an additional lookup through a translation API service to implement it.
 
+## Connecting Doctrine to a Database
+
+<<< @/docs/snippets/guide/app_database_setup.md
+
 ## Install the app
 
 In this last step, we will install the app using the Shopware CLI tools.
@@ -344,7 +347,7 @@ shopware-cli project extension upload ProductTranslator/release --activate --inc
 ```
 
 This command will create a zip file from the specified extension directory and upload it to your configured store.
-The `--increase-version` parameter increases the version specified in the `manifest.xml` file. This flag is required so Shopware picks up changes made to the `manifest.xml` since the last installation.
+The `--increase-version` parameter increases the version specified in the `manifest.xml` file. The app requires this flag so Shopware picks up changes made to the `manifest.xml` since the last installation.
 Once successfully installed, you will see the app in the extension manager.
 And when you save a product, the description will automatically update.
 

snippets/guide/app_database_setup.md

@@ -0,0 +1,12 @@
+The App Bundle ships with a basic Shop entity to store the shop information. You can extend this entity to store more information about your app if needed.
+
+Symfony configures doctrine to use PostgreSQL by default. Change the `DATABASE_URL` environment variable in your `.env` file if you want to use MySQL.
+You can also use SQLite by setting the `DATABASE_URL` to `sqlite:///%kernel.project_dir%/var/app.db` for development.
+
+After choosing your database engine, you need to require two extra composer packages.
+
+```shell
+composer req symfony/maker-bundle migrations
+```
+
+And create your first migration using `bin/console make:migration` (which is using the `AbstractShop` Class) and apply it to your database with `bin/console doctrine:migrations:migrate`.