web-vision · sbuerk · Jul 6, 2026 · Jul 6, 2026
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,102 @@
+name: documentation
+
+on:
+  pull_request:
+
+jobs:
+
+  documentation:
+    name: "render documentation"
+    runs-on: ubuntu-22.04
+    outputs:
+      comment_id: ${{ steps.find-comment.outputs.comment-id }}
+      documentation_url: ${{ steps.documentation-artifact.outputs.artifact-url }}
+    strategy:
+      fail-fast: false
+    permissions:
+      contents: write
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v6
+
+      - name: Find Comment
+        uses: peter-evans/find-comment@v4
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+
+      - name: "Render documentation"
+        run: "Build/Scripts/runTests.sh -b podman -s renderDocumentation"
+
+      - uses: actions/upload-artifact@v6
+        id: documentation-artifact
+        with:
+          name: documentation-${{ github.event.pull_request.number }}-${{ github.run_id }}
+          path: Documentation-GENERATED-temp/
+          compression-level: 9
+          if-no-files-found: error
+          retention-days: 5
+          include-hidden-files: true
+          overwrite: true
+
+
+  documentation-report:
+    name: "report rendered documentation"
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+    needs: [ documentation ]
+    steps:
+
+      - name: Display information
+        run: |
+          echo "PR_ID.......: ${{ github.event.pull_request.number }}"
+          echo "COMMENT_ID..: ${{ needs.documentation.outputs.comment-id }}"
+          echo "ARTIFCAT_URL: ${{ needs.documentation.outputs.documentation_url }}"
+
+      - name: Create Comment
+        uses: peter-evans/create-or-update-comment@v5
+        # Skip if PR from fork (https://github.com/peter-evans/create-or-update-comment/issues/444)
+        # or comment-id not empty
+        if: github.repository == github.event.pull_request.head.repo.full_name && needs.documentation.outputs.comment_id == ''
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          edit-mode: replace
+          body: |-
+            ## Documentation rendering
+
+            You can find files attached to the below linked Workflow Run URL (Logs).
+
+            Please note that files only stay for around 5 days!
+
+            | Name          | Link                                                                                |
+            |---------------|-------------------------------------------------------------------------------------|
+            | Commit        | ${{ github.event.pull_request.head.sha }}                                           |
+            | Logs          | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
+            | Documentation | ${{ needs.documentation.outputs.documentation_url }}                                |
+
+            [badge]: https://img.shields.io/badge/Build-Success!-3fb950?logo=github&style=for-the-badge
+
+      - name: Update Comment
+        # Skip if PR from fork (https://github.com/peter-evans/create-or-update-comment/issues/444)
+        # or comment-id empty
+        if: github.repository == github.event.pull_request.head.repo.full_name && needs.documentation.outputs.comment_id != ''
+        uses: peter-evans/create-or-update-comment@v5
+        with:
+          comment-id: ${{ needs.documentation.outputs.comment_id }}
+          edit-mode: replace
+          body: |-
+            ## Documentation rendering
+
+            You can find files attached to the below linked Workflow Run URL (Logs).
+
+            Please note that files only stay for around 5 days!
+
+            | Name          | Link                                                                                |
+            |---------------|-------------------------------------------------------------------------------------|
+            | Commit        | ${{ github.event.pull_request.head.sha }}                                           |
+            | Logs          | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
+            | Documentation | ${{ needs.documentation.outputs.documentation_url }}                                |
+
+            [badge]: https://img.shields.io/badge/Build-Failure!-f85149?logo=github&style=for-the-badge
diff --git a/Build/Scripts/runTests.sh b/Build/Scripts/runTests.sh
@@ -566,7 +566,7 @@ case ${TEST_SUITE} in
         SUITE_EXIT_CODE=$?
         ;;
     renderDocumentation)
-        ${CONTAINER_BIN} run ${CONTAINER_INTERACTIVE} --pull always -v ${ROOT_DIR}:/project -it ${IMAGE_RSTRENDERING} --config=Documentation
+        ${CONTAINER_BIN} run ${CONTAINER_COMMON_PARAMS} --name rendering-documentation-${SUFFIX} --pull always -w /project -v ${ROOT_DIR}:/project -it ${IMAGE_RSTRENDERING} --fail-on-error --no-progress --config=Documentation Documentation
         SUITE_EXIT_CODE=$?
         ;;
     phpstan)

diff --git a/Documentation/Administration/Configuration/Index.rst b/Documentation/Administration/Configuration/Index.rst
@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _configuration:
 
 Configuration

diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst
@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _administration:
 
 ==============
@@ -12,3 +10,4 @@ Administration
 
     Installation/Index
     Configuration/Index
+    Updates/Index
diff --git a/Documentation/Administration/Installation/Index.rst b/Documentation/Administration/Installation/Index.rst
@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _installation:
 
 Installation
@@ -8,34 +6,81 @@ Installation
 The extension has to be installed like any other TYPO3 CMS extension.
 You can download the extension using one of the following methods:
 
-#.  **Use composer**:
-    Run
+..  tabs::
+
+    ..  group-tab:: composer
+
+        ..  code-block:: bash
+            :caption: only the extension itself
+
+            composer require -W \
+               'web-vision/deepl-write':'~2.0.0@dev'
+
+        ..  code-block:: bash
+            :caption: requiring depending TYPO3 extensions along the way
+
+            composer require -W \
+                'web-vision/deeplcom-deepl-php':'~1.18.0@dev' \
+                'web-vision/deepl-base':'~2.0.0@dev' \
+                'web-vision/deepl-write':'~2.0.0@dev'
+
+        ..  tip::
 
-    ..  code-block:: bash
+            :guilabel:`~2.0.0@dev` is the recommended version constraint to use, which
+            locks the installable version down on :guilabel:`minor level (2.0)` having
+            :guilabel:`2.0.0` as lowest patchlevel version. :guilabel:`@dev` in general
+            would allow to install a possible development version and automatically
+            switch to the stable release in case :guilabel:`minimum-stability: "dev"`
+            and :guilabel:`prefer-stable: true` is configured in the root
+            :guilabel:`composer.json` file.
 
-        composer require -W 'web-vision/deepl-write':'^2.0'
+            :guilabel:`-W` automatically installs required transient dependencies, for
+            example:
 
-    in your TYPO3 installation.
+            *   :guilabel:`web-vision/deepl-base` and
+            *   :guilabel:`web-vision/deeplcom-deepl-php`
 
-#.  **Get it from the Extension Manager**:
-    Switch to the module :guilabel:`Admin Tools > Extensions`.
-    Switch to :guilabel:`Get Extensions` and search for the extension key
-    *deepltranslate_core* and import the extension from the repository.
+        ..  note::
 
-#.  **Get it from typo3.org**:
-    You can always get current version from `TER`_ by downloading the zip
-    version. Upload the file afterwards in the Extension Manager.
+            **Be aware** that aforementioned version constraints may be outdated, look up
+            actual version by checking the `packagist.org <https://packagist.org/>`_
+            meta-data repository.
 
-The extension then needs to be :ref:`configured <configuration>`
-in order to display translation buttons in the desired languages.
+            * `packagist.org - web-vision/deepl-write <https://packagist.org/packages/web-vision/deepl-write>`_
+            * `packagist.org - web-vision/deepl-base <https://packagist.org/packages/web-vision/deepl-base>`_
+            * `packagist.org - web-vision/deeplcom-deepl-php <https://packagist.org/packages/web-vision/deeplcom-deepl-php>`_
+
+    ..  group-tab:: Extension Manager
+
+        #.  Switch to the module :guilabel:`System > Extensions`.
+        #.  Switch to :guilabel:`Get Extensions`
+        #.  Search for the extension key :guilabel:`deepl_write`
+        #.  Import the extension from the repository.
+
+        ..  note::
+
+            For TYPO3 v13 navigate :guilabel:`Admin Tools > Extensions` to
+            find the **Extension Manager**.
+
+    ..  group-tab:: Upload ZIP (TER)
+
+        #.  Get current version from `TER`_ by downloading the zip version.
+            Alternatively, get the zip from the `Github Releases`_ page.
+        #.  Switch to the module :guilabel:`System > Extensions`.
+        #.  Enable upload :guilabel:`Upload Extension`
+        #.  Select or drag extension ZIP archive and upload the file
 
 ..  _TER: https://extensions.typo3.org/extension/deepl_write
+..  _Github Releases: https://github.com/web-vision/deepl-write/releases
+
+The extension then needs to be :ref:`configured <configuration>` in order to
+use the DeepL Write features.
 
 Compatibility
 -------------
 
 DeepL Write supports:
 
 ..  csv-table:: Changes
-    :header: "DeepL Write version","TYPO3 Version","PHP version(s)","Supported"
+    :header: "DeepL Write version","TYPO3 Version","PHP version","Supported","Composer","TER"
     :file: Files/versionSupport.csv
diff --git a/Documentation/Administration/Updates/Index.rst b/Documentation/Administration/Updates/Index.rst
@@ -0,0 +1,12 @@
+..  _updates:
+..  _upgrades:
+
+========
+Upgrades
+========
+
+..  toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    UpgradeFrom1To2
diff --git a/Documentation/Administration/Updates/UpgradeFrom1To2.rst b/Documentation/Administration/Updates/UpgradeFrom1To2.rst
@@ -0,0 +1,41 @@
+.. _upgrade1to2:
+
+==================
+Upgrade 1.x to 2.x
+==================
+
+The `2.x` version drops support for TYPO3 v12 and adds support for TYPO3 v14,
+see :ref:`Breaking: Removed TYPO3 v12 support <breaking-1783314229>` and
+:ref:`Feature: Added TYPO3 v14 support <feature-1783314230>`.
+
+Apart from the changed supported TYPO3 versions the functionality stayed the
+same and no greater actions are needed.
+
+composer-mode
+=============
+
+..  code-block:: bash
+
+    composer require -W \
+       "web-vision/deepl-write":"2.0.*@dev"
+
+classic-mode
+============
+
+#.  **Get it from the Extension Manager**:
+    Switch to the module :guilabel:`System > Extensions`.
+    Switch to :guilabel:`Get Extensions` and search for the extension key
+    *deepl_write* and import the extension from the repository.
+
+#.  **Get it from typo3.org**:
+    You can always get current version from `TER`_ by downloading the zip
+    version. Upload the file afterwards in the Extension Manager.
+
+#.  **Get it from GitHub release**:
+    TER upload archives are added to the corresponding GitHub release page,
+    in case you need to download or update the extension and `GITHUB_RELEASES`_
+    is down or not reachable.
+
+
+..  _TER: https://extensions.typo3.org/extension/deepl_write
+..  _GITHUB_RELEASES: https://github.com/web-vision/deepl-write/releases/
diff --git a/Documentation/Changelog/2.0/Breaking-RemovedTYPO3V12Support.rst b/Documentation/Changelog/2.0/Breaking-RemovedTYPO3V12Support.rst
@@ -0,0 +1,35 @@
+..  _breaking-1783314229:
+
+===================================
+Breaking: Removed TYPO3 v12 support
+===================================
+
+Description
+===========
+
+Support for TYPO3 v12 has been removed for `2.x` based on our dual
+TYPO3 core version support per major version as casual support matrix.
+
+This includes removing code paths and configurations only required for
+TYPO3 v12.
+
+Impact
+======
+
+TYPO3 v12 or older instances cannot update to the `2.x` version and are
+required to upgrade TYPO3 to be able to install the next version of the
+`EXT:deepl_write` together with `EXT:deepl-base (2.x)` and related packages
+when released in a compatible version.
+
+Extension cannot be installed in that version but does not break otherwise.
+
+Affected installations
+======================
+
+TYPO3 v12 or older instances with `EXT:deepl_write` version `1.x`.
+
+Migration
+=========
+
+Upgrade TYPO3 to supported version for `2.x` beforehand or in the same step
+with upgrading/installing `EXT:deepl_write`.
diff --git a/Documentation/Changelog/2.0/Feature-AddedTYPO3v14Support.rst b/Documentation/Changelog/2.0/Feature-AddedTYPO3v14Support.rst
@@ -0,0 +1,38 @@
+..  _feature-1783314230:
+
+================================
+Feature: Added TYPO3 v14 Support
+================================
+
+Description
+===========
+
+:guilabel:`TYPO3 v14.3.*` has been added coming with following changes:
+
+Handling and visual difference between TYPO3 v13 and v14
+--------------------------------------------------------
+
+For `TYPO3 v14` the streamlined and revamped overall localization handling is
+adopted, implementing the `LocalizationHandlerInterface` and making use of the
+new `Localization Handler` feature. That means, that the look and feel is
+different based on the used TYPO3 version even with the same extension version.
+Some examples:
+
+*   TYPO3 v14 localization handler selection:
+
+    ..  figure:: /Images/Editor/deeplwrite-localization-handler-v14.png
+        :alt: Select `DeepL Write` localization handler in TYPO3 v14
+
+*   TYPO3 v13 localization mode selection in `PageLayout module`:
+
+    ..  figure:: /Images/Editor/deeplwrite-localization-mode-v13.png
+        :alt: Select `DeepL Write` localization mode in TYPO3 v13
+
+Impact
+======
+
+:guilabel:`web-vision/deepl-write` can now be installed and used in
+:guilabel:`TYPO3 v14.3` instances.
+
+Supported features are completely available for TYPO3 v13 and v14, except
+that generic TYPO3 handling is used provided by these versions.