From 40a4e6961f77783a9f65e79fcef7a55dc963b631 Mon Sep 17 00:00:00 2001
From: Matthias Schmidt <gravatronics@live.com>
Date: Mon, 7 Jun 2021 13:34:52 +0200
Subject: [PATCH] Add migration guide for language PIP changes in 5.5

See WoltLab/WCF#4261
---
 docs/migration/wsc54/php.md                   | 33 +++++++++++++++++++
 mkdocs.yml                                    |  2 ++
 snippets/migration/wsc54/en_new.xml           |  8 +++++
 .../migration/wsc54/en_new_with_delete.xml    | 11 +++++++
 snippets/migration/wsc54/en_old.xml           |  6 ++++
 5 files changed, 60 insertions(+)
 create mode 100644 docs/migration/wsc54/php.md
 create mode 100644 snippets/migration/wsc54/en_new.xml
 create mode 100644 snippets/migration/wsc54/en_new_with_delete.xml
 create mode 100644 snippets/migration/wsc54/en_old.xml

diff --git a/docs/migration/wsc54/php.md b/docs/migration/wsc54/php.md
new file mode 100644
index 00000000..cdca2359
--- /dev/null
+++ b/docs/migration/wsc54/php.md
@@ -0,0 +1,33 @@
+# Migrating from WSC 5.4 - PHP
+
+## Language Package Installation Plugin
+
+[WCF PR#4261](https://github.com/WoltLab/WCF/pull/4261) has added support for deleting existing phrases with the `language` package installation plugin.
+
+The current structure of the language XML files
+
+{jinja{ codebox(
+    language="xml",
+    title="language/en.xml",
+    filepath="migration/wsc54/en_old.xml",
+) }}
+
+is deprecated and should be replaced with the new structure with an explicit `<import>` element like in the other package installation plugins:
+
+{jinja{ codebox(
+    language="xml",
+    title="language/en.xml",
+    filepath="migration/wsc54/en_new.xml",
+) }}
+
+Additionally, to now also support deleting phrases with this package installation plugin, support for a `<delete>` element has been added: 
+
+{jinja{ codebox(
+    language="xml",
+    title="language/en.xml",
+    filepath="migration/wsc54/en_new_with_delete.xml",
+) }}
+
+Note that when deleting phrases, the category does not have to be specified because phrase identifiers are unique globally.
+
+!!! warning "Mixing the old structure and the new structure is not supported and will result in an error message during the import!"
diff --git a/mkdocs.yml b/mkdocs.yml
index 1e61825d..eef35041 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -105,6 +105,8 @@ nav:
     - 'Database PHP API': 'package/database-php-api.md'
 
   - 'Migration':
+    - 'Migrating from WSC 5.4':
+      - 'PHP API': 'migration/wsc54/php.md'
     - 'Migrating from WSC 5.3':
       - 'PHP API': 'migration/wsc53/php.md'
       - 'Session Handling and Authentication': 'migration/wsc53/session.md'
diff --git a/snippets/migration/wsc54/en_new.xml b/snippets/migration/wsc54/en_new.xml
new file mode 100644
index 00000000..c80aaf59
--- /dev/null
+++ b/snippets/migration/wsc54/en_new.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<language xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/5.4/language.xsd" languagecode="en" languagename="English" countrycode="gb">
+	<import>
+		<category name="wcf.foo">
+			<item name="wcf.foo.bar"><![CDATA[Bar]]></item>
+		</category>
+	</import>
+</language>
diff --git a/snippets/migration/wsc54/en_new_with_delete.xml b/snippets/migration/wsc54/en_new_with_delete.xml
new file mode 100644
index 00000000..099566ae
--- /dev/null
+++ b/snippets/migration/wsc54/en_new_with_delete.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<language xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/5.4/language.xsd" languagecode="en" languagename="English" countrycode="gb">
+	<import>
+		<category name="wcf.foo">
+			<item name="wcf.foo.bar"><![CDATA[Bar]]></item>
+		</category>
+	</import>
+	<delete>
+		<item name="wcf.foo.barrr"/>
+	</delete>
+</language>
diff --git a/snippets/migration/wsc54/en_old.xml b/snippets/migration/wsc54/en_old.xml
new file mode 100644
index 00000000..b22d4d62
--- /dev/null
+++ b/snippets/migration/wsc54/en_old.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<language xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/5.4/language.xsd" languagecode="en" languagename="English" countrycode="gb">
+	<category name="wcf.foo">
+		<item name="wcf.foo.bar"><![CDATA[Bar]]></item>
+	</category>
+</language>
-- 
2.20.1