Search the Community

Hello community! I want to share a new module I've been working on that I think could be a big boost for multi-language ProcessWire sites. Fluency is available in the ProcessWire Modules Directory, via Composer, and on Github Some background: I was looking for a way for our company website to be efficiently translated as working with human translators was pretty laborious and a lack of updating content created a divergence between languages. I, and several other devs here, have talked about translation integrations and the high quality services now available. Inspired by what is possible with ProcessWire, I built Fluency, a third-party translation service integration for ProcessWire. With Fluency you can: Translate any plain textarea or text input Translate any TinyMCE or CKEditor (inline, or regular) Translate page names/URLs Translate in-template translation function wrapped strings Translate modules, both core and add-ons Installation and usage is completely plug and play. Whether you're building a new multi-language site, need to update a site to multi-language, or simply want to stop manually translating a site and make any language a one-click deal, it could not be easier to do it. Fluency works by having you match the languages configured in ProcessWire to those offered by the third party translation service you choose. Currently Fluency works with DeepL and Google Cloud Translation. Module Features Translate any multilanguage field while editing any page. Translate fields in Repeater, Repeater Matrix, Table, Fieldset Page, Image descriptions, etc. Translate any file that added in the ProcessWire language pages. It's possible to translate the entire ProcessWire core in ~20 minutes Provide intuitive translation features that your clients and end-users can actually use. Fluency is designed for real-world use by individuals of all skill levels with little to no training. Its ease-of-use helps encourage users to adopt a multilanguage workflow. Start for free, use for free. Translation services supported by Fluency offer generous free tiers that can support regular usage levels. Fluency is, and will always be, free and open source. Use more than one Translation Engine. You may configure Fluency to use either DeepL, Google Cloud Translation, or both by switching between them as desired. AI powered translations that rival humans. DeepL provides the highest levels of accuracy in translation of any service available. Fluency has been used in many production sites around the world and in commercial applications where accuracy matters. Deliver impressive battle-tested translation features your clients can count on. Disable translation for individual fields. Disable translation for multilanguage fields where values aren't candidates for translation such as phone numbers or email addresses Configure translation caching. Caching can be enabled globally so that the same content translated more than once anywhere in ProcessWire doesn't count against your API usage and provides lightning fast responses. Set globally ignored words and text. Configure Fluency to add exclusionary indicators during translation so that specific words or phrases remain untranslated. This works either for specific strings alone, or present in other content while remaining grammatically correct in translation. Choose how translation is handled for fields. Configure Fluency to have buttons for either "Translate from {default language}" on each tab, or "Translate To All Languages" to populate every language for a field from any language to any language you have configured. No language limits. Configure as few or as many languages as you need. 2, 5, 10, 20 language website? Absolutely possible. If the translation service you choose offers a language, you can use it in ProcessWire. When new languages are introduced by third parties, they're ready to use in Fluency. Visually see what fields and language tabs have modified content. Fluency adds an visual indication to each field language tab to indicate which has different content than when opening the edit page. This helps ensure that content updated in one language should be updated in other languages to prevent content divergence between languages. Render language meta tags and ISO codes. Output alt language meta tags, add the current language's ISO code to your <html lang=""> attribute to your templates that are automatically generated from accurate data from the third party translation service. Build a standards-compliant multi-language SEO ready page in seconds with no additional configuration. Render language select elements. - Fluency can generate an unordered list of language links to switch between languages when viewing your pages. You can also embed a <select> element with JS baked in to switch between languages when viewing your pages. Render it without JS to use your own. Manage feature access for users. Fluency provides a permission that can be assigned to user roles for managing who can translate content. Track your translation account usage. View your current API usage, API account limit, and remaining allotment to keep an eye on and manage usage. (Currently only offered by DeepL) Use the global translation tool. Fluency provides translation on each field according to the languages you configure in ProcessWire. Use the global translation tool to translate any content to any language. Use Fluency from your templates and code. All translation features, usage statistics, cache control, and language data are accessible globally from the $fluency object. Perform any operation and get data for any language programmatically wherever you need it. Build custom AJAX powered admin translation features for yourself. Fluency provides a full RESTful API within the ProcessWire admin to allow developers to add new features for ProcessWire applications powered by the same API that Fluency uses. Robust plain-language documentation that helps you get up to speed fast. Fluency is extremely easy to use but also includes extensive documentation for all features both within the admin and for the Fluency programming API via the README.md document. The module code itself is also fully annotated for use with the ProDevTools API explorer. Is and will always be data safe. Adding, upgrading, or removing Fluency does not modify or remove your content. ProcessWire handles your data, Fluency sticks to translating. Full module localization. Translate Fluency itself to any language. All buttons, messages, and UI elements for Fluency will be presented in any language you choose for the ProcessWire admin. Built for expansion. Fluency provides translation services as modular "Translation Engines" with a full framework codebase to make adding new translation services easier and more reliable. Contributions for new translation services are welcome. Fluency is designed and built to provide everything you need to handle incredibly accurate translations and robust tools that make creating and managing multi-language sites a breeze. Built through research on translation plugins from around the web, it's the easiest and most friendly translation implementation for both end users and developers on any CMS/CMF anywhere. Fluency complements the built-in first class language features of ProcessWire. Fluency continues to be improved with great suggestions from the community and real-world use in production applications. Big thanks to everyone who has helped make Fluency better. Contributions, suggestions, and bug reports welcome! Please note that the browser plugin for Grammarly conflicts with Fluency (as it does with many web applications). To address this issue it is recommended that you disable Grammarly when using Fluency, or open the admin to edit pages in a private window where Grammarly may not be loaded. This is a long-standing issue in the larger web development community and creating a workaround may not be possible. If you have insight as to how this may be solved please visit the Github page and file a bugfix ticket. Requirements: ProcessWire 3.0+ UIKit Admin Theme That's Fluency in a nutshell. The Module Is Free This is my first real module and I want to give it back to the community as thanks. This is the best CMS I've worked with (thank you Ryan & contributors) and a great community (thank you dear reader). DeepL Developer Accounts In addition to paid Pro Developer accounts, DeepL now offers no-cost free accounts. All ProcessWire developers and users can use Fluency at no cost. Learn more about free and paid accounts by visiting the DeepL website. Sign up for a Developer account, get an API key, and start using Fluency. Download You can install Fluency by adding the module to your ProcessWire project using any of the following methods. Method 1: Within ProcessWire using 'Add Module From Directory' and the class name Fluency Method 2: Via Composer with composer require firewire/fluency Method 3: Download from the Github repository and unzip the contents into /site/modules/ Feedback File issues and feature requests here (your feedback and testing is greatly appreciated): https://github.com/SkyLundy/Fluency/issues Thank you! ¡Gracias! Ich danke Ihnen! Merci! Obrigado! Grazie! Dank u wel! Dziękuję! Спасибо! ありがとうございます！ 谢谢你

Hi there, I got now the response in log file of Fluence 2.1.1: Engine: DeepLEngine /Error: AUTHENTICATION_FAILED /Message: Legacy authentication method 'query parameter' is no longer supported. Please update to header-based authentication. Find more details in our docs: https://developers.deepl.com/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods. You can find more info in our docs: https://developers.deepl.com/docs/getting-started/auth /Response: {"message":"Legacy authentication method 'query parameter' is no longer supported. Please update to header-based authentication. Find more details in our docs: https:\/\/developers.deepl.com\/docs\/resources\/breaking-changes-change-notices\/november-2025-deprecation-of-legacy-auth-methods. You can find more info in our docs: https:\/\/developers.deepl.com\/docs\/getting-started\/auth"} Then I updated the codebase of Fluency module 2.3.0, API credentials of DeepL are still there, using the Free account type of Deepl. But now I got the error message by Fluency: An unknown error occurred while querying the translation service. Please try again later And no further Log file entries. Modules are already refreshed. Does someone has any idea what might be reason?

@lpa Apologies for the late reply, I got sick and was off my feet (and keyboard) for a little while there. Are you still having this issue? If so, are you seeing any errors in the browser developer tools console? Did you make any change to your languages? Can you clear the translation cache and see if that changes anything? I can't reproduce this, I'm using Fluency 2.3.0 in production and having no issues. That query parameter error is impossible with 2.2.0+ <?php // Line 217 in DeepLEngine.php $requestUrl = "{$this->apiUrl}{$endpoint}"; // <- This used to have a query parameter for the API key anything earlier than 2.2.0 will have it // Line 227 "Authorization: DeepL-Auth-Key {$this->apiKey}", // This is the header authentication now required and added in 2.2.0 It's not possible to get an API key parameter error because Fluency will never send a request with an API key parameter. It's possible there's a DeepL issue? No idea. Fluency 2.1.1 should fail. 2.1.1 on local may be working if you have translation cache enabled and it's not actually making API calls to DeepL. Just a guess This is hard to diagnose because the errors don't make sense...

Hello all! There's a new version of Fluency and a critical update announcement for all DeepL users. Fluency 2.2.0 has just been released and is a critical update for all users of Fluency that employ DeepL as their translation service. As mentioned above, DeepL is deprecating their previous method of API authentication on January 15, 2025. This means that all Fluency versions less than 2.2.0 that are using DeepL will no longer translate content. Upgrading from Fluency 1.8.0 or earlier requires a complete uninstall/reinstall. The module will have to be configured again, so note your API key if you don't have access to it otherwise. This will not result in any content loss. Fluency 2.2.0 also brings additional features and bugfixes. These include compatibility with AdminThemUikit v3 and its theming customization abilities. Fluency also now uses CSS custom properties so it is possible to customize it separately. This release also includes a fix for an issue that may affect saving content in RockPageBuilder fields mentioned earlier in this thread. For full notes on changes and improvements see the Github release page. If you have any trouble with the module please report them here, filing an issue on Github is helpful as well. Thank you all for your feedback and ongoing support. Additional thanks to the developers who have donated via PayPal, always appreciated!

Quick announcement. DeepL is enforcing a new authentication method when making API calls that deprecates how previous methods were used. You may have received an email from DeepL notifying you of this change, if your clients have a DeepL account of their own to power the translation on their site they may have received this notification. This is the authentication method that Fluency uses (and was the only option available for a long time). The deprecated authentication method will no longer work on January 15th 2026 onward, which means that the current and and all past versions of Fluency will stop working and an API error will be shown when attempting to translate content. Fluency will be ready. I am working on updating the module to adhere to the new requirements and it will be ready ahead of the January 15th cutoff. This means that the Fluency modules you have installed for yourself and clients will need to be updated. I just received the email notifying me a couple of days ago and this is much shorter notice than usual for a deprecation of a critical API component. Unfortunately we have to work with what we have as far as time. It isn't ideal, but again, Fluency will be ready with weeks to spare and an update will be available as soon as possible. Stay tuned for more information and an update on the module release. Thanks and if you have any questions feel free to respond and tag me!

Not sure who would be the best person to reach out for help on this but there's a critical update for my module, Fluency, and getting the word out is not possible because the thread is locked and hidden from everyone but me. I edited my original post last week (IIRC), which I've done before, and I didn't know that this hid it, which hasn't happened before. This is a bit odd given how old my forum account is and reputation 🤔 I'm attempting to let all Fluency module users know that there is a critical update that must be installed for all users that are using DeepL as their translation service or all translation services will fail with an error. This is due to a short-notice breaking change by DeepL stating that they're deprecating their previously documented authentication method on January 15th, 2026. If you're reading this and use Fluency, please update your module installs to version 2.2.0 which now available via a ProcessWire admin module upgrade, the modules directory, Github, and Composer. I pushed the update as soon as I could to give ProcessWire devs as much time as possible to update their installs and those of their clients. Thanks to whomever sees and can/does unlock the thread!

Btw, it might be something with DeepL. On my localhost with Fluency 2.1.1 and the same API Credentials, the translation works fine, just not on live server. It might be fixed after some timeouts.

@robert – yes line 118 is private static function convertGlossaryStringToArray(string $glossaryString = ''): array { – I'm afraid i don't know what and where the language-specific translate_glossary field is 🙂 – using DeepL API Free UPDATE: ahhh, I updated from an very old version and didn't know that you have to add fields to the language template. Trying now to find out how to edit a language template. UPDATE: my fault. You have to uninstall and reinstall the module. Then the new fields are added to your language templates. Thanks again!

@ngrmmHmm, that might be possible, but unfortunately I can't replicate the issue here. Could you double-check that TranslateGlossary.php:118 has a default value for the $glossaryString parameter in the source code? The line should look like this: private static function convertGlossaryStringToArray(string $glossaryString = ''): array { Also, a few questions to help investigate: – Do you have any entries in your language-specific translate_glossary field? – Are you using the DeepL API Free or Pro plan? Thanks for helping with the investigation! 😅

@robert thanks! I updated to 1.3 and still getting the same error. Is this maybe related to my empty DeepL Glossary ID field?

@update AG Thanks for reporting. I pushed a new version 1.3 to Github which supports PHP 8.1. The DeepL API client uses Symfony HTTP Client as a dependency, which requires PHP 8.2 in version 7.x. I downgraded it to Symfony 6.x, so now PHP 8.1 is the minimum supported version. Regarding ProcessWire compatibility with PHP 8.2: I checked client websites and found one installation running PW 3.0.230 without any errors/warnings, and another with 3.0.213 that has some deprecation warnings but works fine. Edit: I forgot to mention that Fluency is no longer necessary for ProcessTranslatePage to run, both modules work independently.

Our PW-Version: 3.0.229, PHP-Version: 8.1 Is it correct that the latest version (v1.1.0) needs PHP 8.2 to work? If so it would perhaps be good if you update the requirements of your module to include that. Last week we updated the Fluency module from v0.3.2 to v2.2.0 to make it work because of Deepl API Changes. For that to work we needed to update the PHP Version from 8 to 8.1. We also had your Module (ProcessTranslatePage) installed in Version 0.8 but that version somehow doesn't work anymore with Fluency v2.2.0 (We get the error Fatal Error: Uncaught TypeError: Cannot access offset of type string on string in /site/modules/ProcessTranslatePage/ProcessTranslatePage.module.php:188 Stack trace). So we thought we should just use the latest version of your module (v1.1.0) but found out today after installing that it needs PHP 8.2 (Error: Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.2.0". You are running 8.1.33.). Do you perhaps by chance know if PW-Version 3.0.229 is suitable to work with PHP 8.2? KR Orkun

Hi Ivan, I haven’t had time yet to verify what (if anything) needs to be done on my side, but I’m fairly sure ProcessTranslatePage already uses the DeepL API v2. It relies on the official PHP client library and was updated in mid‑2025, so we should be in good shape. If any updates are required to keep the module working, I’ll take care of them – thanks for the heads up!

Good day, @robert! Thanks for the module! @FireWire has updated Fluency for DeepL API v. 2.0 which uses different authentication method. Could you please write if ProcessTranslatePage has already done that in v. 1.0? If not are you planning to update?

Perhaps the module can better communicate this in some way. I'll think about ways to possibly remind superadmins if translation is not fully ready. Google has more languages, DeepL has a few extra features. The extra features in DeepL have defaults that you only need to change if you really want to, so no additional configuration. I prefer the translations from DeepL, but Google is a good alternative to have because of their language selection. I've had some challenges with this myself. I usually create a dev key that is unrestricted for development since I know that it won't be used anywhere else and a separate API key for production where the IP address will be stable and the setup is more permanent. No problem at all.

Maybe we can extend the site-wide search to include the body / description of modules as well, be it with less priority? This is an example of a use case: I knew a module exists that uses DeepL to translate site content, but when I searched for DeepL I got 0 results: https://processwire.com/search/?q=DeepL. However, DeepL gets mentioned 5 times in the body of this module page. It was only until I tried searching for terms like 'Translate' that I could find this module. Edit: there is another module that I missed and in my opinion should have popped up.

@snck The purpose of the requests on the config page are to confirm that your API key works by making an API request to get the available languages. The only time that it will make 4 API calls on the config page is when you are first entering your API credentials. After you have entered valid credentials it will only make 2 API calls when you load the module config page. This hasn't ever been an issue before so I'm very curious why you are seeing a 429 but others haven't. Here's some additional details on why you are seeing 2 or 4 API calls for languages in Fluency when using DeepL: Fluency needs to know what languages a service allows you to translate from and what languages you can translate to. Google Cloud Translate will give you this information in 1 API call. DeepL requires you to make two API calls, one for source languages and one for target languages. Fluency is built with a modular architecture so that new translation services can be added easily. If you're interested you can compare DeepLEngine.php with GoogleCloudTranslationEngine.php. Each have the same methods that return the same data type but how it gets that data is entirely internal. To see what I mean about the 2 API calls vs 1 API call compare the getLanguages() method in each of those. 2 API calls is technically just one execution of the getLanguages() function. You should only see 4 API calls when: You first enter your API credentials and hit save You change translation engines You entered incorrect credentials and have to re-enter them After that it should only be 2 when using DeepL in Fluency. Back to your issue- 4 API calls shouldn't cause a 429. The DeepL team states that API calls should be limited to 50 requests per second. That comment is in an issue in their Node library, but the limits should still apply for all API usage. I just removed my credentials and re-added them without any issues. Are you seeing 4 API calls every time you load or save the module config page? I have to ask the obligatory security question- is there any chance that your credentials are being used by someone else or were compromised? I know that you said that you just created your API key today but you would have to be absolutely hammering the DeepL API to get a 429. I've never seen it during regular usage and it hasn't come up here in the forums by anyone who has been using the module for years. This is a tough issue to crack especially since it's happening for you but not me at the same time. Let me know if there's any additional info you can share.

@snck That may be a gamble... I think I've seen some situations where DeepL responses aren't very descriptive beyond the HTTP code that they return which can be frustrating. Unfortunately when I test my API key (free) I'm getting translations successfully. In your case the only way to get "Translation rate limit exceeded" is if DeepL returns an HTTP 429 code so that is another message that Fluency is relaying to you from DeepL and not originating with anything in the module. Whether the HTTP 429 applies in your case, I don't know. You may want to check the API key type that you have and ensure that it is valid for making translation requests. If you would like to see what DeepL is responding with directly and you aren't afraid to dig into some code then you can dump the response at L252 in DeepLEngine.php. Because the translations are made via AJAX in ProcessWire, you'll have to use the developer tools in your browser to view the response after clicking the translate button for a field. If you're using Tracy then adding bd() is the best way to see the result in your browser. Sorry I can't be of more help, there have been some instances in this thread where people have had some hiccups with DeepL. It doesn't happen very often and when you find the cause/solution for your issue here it should be smooth sailing.

That would be nice. To be honest, I never use forums or website search. By default, I just fire up Google. My usual suspects are /talk /blog /docs site:processwire.com/ deepl site:processwire.com/talk deepl site:processwire.com/blog languages site:processwire.com/docs $page

@bernhard Apologies for the delay! I've pushed updates to the dev branch. I had a few changes that were already going into the next version that I had to do some extra testing for and a lot of housekeeping. Let me know if this works as well for you as it did me and I'll push another version to main https://github.com/SkyLundy/Fluency/tree/development New feature that some may be interested in- adding DeepL languages for translation that are technically supported by their API but not delivered by the languages endpoint yet. You can read more about when that happens and why on this DeepL documentation page. To manually define languages in Fluency that are supported for translation, you can use a hook. This will make the language available both within the global translation tool as well as available for configuration with a ProcessWire language on the module config page. <?php namespace ProcessWire; // ready.php use Fluency\DataTransferObjects\{EngineLanguageData, EngineTranslatableLanguagesData}; // Hook after Fluency gets the available languages from the DeepL API wire()->addHookAfter('Fluency::getTranslatableLanguages', function (HookEvent $e) { // $e->return is an instance of EngineTranslatableLanguageData // The `languages` property returns an array of EngineLanguageData objects $languages = $e->return->languages; // Create a new data object, define the values according to the API docs, add it to the original languages array $languages[] = EngineLanguageData::fromArray([ 'sourceName' => __('Arabic'), 'sourceCode' => 'AR', 'targetName' => __('Arabic'), 'targetCode' => 'AR', 'meta' => [ 'supports_formality' => false, // This is determined by DeepL, check to see if it's available in their API docs ], ]); // Instantiate a new EngineTranslatableLanguageData object with the language array then assign it to the return value $e->return = EngineTranslatableLanguagesData::fromArray([ 'languages' => $languages ]); }); @Hari KT This is a new method supported by Fluency to add Arabic to Fluency before DeepL lists it for translation. Thank you for inspiring a solution with your Github issue on languages not being available in Fluency. This is available on the dev branch of the Fluency repo if you would like to help test it out @ryangorley This will address the issue you had with Traditional Chinese, albeit a lot later than may be useful for you, but the hook above can be modified to resolve that problem. I'm surprised how long the language had been listed as "available soon" on their API documentation 🤷‍♂️ I would have gone this route sooner had I known there was some documentation about this, I don't think it existed at the time.

Hmm I was about to test it, on the specific customer project, who had that problem and now I'm hit on the Problem in the plugin configuration screen. So Fluency will not more let me connect the languages from ProcessWire to the DeepL one, and so I can not test it. Sorry. If it helps, the TranslatePage (via DeepL) - Plugin on the other hand, has no problems with the same API-Key.

@Mike-it some steps: Double check that you've picked the correct "Free" or "Pro" subscription type on the module config page. This is an issue with a DeepL account, API key, or a Free/Pro setting. If you receive that error again, next to the "check credentials" there is a +2, click on the chevron-down and see what the additional message is that may be hidden. There is only one place in the module that can return that error message and it is based on the HTTP response status. So in that case, DeepL is indeed returning an HTTP 403 and Fluency is just relaying the information. The error message you're seeing is the "polite" message from Fluency. Any errors returned by a translation service are logged so there may be a more specific message in the fluency-engine log if DeepL provided one.

Yeah, that's DeepL returning 429 as your error and nothing as the response body. I'm at a loss on how to diagnose that. Have you been able to translate content successfully in the past? Have you used up your allowable number of translated characters? This is going to have to be something on the DeepL side and I don't know if there's anything I can do to help out. Like I mentioned, I just translated using my API key and things are working alright.

@FireWire Thanks! I had already checked that. I picked "Free" (which is correct) and inserted a valid API key that has never been used before. I only get the "Translation rate limit exceeded, please wait then try again" error (see below). The fluency-engine logs show the following message: Engine: DeepLEngine /Error: RATE_LIMIT_EXCEEDED /Message: No Message /Response: null Is there any other place where I could look for more verbose information? I tested the API key and made sure it is correct: curl -X POST 'https://api-free.deepl.com/v2/translate' -H 'Authorization: DeepL-Auth-Key [MY API KEY]' -d 'text=Hello%2C%20world!' -d 'target_lang=DE' {"translations":[{"detected_source_language":"EN","text":"Hallo, Welt!"}]}%

It was within the class that I tested it, and I did get an error when using that snippet in a template. However, happy to confirm the mistake was my own. I started a completely fresh site to test it, and was using Google Cloud. Clearly the first time I didn't notice the popup in the module settings telling me that authentication had failed 🤦‍♂️ I assumed Google just had less functionality than DeepL and therefore less configuration. I'm not sure why I regularly run into this issue, but when restricting the API key in Cloud Console to website URLs, it seems a bit unreliable. Or maybe it just doesn't work with local addresses. Of course, nothing to do with your module, which I'm happy to say is working now and looks great. Sorry to have troubled you with it!