Add migration guide for language PIP changes in 5.5

See WoltLab/WCF#4261

diff --git a/docs/migration/wsc54/php.md b/docs/migration/wsc54/php.md
new file mode 100644 (file)
index 0000000..cdca235
--- /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 1e61825d88962cdc4978c862bcbbce8bd5561f78..eef35041051f11b57d0b7f5979ac9d81aa58a6ee 100644 (file)
--- 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 (file)
index 0000000..c80aaf5
--- /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 (file)
index 0000000..099566a
--- /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 (file)
index 0000000..b22d4d6
--- /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>