doc(translatable): Add a tips about Doctrine Migration

docs/translatable-migration.md

@@ -0,0 +1,43 @@
+# Translatable - Keep existing content with Doctrine Migration
+
+When adding Translatable to an existing project, Doctrine Migration is going to blindly remove your table columns as you moved them to Translatable dedicated entities.
+
+Here is how you can edit your Doctrine Migration to keep your contributed database content.
+
+Let's see an example with a **Master** entity owning a **description** property. You moved this property to the **MasterTranslation** entity. Your initial Doctrine migration will look like this:
+
+```php
+final class Version20221111111111 extends AbstractMigration
+{
+    public function up(Schema $schema): void
+    {
+        $this->addSql('CREATE TABLE master_translation (id INT AUTO_INCREMENT NOT NULL, translatable_id INT DEFAULT NULL, description LONGTEXT DEFAULT NULL, locale VARCHAR(5) NOT NULL, INDEX IDX_BE61F5EA2C2AC5D3 (translatable_id), UNIQUE INDEX master_translation_unique_translation (translatable_id, locale), PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8mb4 COLLATE `utf8mb4_unicode_ci` ENGINE = InnoDB');
+        $this->addSql('ALTER TABLE master_translation ADD CONSTRAINT FK_BE61F5EA2C2AC5D3 FOREIGN KEY (translatable_id) REFERENCES master (id) ON DELETE CASCADE');
+        $this->addSql('ALTER TABLE master DROP description');
+    }
+
+    // ...
+}
+```
+
+The last SQL is problematic: `DROP description` will permanently delete all the contributed descriptions.
+
+All we need to do is add a new SQL statement manually, between the **CREATE TABLE** and the **DROP description**, to move our content using the **INSERT ... SELECT** notation:
+
+```sql
+INSERT INTO master_translation (translatable_id, description, locale) SELECT id, description, 'en' FROM master;
+```
+
+The modification is as follows:
+
+```diff
+public function up(Schema $schema): void
+{
+    $this->addSql('CREATE TABLE master_translation (id INT AUTO_INCREMENT NOT NULL, translatable_id INT DEFAULT NULL, description LONGTEXT DEFAULT NULL, locale VARCHAR(5) NOT NULL, INDEX IDX_BE61F5EA2C2AC5D3 (translatable_id), UNIQUE INDEX master_translation_unique_translation (translatable_id, locale), PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8mb4 COLLATE `utf8mb4_unicode_ci` ENGINE = InnoDB');
+    $this->addSql('ALTER TABLE master_translation ADD CONSTRAINT FK_BE61F5EA2C2AC5D3 FOREIGN KEY (translatable_id) REFERENCES master (id) ON DELETE CASCADE');
++    $this->addSql('INSERT INTO master_translation (translatable_id, description, locale) SELECT id, description, 'en' FROM master;');
+    $this->addSql('ALTER TABLE master DROP description');
+}
+```
+
+Make sure to add all your fields and edit the locale if you don't come from "en" like in the example.

docs/translatable.md

@@ -8,7 +8,10 @@ same folder, e.g.:
 
 The default naming convention (or its customization via trait methods) avoids you to manually handle entity associations. It is handled automatically by the `TranslatableEventSubscriber`.
 
-[How to use translatable with api platform?](/docs/translatable-api-platform.md)
+Related documentations:
+
+- [How to use translatable with api platform?](/docs/translatable-api-platform.md)
+- [How to tweak your Doctrine Migration to keep existing content?](/docs/translatable-migration.md)
 
 ## Entity
 
@@ -228,4 +231,4 @@ No joins are created. Only the query strategy is changed.
 |------------|------------------------------------------------------------------------------------------------------------------------------------|
 | EAGER      | Doctrine always loads the translation.                                                                                             |
 | LAZY       | Doctrine only loads the translation if it's actually used.                                                                         |
-| EXTRA_LAZY | Doctrine only loads the translation if the data is specifically queried. Count and/or contains queries do not trigger new queries. |
+| EXTRA_LAZY | Doctrine only loads the translation if the data is specifically queried. Count and/or contains queries do not trigger new queries. |