web-vision · NarkNiro · Sep 27, 2024 · Jul 12, 2024 · Jul 13, 2024 · Jul 13, 2024
diff --git a/.ddev/config.yaml b/.ddev/config.yaml
@@ -21,7 +21,6 @@ web_environment:
     - typo3DatabasePassword=root
     - typo3DatabaseUsername=root
 nodejs_version: "16"
-DEEPL_API_KEY: ""
 
 # Key features of DDEV's config.yaml:
 

diff --git a/Documentation/Administration/AutoTranslatePrefix/Index.rst b/Documentation/Administration/AutoTranslatePrefix/Index.rst
@@ -5,11 +5,10 @@
 Auto-translate-prefix
 =====================
 
-To enable tagging for Automatically Translated Pages and Content
-the page activation of translated pages was extended in order to implement a control
-possibility to implement.
+To enable the tagging of automatically translated pages and content, the page
+activation of translated pages has been extended to provide a means of control.
 
-This information is passed in the Page Context Fluid template and can be used there to enable a page specific appearance.
+This information is passed to the Page Context Fluid template, where it can be used to create a page-specific look.
 
 ..  figure:: /Images/Editor/AutoTranslatePrefix/page-translation-prefix.png
     :alt: Page Frontend
@@ -18,7 +17,7 @@ This information is passed in the Page Context Fluid template and can be used th
 ----
 
 
-To make this easy can also be used in the extension Partial.
+To make this easier, you can also use the extension partial.
 
 ..  code-block:: html
 

diff --git a/Documentation/Administration/Configuration/Index.rst b/Documentation/Administration/Configuration/Index.rst
@@ -5,19 +5,105 @@
 Configuration
 =============
 
+Set up API
+------------------------
+
+.. attention::
+    Before using the DeepL API, you need to get an API key from your `DeepL Profile`_.
+
+Go to :guilabel:`Admin Tools > Settings > Extension Configuration`.
+
+Open the settings for :guilabel:`wv_deepltranslate` and add your API key.
+
+.. figure:: /Images/Reference/configuration.png
+    :alt: The Extension configuration settings showing two input fields for DeepL API key
+
+The extension is set up to auto-detect the corresponding DeepL API URL.
+
+.. _sitesetup:
+
+Set up translation language
+---------------------------
+
+#. Go to :guilabel:`Site Management > Sites` and edit your site configuration
+#. Switch to tab `Languages` and open your target
+
+    .. figure:: /Images/Administration/site-config-deepl-settings-empty.png
+        :alt: Site settings for a TYPO3 language showing empty DeepL Target Language dropdown
+
+#. Go to :guilabel:`DeepL Settings` and set up your `Target Language (ISO Code)`
+
+    .. figure:: /Images/Administration/site-config-selected-target.png
+        :alt: Selected target now set to German
+
+.. note::
+    Although the drop-down list can also be set in the default language, there is
+    no point in defining a target language for the source language.
+
+Choice a Formality
+------------------
+
+The formality configuration has been moved from the extension configuration to the SiteConfig languages.
+The Formality Select field is only displayed if the selected Target-Translate of DeepL is supported.
+
+.. note::
+    For TYPO3 projects with more than one page root and language there is an upgrade wizard,
+    which migrates the global formality configuration in the language config.
+
+    .. figure:: /Images/Administration/site-config-selected-target-formally.png
+        :alt: Selected target now set to German wird default formality
+
+The same option is available in the Select field as DeepL API Supported.
+
+..  confval:: deeplFormality
+
+    :type: string
+
+    Sets whether the translated text should lean towards formal or informal language.
+    Possible options:
+
+    default
+        The default setting. If formal or informal depends on the language
+
+    less
+        Less formal language. Will fail, if no formality support for language
+
+    more
+        More formal language. Will fail, if no formality support for language
+
+    prefer_less
+        Use less formal language, if possible, otherwise fallback to default
+
+    prefer_more
+        Use more formal language, if possible, otherwise fallback to default
+
+
+Configure tables
+----------------
+
+If not default set, you need to define the `l10n_mode` for the fields you want to
+have translatable by `wv_deepltranslate`.
+
+See the :ref:`tableConfiguration<table configuration>` for details.
+
 Detecting target language
 -------------------------
 
-From TYPO3 11.5 LTS on the detection of the target language works as following:
+The following chain tries to detect the language to translate into:
 
 #.  Set up DeepL Translation language in SiteConfiguration
     * Target languages detected from DeepL will only appear
 #.  Check hreflang against DeepL supported languages
     * Needed for detecting EN-GB, EN-US, PT-PT or PT-BR
 #.  Fallback to Language ISO code
 
+For currently allowed languages see the `DeepL conform language key`_. As this
+extension retrieves available languages from the API, translations are restricted
+to the languages listed in the official DeepL API documentation.
+
 If none of these match against DeepL API, translation for this language
 is disabled for usage within DeepL. Translation buttons and dropdowns
 respect this setting.
 
-..  _DeepL conform language key: https://www.deepl.com/de/docs-api/general/get-languages/
+..  _DeepL conform language key: https://developers.deepl.com/docs/api-reference/languages
+.. _DeepL Profile: https://www.deepl.com/en/your-account/keys
diff --git a/Documentation/Administration/Installation/Index.rst b/Documentation/Administration/Installation/Index.rst
@@ -5,8 +5,8 @@
 Installation
 ============
 
-The extension needs to be installed as any other extension of TYPO3 CMS. Get the
-extension by one of the following methods:
+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
@@ -28,7 +28,7 @@ extension by one of the following methods:
 
 and :ref:`configure <extensionConfiguration>` it.
 
-Inside your own site configuration follow the instructions for
+Within your own site configuration follow the instructions for
 :ref:`table configuration <tableConfiguration>`.
 
 ..  _TER: https://extensions.typo3.org/extension/wv_deepltranslate

diff --git a/Documentation/Administration/Updates/Index.rst b/Documentation/Administration/Updates/Index.rst
@@ -2,11 +2,25 @@
 
 ..  _updates:
 
+=======
 Updates
 =======
 
+Version 3.x > 4.x
+=================
+
+If you are upgrading from 3.x on TYPO3 11 LTS to 12 LTS and you have used the site
+config setup for translations, you can simply update.
+
+Upgrade with Core Upgrade
+-------------------------
+
+If you are upgrading from a TYPO3 version below v11, you need to define the target
+languages in the site configuration. See :ref:`sitesetup<Site Setup section>`
+in this documentation.
+
 Version 2.x > 3.x
------------------
+=================
 
 ..  note:: This Upgrade is only needed, if you are using glossary functionality.
 

diff --git a/Documentation/Editor/AutoTranslatePrefix/Index.rst b/Documentation/Editor/AutoTranslatePrefix/Index.rst
@@ -5,29 +5,28 @@
 Auto-translate-prefix
 =====================
 
-To enable tagging for Automatically Translated Page and Content
-the Page Turned On of translated pages was extended to implement a control
-possibility to implement.
+To enable tagging of automatically translated pages and content, the page turned
+on of translated pages has been extended to implement a control.
 
 
 ..  figure:: /Images/Editor/AutoTranslatePrefix/page-translation-properties.png
     :alt: Page Property DeepL Translate
 
-With each translation process of content the fields are updated.
+Each time content is translated, the fields are updated.
 
 ----
 
-The field information "Last translation date" and "DeepL Translated content has not been checked".
+The field information "Last translation date" and "DeepL Translated content has not been checked"
 are always transferred to the page object and can be queried in Fluid.
 
-Thus, information and notes in Fluid template can be controlled if necessary.
-This must be added to the template by a TYPO3 administrator or developer beforehand.
+In this way, information and notes can be controlled in the Fluid template if required.
+This must be added to the template by a TYPO3 administrator or developer.
 
 ..  figure:: /Images/Editor/AutoTranslatePrefix/page-translation-prefix.png
     :alt: Page Frontend prefix
 
-When an editor previews DeepL translated hidden page,
-a DeepL badge is displayed in addition to the "Preview" badge in the upper right corner.
+When an editor is previewing a hidden page translated by DeepL, a DeepL badge is
+displayed in addition to the "Preview" badge in the upper right corner.
 
 ..  figure:: /Images/Editor/AutoTranslatePrefix/page-translation-preview.png
     :alt: Page frontend preview
diff --git a/Documentation/Editor/Glossary/Index.rst b/Documentation/Editor/Glossary/Index.rst
@@ -5,57 +5,55 @@
 Glossaries
 ==========
 
-You are able to define glossaries for your translation. Each glossary has a
-name, a source language and a target language defined. The name is built by
-the Page title and the target and source language.
+You can define glossaries for your translations. Each glossary has a name, a source
+language and a target language. The name is made up of the page title and the target
+and source languages.
 
 ..  figure:: /Images/Editor/glossaries-list-view.png
     :alt: List view of glossary items
 
-On pages with Doktype 254 (Folder) and "Use Container" to "DeepL Glossar" set,
-a synchronise button appears to easy sync the glossary terms listed in this page.
+On pages with Doktype 254 (Folder) and "Use Container" set to "DeepL Glossary",
+a synchronise button appears for easy synchronisation of the glossary terms listed in this page.
 
 Possible glossary combinations in multiple language translation modes are built
-on the fly, so your glossary can be used from every target to source, **except**
-the default system language.
+on the fly, so your glossary can be used from any target to source, **except** the
+default system language.
 
-Each glossary shows you the current sync status to DeepL API in page settings.
+Each glossary shows you the current sync status to the DeepL API in the page settings.
 
 ..  figure:: /Images/Editor/glossary-sync-tab-not-synced.png
     :alt: Page settings tab *DeepL Translate* with not synced glossary
 
-Adding terms is done by list module.
+Adding terms is done through the list module.
 
 ..  figure:: /Images/Editor/glossary-add-term.png
     :alt: Add entry via add record
 
-To generate a glossary translation, simply translate the page via TYPO3
-translation dropdown to your needed glossary language. A custom translation
-dropdown is shown, which only takes languages, where glossary entries can be
-built to.
+To generate a glossary translation, simply translate the page into the required
+glossary language using the TYPO3 translation dropdown. A custom translation dropdown
+will be displayed, which will only accept languages in which glossary entries can be created.
 
 ..  figure:: /Images/Editor/glossary-page-translation.png
     :alt: Custom translation dropdown in list view
 
 ..  figure:: /Images/Editor/glossary-page-translation-select.png
     :alt: Possible translations based on source language EN
 
-After that, you are able to make translations with the *Translate to* button.
+After that you can make translations with the *Translate to* button.
 As the glossary entries are made for not using DeepL standard wording, the
 ability of translating entries by DeepL is disabled.
 
 ..  figure:: /Images/Editor/glossary-entry-list.png
     :alt: Backend list view of glossary entries, original language english, translated to German
 
-In page settings, Tab **DeepL Translate** you will retrieve current sync
-information of this glossary to API.
+You can retrieve the current sync information of this glossary to the API in the
+page settings, tab **DeepL Translate**.
 
 ..  note::
 
-    Currenty **NO** automatic sync is done on save. Save and trigger sync
-    manually.
+    Current **NO** Automatic sync is performed on save. Save and trigger sync manually.
 
-In each glossary directory a button is enabled to sync this glossary.
+In each glossary directory, a button is enabled to synchronise that glossary.
 
 After sync the tab *DeepL Translate* should look like this:
 

diff --git a/Documentation/Editor/Index.rst b/Documentation/Editor/Index.rst
@@ -2,7 +2,7 @@
 
 ..  _editor:
 
-Editors
+Editors manuel
 =======
 
 How editors work with *wv_deepltranslate* is described in the following chapters.

diff --git a/Documentation/Editor/Usage/Index.rst b/Documentation/Editor/Usage/Index.rst
@@ -8,9 +8,9 @@ Basic Usage
 Translating content elements
 ----------------------------
 
-Once the extension is installed and API key provided, we are good to go for
-translating content elements. On translating content element, there appears
-additional four options apart from normal translate and copy.
+Once the extension is installed and the API key provided, we are ready to start
+translating content elements. When translating a content element, there are four
+additional options besides the normal translate and copy.
 
 * DeepL Translate (auto detect).
 * DeepL Translate.
@@ -24,9 +24,9 @@ additional four options apart from normal translate and copy.
 Translating a page
 ------------------
 
-*wv_deepltranslate* adds a separate dropdown for DeepL translation of a page
-to list and web module. The dropdown is filtered to not translated pages
-and against DeepL API possible translation languages.
+*wv_deepltranslate* adds a separate dropdown for DeepL translation of a page to
+the list and web module. The dropdown is filtered to not translated pages and
+against DeepL API possible translation languages.
 
 ..  figure:: /Images/Editor/translation-dropdown.png
     :alt: Dropdown for DeepL translation
@@ -40,8 +40,8 @@ translate button for the language you want.
 ..  figure:: /Images/Editor/translation-buttons-page.png
     :alt: Translation buttons in list view
 
-Languages not available will have no DeepL button. In this case use normal
-translation.
+Languages that are not available will have no DeepL button. In this case,
+use normal translation.
 
 ..  figure:: /Images/Editor/translation-button-news.png
     :alt: Translation button for tx_news, one language not available in DeepL

diff --git a/Documentation/Faq/Index.rst b/Documentation/Faq/Index.rst
@@ -5,9 +5,27 @@
 FAQ
 ===
 
+My dropdown in the site configuration is empty
+----------------------------------------------
+
+This happens if TYPO3 cached the request from the DeepL API for allowed languages,
+but no API key was provided. In this case, empty your system cache in TYPO3.
+Normally no cache files should be created when no API key is provided.
+
+If this step does not work, delete the cached files manually. The location is as follows:
+
+* composer based installation
+    `var/cache/data/wvdeepltranslate`
+* legacy installation
+    `typo3temp/var/cache/data/wvdeepltranslate`
+
+After deleting the files in this directory and going to Site Configuration, the
+extension will reload the cache and the dropdown should have all the translatable
+language keys.
+
 What will be the cost for DeepL API subscription?
-----------------------------------------------------------------
+-------------------------------------------------
 
-You can find all the details regarding  DeepL API usage here:
+You can find all the details regarding the usage of the DeepL API here:
 
 *   https://www.deepl.com/pro-pricing.html
diff --git a/Documentation/Files/versionSupport.csv b/Documentation/Files/versionSupport.csv
@@ -1,2 +1,3 @@
-2.3,9-11,>=7.4
-3.0,9-11,>=7.4
+"2.3","9-11",">=7.4"
+"3.0","9-11",">=7.4"
+"4.0-4.x","11-12","7.4, 8.0, 8.1, 8.2, 8.3"