Add ProcessWire language name to ConfiguredLanguageData object

Author: SkyLundy

.gitignore

@@ -1,2 +1,6 @@
 node_modules
-.dev
+.dev
+.parcel-cache/
+parcel-trace-*
+*.log
+*.cache

.postcssrc

@@ -0,0 +1,6 @@
+{
+  "plugins": {
+    "postcss-import": {},
+    "postcss-nesting": {}
+  }
+}

.prettierrc

@@ -2,4 +2,4 @@
   "singleQuote": true,
   "arrowParens": "avoid",
   "printWidth": 100
-}
+}

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Fluency for ProcessWire Changelog
 
+## 2.2.0 2025-12-23
+
+### Critical update. New features, Bugfixes/Compatability. Required for users of DeepL.
+
+**Critical**: All users employing DeepL as the translation service must upgrade. DeepL API authentication requirements will change in January 2025 with previous methods deprecated. Using Fluency with DeepL after 2025-12-15 will cause all translations to fail with a translation service error displayed in the UI.
+
+- Update DeepL authentication method to Auth header from deprecated URL paramter. More information in the DeepL API documentation [here](https://developers.deepl.com/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key)
+- Add clarification to requirement of AdminThemeUikit to use Fluency in README
+- Add 'name' property to ConfiguredLangaugeData object that makes the ProcessWire name of the
+  language available
+- Fix deprecated PHP 8.4 deprecated implicit null parameters in FluencyMarkup class. Credit to @BernhardBaumrock for finding/reporting
+- Add jQuery change event trigger when translated values are inserted in addition to native JavaScript change event. See note on change detection in RockPageBuilder fields below
+- Add additional TinyMCE compatability.
+- Replace Gulp with Parcel for asset bundling.
+- Replace Sass with CSS, replace Sass transpiler with PostCSS
+- Add compatibility with new AdminThemeUikit 3 theme and theme features. Remains backwards compatible with previous versions
+- UI design updates.
+- Updated README.md with documentation for theming Fluency
+- API usage table now shows used/limit/remaining numbers formatted with commas to more easily read when they're large
+- Remove legacy/unused code and files. Code cleanup. A little more docblocking.
+- Change console warnings about unrecognized fields when attempting to initialize translation to only show when debug is enabled so we aren't junking up the browser console
+- Added additional documentation for contributing and the tech stack for asset bundling
+
+This release addresses issues with change detection in RockPageBuilder fields. Links to issues reported [here](https://processwire.com/talk/topic/24567-fluency-the-complete-translation-enhancement-suite-for-processwire/?do=findComment&comment=249741), and [here](https://processwire.com/talk/topic/24567-fluency-the-complete-translation-enhancement-suite-for-processwire/?do=findComment&comment=249746).
+
+This release also contains the fix for incorrect `href` and `hreflang` when outputting language meta tags using `$fluency->renderAltLinkLanguageMetaTags()`. [Pull Request](https://github.com/SkyLundy/Fluency/pull/19) credit to @WebWorkingMan for reporting and bugfix
+
 ## 2.1.1 2025-03-17
 
 ### Major Bugfix. Recommended for all users

Fluency.info.php

@@ -6,7 +6,7 @@
 
 $info = [
     'title' => 'Fluency',
-    'version' => '211',
+    'version' => '220',
     'href' => 'https://processwire.com/talk/topic/24567-fluency-the-complete-translation-enhancement-suite-for-processwire/',
     'icon' => 'language',
     'summary' => 'The complete translation enhancement suite for ProcessWire.',
@@ -17,6 +17,7 @@
         'LanguageSupport',
         'LanguageTabs',
         'ProcessWire>=300',
+        'AdminThemeUikit',
         'PHP>=8.1',
     ],
     'permission' => 'fluency-translate',

Fluency.module.php

@@ -113,8 +113,8 @@ public function init()
             return;
         }
 
-        $this->moduleJsPath = "{$this->urls->$this}assets/scripts/";
-        $this->moduleCssPath = "{$this->urls->$this}assets/styles/";
+        $this->moduleJsPath = "{$this->urls->$this}assets/bundle/scripts/";
+        $this->moduleCssPath = "{$this->urls->$this}assets/bundle/css/";
 
         $this->initializeCaches();
         $this->initializeTranslationEngine();
@@ -289,8 +289,8 @@ private function insertAdminAssets(): void
      */
     private function insertCoreAssets(): void
     {
-        $this->config->styles->add("{$this->moduleCssPath}fluency_core.min.css");
-        $this->config->scripts->add("{$this->moduleJsPath}fluency.bundle.js");
+        $this->config->styles->add("{$this->moduleCssPath}fluency_core.css");
+        $this->config->scripts->add("{$this->moduleJsPath}fluency.js");
     }
 
     /**
@@ -299,8 +299,8 @@ private function insertCoreAssets(): void
     private function insertFluencyConfigPageAssets(): void
     {
         if ($this->input->get->name === 'Fluency') {
-            $this->config->styles->add("{$this->moduleCssPath}fluency_module_config.min.css");
-            $this->config->scripts->add("{$this->moduleJsPath}fluency_module_config.bundle.js");
+            $this->config->styles->add("{$this->moduleCssPath}fluency_module_config.css");
+            $this->config->scripts->add("{$this->moduleJsPath}fluency_module_config.js");
         }
     }
 
@@ -314,8 +314,8 @@ private function insertProcessWireLanguageTranslatorAssets(): void
         }
 
         $this->config->js('fluency', $this->getClientData());
-        $this->config->styles->add("{$this->moduleCssPath}fluency_core.min.css");
-        $this->config->scripts->add("{$this->moduleJsPath}fluency_language_translator.bundle.js");
+        $this->config->styles->add("{$this->moduleCssPath}fluency_core.css");
+        $this->config->scripts->add("{$this->moduleJsPath}fluency_language_translator.js");
     }
 
     /**
@@ -326,8 +326,8 @@ private function insertProcessWireLanguageTranslatorAssets(): void
     public function insertStandaloneTranslatorAssets(): void
     {
         $this->config->js('fluency', $this->getClientData());
-        $this->config->scripts->add("{$this->moduleJsPath}fluency_standalone_translator.bundle.js");
-        $this->config->styles->add("{$this->moduleCssPath}fluency_standalone_translator.min.css");
+        $this->config->scripts->add("{$this->moduleJsPath}fluency_standalone_translator.js");
+        $this->config->styles->add("{$this->moduleCssPath}fluency_standalone_translator.css");
     }
 
     /**
@@ -338,8 +338,8 @@ public function insertStandaloneTranslatorAssets(): void
     public function insertApiUsageTableFieldsetAssets(): void
     {
         $this->config->js('fluency', $this->getClientData());
-        $this->config->scripts->add("{$this->moduleJsPath}fluency_api_usage.bundle.js");
-        $this->config->styles->add("{$this->moduleCssPath}fluency_api_usage.min.css");
+        $this->config->scripts->add("{$this->moduleJsPath}fluency_api_usage.js");
+        $this->config->styles->add("{$this->moduleCssPath}fluency_api_usage.css");
     }
 
     /**
@@ -432,6 +432,7 @@ private function getConfiguredLanguageByProcessWireId(
         return ConfiguredLanguageData::fromArray([
             'id' => $processWireId,
             'title' => $pwTitle,
+            'name' => $pwLanguage->name,
             'default' => $pwLanguage->name === 'default',
             'engineLanguage' => EngineLanguageData::fromJson($configuredLanguage),
             'isCurrentLanguage' => $pwLanguage === $userLanguage
@@ -790,7 +791,7 @@ classes: $classes,
     public function renderLanguageLinks(
         string|array|null $classes = null,
         string $id = '',
-        string $divider = null,
+        ?string $divider = null,
         ?string $activeClass = 'active',
         string $languageSource = 'fluency',
     ): string {
@@ -1192,13 +1193,13 @@ public function execute(bool $renderToString = true): InputfieldWrapper|string
 
         $this->initializeTranslationEngine();
 
-        $wrapper->import(StandaloneTranslatorFieldset::render());
+        $wrapper->import(StandaloneTranslatorFieldset::getFields());
 
         if (
             $this->translationEngineIsReady() &&
             $this->translationEngineInfo->providesUsageData
         ) {
-            $wrapper->import(ApiUsageTableFieldset::render(true));
+            $wrapper->import(ApiUsageTableFieldset::getFields(true));
         }
 
         return $renderToString ? $wrapper->render() : $wrapper;

FluencyConfig.php

@@ -362,7 +362,7 @@ public function getInputFields(): InputfieldWrapper
          */
 
         if ($this->engineInfo->providesUsageData) {
-            $inputfields->import(ApiUsageTableFieldset::render());
+            $inputfields->import(ApiUsageTableFieldset::getFields());
         }
 
         if (!$this->engineInfo->providesUsageData) {
@@ -477,7 +477,7 @@ function ($markup, $language) {
                     'notes' => 'Translations remain cached forever until this cache is cleared.',
                     'columnWidth' => 50,
                     'defaultValue' => $this->getDefaults()['translation_cache_enabled'],
-                    'description' => __('Enabling caching can help keep API usage lower and increase the speed of translation when the same content is translated more than once.'),
+                    'description' => __('Translation caching reduces API usage and increases translation speed when the same content is translated more than once.'),
                     'checkedValue' => 1,
                     'uncheckedValue' => 0
                 ],
@@ -508,7 +508,7 @@ function ($markup, $language) {
                 'translatable_languages_cache_management' => [
                     'type' => 'InputfieldMarkup',
                     'label' => __('Translatable Languages Cache Management'),
-                    'description' => __('Fluency caches the list of languages a third party supports. If a translation service introduces a language that is not available in Fluency, clear this cache.'),
+                    'description' => __('A cache of languages the translation service in use supports. Clear this cache if a translation service introduces a language that is not available in Fluency.'),
                     'collapsed' => Inputfield::collapsedNever,
                     'columnWidth' => 50,
                     'themeBorder' => 'hide',

README.md

@@ -17,13 +17,18 @@ Upgrading from earlier versions to 1.0.8 and earlier may cause errors to occur.
 
 For support and community discussion about Fluency, visit [the module thread in the ProcessWire forums](https://processwire.com/talk/topic/24567-fluency-the-complete-translation-enhancement-suite-for-processwire/).
 
+**IMPORTANT**
+
+Fluency v2.2.0 or greater is required when using DeepL as the translation service. DeepL changed their API authentication method in January of 2025 and deprecated the previous method. Translation via DeepL in versions earlier to 2.2.0 will no longer work and result in a translation service error in the UI.
+
 ## Contents
 
 - [Requirements](#requirements)
 - [Installing](#installing)
   - [Configuring](#configuring)
   - [Translation Engines](#translation-engines)
   - [Localizing Fluency](#localizing-fluency)
+  - [Theming Fluency](#theming-fluency)
   - [Upgrading or Removing](#upgrading-or-removing)
 - [Features and Usage](#features-and-usage)
   - [Translating Inputfields](#translating-inputfields)
@@ -49,6 +54,7 @@ For support and community discussion about Fluency, visit [the module thread in
 - [Hooking](#hooking)
 - [Known Issues](#known-issues)
 - [Contributing](#contributing)
+  - [Coding Standards](#coding-standards)
 - [Cost](#cost)
 - [Supporting Module Development](#supporting-module-development)
 
@@ -106,6 +112,14 @@ All text for the Fluency UI elements can be translated including messages, error
 
 All translatable texts are located in `Fluency/app/FluencyLocalization.php`
 
+### Theming Fluency
+
+Fluency is styled to match and complement AdminThemeUikit which is active by default when you install ProcessWire. It is also configured to work with AdminThemUikit v3 which adds built-in customizability for theming. When you choose a main color, or choose a custom main color, Fluency will match your theme choices.
+
+CSS for Fluency UI elements may be customized for some styles. Fluency uses [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) for values such as color in some rules.
+
+You can refrence the available custom properties that you can set values for in `Fluency/resources/css/global/ft_variables.css`
+
 ### Upgrading Or Removing
 
 Adding, upgrading, or removing Fluency from your ProcessWire application will not affect content. At most, you _may_ (but not always) need to update or reconfigure your Fluency module config. Settings are saved individually for each translation engine, so it is possible to switch between engines without losing your configurations for each.
@@ -172,7 +186,7 @@ When content in a ProcessWire field changes, Fluency italicizes and adds a green
 
 ![fluency_translation_caching](https://github.com/SkyLundy/Fluency/assets/61801600/605aa092-5f72-4eab-9593-e72724892c40)
 
-All translations are cached by default for a period of one month. This helps reduce API account usage where the same content is translated more than once and significantly increases translation speed. Caching can be toggled on/off on the Fluency module config page. The translation cache can also be manually cleared either on the module config page, via the [Fluency module API](#managing-cache), or via an AJAX request using the [Fluency admin REST API](#admin-rest-api-endpoints).
+All translations are cached indefinitely. This helps reduce API account usage where the same content is translated more than once and significantly increases translation speed. Caching may be toggled on/off on the Fluency module config page. The translation cache can also be manually cleared either on the module config page, via the [Fluency module API](#managing-cache), or via an AJAX request using the [Fluency admin REST API](#admin-rest-api-endpoints).
 
 Translation caching relies on _exact_ value matching including punctuation, spelling, and capitalization. This ensures that an exact translation is always returned accurately. Translations that contain multiple strings are cached together.
 
@@ -791,6 +805,8 @@ Note: This will only work if the language is recognized by the translation servi
 ```php
 <?php namespace ProcessWire;
 
+// /site/ready.php
+
 use Fluency\DataTransferObjects\{EngineLanguageData, EngineTranslatableLanguagesData};
 
 // Hook after Fluency gets the available languages from the DeepL API
@@ -833,10 +849,33 @@ Feature suggestions are welcome. In fact, Fluency has been made better thanks to
 
 Fluency is modular in that it contains a framework for adding additional third party services as "Translation Engines". You can choose which Translation Engine you prefer and provide the credentials to connect via their API. As this project is open source, contributions for new third party services as Translation Engines are welcome. If you would like to request a new third party service, [file an issue in the Fluency GitHub repository](https://github.com/SkyLundy/Fluency/issues)
 
-If you'd like to develop one for yourself, feel free to fork Fluency, build a new Translation Engine, and create a pull request.
+If you'd like to develop a new translation engine, feel free to fork Fluency, build a new Translation Engine, and create a pull request. Please reference
+
+Every effort has been made to make Fluency robustly documented within the code. Full docblocks with information have been added in all files. Additional docblock markup that is parsed by the ProcessWire API Explorer has been added with descriptions and example usage for all primary module methods. JavaScript files are also well documented with docblocks on each method and each object. [ProDevTools](https://processwire.com/talk/store/product/22-prodevtools/)
 
 Developer documentation for integrating third party translation services as Translation Engines is located in `Fluency/app/Engines/DEVDOC.md`. _Documentation is a work in progress_. If you need help or more information, feel free to send me a PM on the [ProcessWire forum](https://processwire.com/talk/).
 
+### Tech Stack
+
+Aside from build tools, Fluency is intentionally built without libraries and external dependencies to ensure that the module is stable long-term. Vanilla JavaScript and CSS are used exclusively. To make use of more advanced features, bundle assets, and optimize output, [Parcel](https://parceljs.org/) is used for JavaScript and CSS.
+
+CSS is processed by PostCSS to add import bundling and nested rules.
+
+**Using Parcel**
+
+In the Fluency module directory, execute the following commands in a terminal instance for development:
+
+`npm install`
+`npm run dev`
+
+To build for production execute:
+
+`npm run build`
+
+### Coding Standards
+
+Code contributins and bugfixes are welcome via pull requests. Please ensure that your PHP code adheres to [PSR-12 standards](https://www.php-fig.org/psr/psr-12/), JavaScript matches the common conventions followed in existing files, and CSS is formatted and clear.
+
 ## Cost
 
 Fluency is free to use. There is no cost for this module and it can be used on any site that you build with ProcessWire. This module is provided as a thank you to the outstanding ProcessWire community and as a contribution alongside other module developers who help everyone build great websites and applications.

app/Components/ApiUsageTableFieldset.php

@@ -14,7 +14,7 @@ class ApiUsageTableFieldset
 {
     use GeneratesFieldsetsTrait;
 
-    public static function render(bool $collapsed = false): InputfieldWrapper
+    public static function getFields(bool $collapsed = false): InputfieldWrapper
     {
         $collapsed ? Inputfield::collapsedYes : Inputfield::collapsedNever;
         $uiText = FluencyLocalization::getFor('usage');

app/Components/StandaloneTranslatorFieldset.php

@@ -14,7 +14,7 @@ class StandaloneTranslatorFieldset
 {
     use GeneratesFieldsetsTrait;
 
-    public static function render(bool $collapsed = false): InputfieldWrapper
+    public static function getFields(bool $collapsed = false): InputfieldWrapper
     {
         $fluencyConfig = (new FluencyConfig())->getConfigData();
         $modules = wire('modules');
@@ -75,7 +75,7 @@ public static function render(bool $collapsed = false): InputfieldWrapper
                         'options' => $sourceLanguageSelectOptions->options,
                         'optionAttributes' => $sourceLanguageSelectOptions->attributes,
                     ],
-                    'ft_swap_languages' => [
+                    'ft_swap_languages_markup' => [
                         'type' => 'InputfieldMarkup',
                         'label' => ' ',
                         'collapsed' => Inputfield::collapsedNever,
@@ -91,6 +91,7 @@ public static function render(bool $collapsed = false): InputfieldWrapper
                                 'name' => "swap_languages",
                                 'value' => 1,
                                 'attributes' => [
+                                    'name' => 'ft_swap_languages',
                                     'icon' => 'exchange',
                                     'class' => self::appendInputfieldClasses('InputfieldSubmit', 'js-ft-swap-languages')
                                 ]