module Fluency - The complete translation enhancement suite for ProcessWire

[bernhard]

Hm. Really appreciate your work on this! Thank you very much. But as much as I understand and agree with this:

18 hours ago, FireWire said:

I like this implementation because it will provide a good location for possible future features as well without crowding UI for fields.

I really don't think that it is intuitive for users to look for the "wipe all" at the opposite direction of the button that does the same thing when filling fields ("translate to all").

My point is: We all understand the necessity of deleting all fields. And we might think of it when we need to reset a field. But the average user? Do you really think he/she will clear the text field, then head over to the translation icon, then click clear all?

I think what will happen is that he/she clears the field (deletes "Home" in your screenshot), hit's save and doesn't even think of deleting it in other languages. Maybe if he/she does, then I think it's more likely that he/she will look for it where he/she always looks for it. Below the field where it says "translate to all". In our project that's what everybody really got used to. Fill in the field, hit translate, hit save.

I honestly and strongly think that the "delete all" feature/button should be close to the "translate all" button.

I get your point about a cluttered UI, but what if a button to "delete all" only appeared if one of the non-default languages are filled and the default language get's cleared out? It would not clutter the UI, it would appear as the user clears the default language value and it would probably remind the user to also clear the other language's values.

What I could also think of is something like this:

Here I'd see the challenge to differentiate between users that case where someone wants to only delete this languages value or all languages values.

Another idea would be to instead of this:

18 hours ago, FireWire said:

Show a popup as soon as the default language value gets deleted that shows something like: "Delete the content of all other languages as well? Cancel / OK"

Please don't hurry with a solution and take your time 🙂 I think a big part of making this feature as useful as possible is not only about providing a way to do it but also about showing/reminding the user that going this way might be necessary (to not end up with orphaned content).

[FireWire]

7 hours ago, bernhard said:

Please don't hurry with a solution and take your time

I sketched my ideas to come back and share them with the people who suggested the feature and I haven't worked on any true implementation yet.  I can assure you there's no rush, I wanted to get some feedback before diving in and coding everything. If I had made a decision in private, programmed everything, then come back and announced the new changes it would be far more work to change my approach if it had a negative reception.

Luckily the custom header actions are 20 lines of code and aren't a commitment.

[FireWire]

@bernhard I wasn't able to provide a more robust response above but I wanted to mention that my concept wasn't an impulsive decision. I think my language in the confirmation popup should be changed. The "clear all" feature is a shortcut to clear all content in all languages including the default language so that it has one purpose.

One of the things that I first had to consider was how often the feature gets used. Fluency has been available for over 5 years and this feature absolutely has great value but hasn't been mentioned before. I haven't heard about users/devs expressing a need to clear all content from multilanguage fields, and the general practice has been in my experience that if content changes then it would involve entering new content and re-translating. I thought about weighing how often the feature would be used compared to translation and it seemed like much less often, but I didn't have experience to go on.

I also wondered if this was a feature that was use most during the initial build and population of content vs. ongoing content management. I think that was another area where the use of the feature may change over time as far as how often it's used, but again I haven't had the need so my understanding may be limited there.

I'm not against the concept of a always-visible button or icon. Throughout the admin UI the trash icon is, as far as I can tell, mainly implemented for block, group, or object deletion rather than field contents. This is where the use of the trash icon without a label to explain the difference between what it means when used specifically for a field could be confusing because it does break from what it signifies elsewhere.

The position of the translation action menu to the right as a clickable option felt natural with destructive actions located elsewhere. Placing it under a dedicated language icon menu seemed like it would strongly associate the action exclusively with multilanguage field features.

Each field can have translation disabled, so there would have to be a decision whether to include just a trash icon even if there is no translation enabled for consistency when working with multilanguage fields. I think this could be a great convenience enhancement even if it steps outside of Fluency's current purpose and may be even be necessary for consistency.

11 hours ago, bernhard said:

Show a popup as soon as the default language value gets deleted that shows something like: "Delete the content of all other languages as well? Cancel / OK"

This may present another challenge because only multilanguage fields would provide the ability to delete content from the primary field that is visible where all other fields that only have primary content would need to manually be deleted. It's a step that may push a little further into ProcessWire's core behavior because some fields enable you to delete content for the default language alone, but other fields that are not multi-lingual still require a select-all-then-delete action by the user. If the trash icon is not present on all fields, would it seem like an oversight?

Another thing that comes to mind is whether a multilanguage field with translation disabled were next to a single language field. On the left you can delete the primary content without deleting any other language, but on the right you can't delete the primary content with one click. The tabs hint that it's related to language fields, but non-language fields aren't afforded the same convenience even though they are visually similar to the end user.

11 hours ago, bernhard said:

Do you really think he/she will clear the text field, then head over to the translation icon, then click clear all?

The intention is to have the clear all button clear everything in one action, so if the user is aware of the feature then they wouldn't clear any text to begin with. I think the language I used in my original "confirm" example may not have been as descriptive as it should be. It's an all-or-nothing action. The wording you used: "Are you sure you want to clear content in all languages for this field?" is much better and communicates clearly.

So my approach was placing the option under an action menu since it felt natural to group secondary behaviors. The button that opens the translator is secondary and the ability to delete content in all languages is secondary compared to the primary feature of translation.

I like the ideas and want to take the best approach, and I'm not against any specific implementation. Thinking through this though when you originally mentioned stepping into "core" behavior may be more impactful than it seemed when putting all different types of fields into the mix.

[bernhard]

16 hours ago, FireWire said:

I sketched my ideas to come back and share them with the people who suggested the feature and I haven't worked on any true implementation yet.  I can assure you there's no rush, I wanted to get some feedback before diving in and coding everything. If I had made a decision in private, programmed everything, then come back and announced the new changes it would be far more work to change my approach if it had a negative reception.

Luckily the custom header actions are 20 lines of code and aren't a commitment.

Thx. No offence. Just tried to say no hurry from my side for a solution. Thx for considering it seriously.

8 hours ago, FireWire said:

One of the things that I first had to consider was how often the feature gets used. Fluency has been available for over 5 years and this feature absolutely has great value but hasn't been mentioned before.

My guess is that

1. Many don't provide feedback
2. Many didn't even realise
3. If they did, they didn't think of accusing the UI for it but thought, "oh, I need to remember next time to wipe all fields"

Just guesses, of course.

In my project we have a multisite setup where we clone one site and then change the content afterwards. This might have made the issue more obvious, but I think it does not mean that it's not an issue on regular sites. Another detail why it popped up now is that the client was doing all the content editing on her own. If I had been the one to edit the site, the issue might have never popped up, because I would have thought (3) from above.

The reason why I reported it as issue is because my project will hopefully be used by other clients as well and every detail matters, because when done wrong it either means bad results on the frontend (content showing up on a different language that should not be there) or more support from my side.

8 hours ago, FireWire said:

This may present another challenge because only multilanguage fields would provide the ability to delete content from the primary field that is visible where all other fields that only have primary content would need to manually be deleted.

True, but I really don't see a problem here. My main point is to make the user not forget to wipe the translations as well. On a single-language field it's totally fine to just delete the content and save.

8 hours ago, FireWire said:

The intention is to have the clear all button clear everything in one action, so if the user is aware of the feature then they wouldn't clear any text to begin with. I think the language I used in my original "confirm" example may not have been as descriptive as it should be. It's an all-or-nothing action. The wording you used: "Are you sure you want to clear content in all languages for this field?" is much better and communicates clearly.

Same as above: If the user thinks of it, no problem. But I doubt he/she does.

I also thought that it might be good to have another indicator on the language tabs to show when they are filled while the default tab is empty. Maybe in red? Color blind people wouldn't be able to see it though. Maybe something like this:

Field when empty:

Field when filled in all languages and the default language gets cleared out:

Non-default language tab with an empty default language tab:

Or maybe a bit more compact using a tooltip:

It's a tabler trash icon which looks a bit different than the regular fontawesome trash icon anywhere else in the admin:

<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><!-- Icon from Tabler Icons by Paweł Kuna - https://github.com/tabler/tabler-icons/blob/master/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 7h16M5 7l1 12a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2l1-12M9 7V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v3m-5 5l4 4m0-4l-4 4"/></svg>

The orange warning could pop up whenever the main language value is cleared out. Then the user can decide to either

• enter the new field value and hit "translate to all".
  In that case the warning would also be beneficial as it reminds the user of hitting "translate to all" after entering the new text as well. win win
• hit "clear content for non-default languages"

PS: I think it should probably be a core feature...

PPS: I think it would also be good to remind the user of translating the content if he/she entered/changed the content of the main language. Something like this: 

Ok now I realise that the user might also want to change the main language and then wipe all other languages, so the "clear content of non-default languages" should maybe appear whenever the main language was changed (either to empty or something else) and any other language is not empty

[monollonom]

I feel like this is something the editor should know / be told about — the same way editing a page’s title doesn’t automatically update its name — and not something so prominently shown (adding a new button).

At first I was thinking of a hook checking for a change in the main language and then adding a message to the Inputfield indicating they might want to update the other languages as well, something like this:

But then I thought it could be more subtle / embedded within Fluency’s UI, maybe the button’s text could be "Translation Available" when idle, "Translate to all languages" when main language is changed (non-empty) and "Clear all languages" when the main language is cleared / empty AND the other languages have a value (otherwise, default to "Translation Available"):

[bernhard]

11 minutes ago, monollonom said:

I feel like this is something the editor should know / be told about — the same way editing a page’s title doesn’t automatically update its name — and not something so prominently shown (adding a new button).

I'm almost always configuring my templates to automatically update the page name based on the title 😉 

11 minutes ago, monollonom said:

Yeah, nice! But still, my point is to make it more obvious to the user to not forget to translate. I always test these things with my mother and this is eye-opening from time to time! 😄 She can not type blindly. So she types, then looks up on the screen. I bet a lot that she would not realise the change from "translate to all languages" to "clear all languages" after she typed or hit backspace.

I updated my post with some new screenshots of mockups. 

11 minutes ago, monollonom said:

I like it because it would be obvious but it would also cause the UI to jump around because it moves the input down. I tried to avoid that with where I placed the ui elements.

[monollonom]

15 minutes ago, bernhard said:

I always test these things with my mother and this is eye-opening from time to time!

Mothers are the best beta-testers haha.

Maybe the change in the copy is indeed too subtle, but in that case maybe I’d go with your proposal of the Trash icon and the tooltip, shown when you cleared the main language. But like you said in this case this is more related to core than Fluency.

[FireWire]

Hey @bernhard & @monollonom I didn't forget about you, just hammering out some work. Taking notes from your great input. I appreciate it!

Will be back when I escape from programming prison 🤣

[bernhard]

Ok great we have some positive feedback from ryan as well. He'd be willing to improve that detail in the core as well:

Quote

For that situation, the way I usually do it is to click that little icon on the right side that opens all of the inputs at once. Though it is admittedly a rare need. But I'm sure it could be made even simpler. 

 

Maybe a confirm box that pops up and says "Do you want to clear this field in all languages?". Maybe another option would be that it ignores translated values (at page render time) if the default language value is blank?

Didn't think about the page render option before... What do you guys think? At first I thought it might be exactly one would need, but it might also be exactly the opposite. Maybe someone wants to have the default value blank, but other language values non-blank.

Didn't have a good example for that, but I think I have one: What if we are on a website that shows events taking place in Vienna. The default language of the website is german. So for the german version of the website it's just showing the event title and details.

But for the non-german website it might show "this event will be in german". Ok thinking about it further I'd probably add a select field then on each event to choose the language and then add that logic to the template code.

Anyhow. Wanted to mention that and wanted to provide ryan with some good suggestions that he can easily add to the core.

Happy about your input

[bernhard]

On 3/31/2025 at 10:40 AM, bernhard said:

Looking at that mockup again I was a little confused... I think it should better say "clear content in all languages" ?

[FireWire]

@bernhard I really like this direction with adding something next to the languages, it makes a lot of sense and does a good job showing the relationship between the button to what it does.

The only concern I have is that on fields with smaller widths a larger tab size will cause some crowding next to the language tabs and cause wrapping. Example would be the description fields for images. Real world example for me:

If it could be a little more minimal it would fit in a lot of places, especially if there are many languages. Experimenting with an alternate "X" style icon to differentiate it from the trash icon used to delete blocks, groups, pages, etc.

Hover state

On 3/30/2025 at 6:30 AM, bernhard said:

"Delete the content of all other languages as well? Cancel / OK"

A popup with a similar message would confirm both the intention and purpose of the button. Perhaps "Delete content in all languages for this field? Cancel/OK". A "delete all" action would prevent having to first manually remove the contents of the default language then click to delete the contents for all other languages.

A tooltip would show "Delete content for this field in all languages". With both a tooltip and confirm popup the user would see, understand, and remember its purpose when editing content anywhere in the admin. Thoughts?

[monollonom]

15 hours ago, bernhard said:

Didn't think about the page render option before... What do you guys think?

I don’t think it’s good to assume something like no default language = no languages at all.

With a button the action is truly delibarate and I think the same as @FireWire that it would be best to keep it as an icon only + tooltip + confirm message to manage space. Which icon though... 😅

Using/tweaking the style of PageListActions:

But even with a small string like “Clear all” I’m already picturing it will be too much if you have a bunch of multi-languages fields in the page, so more like:

Ideally this should be in consideration / thought through with the new design @ryan is currently implementing. So thanks for bringing this up to him @bernhard!

[bernhard]

15 hours ago, FireWire said:

1 hour ago, monollonom said:

I like both suggestions a lot 🙂 So a final question would be where to show it if all language tabs are expanded. I'd probably hide it then?

[Mike-it]

Error on a Fresh new installation: ProcessWire: Translation rate limit exceeded, please wait then try again.

I recently came across this error which I really cannot explain...  

After trying with my usual API keys (well below the monthly limit) i also tried with new API  relying on a new fresh account, but it returns the same error...

On another site same api keys everything works correctly... The only difference is the Process Wire version.
Any ideas? 

PhP 8.1 All requirements fulfilled.
ProcessWire 3.0.246 (error site)
ProcessWire 3.0.229 (No Error site with Fluency)

The error occurs post selection of the translation engine and related API key input

[FireWire]

@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.

[bernhard]

Hey @FireWire just wanted to let you know that the "Click To Translate All" feature bit me in my ** today 🙂 It would be great to have an "Click To Translate All Empty" option, because I had the UI open like this:

So I clicked "translate all" and boom both fields have been translated.

I thought.

But actually it also translated some of my other 57 fields on that page and I didn't realise!

This can be a quite destructive operation, so it would be great if you could prioritise this issue if possible 🙂 Thx a lot!

PS: I wanted to provide a PR as the task seemed quite simple but Fluency has some quite complex JS setup that I don't understand and that involves a lot of tools I'm not using (babel/gulp) 🤯😅

[snck]

On 5/23/2025 at 9:49 AM, Mike-it said:

Error on a Fresh new installation: ProcessWire: Translation rate limit exceeded, please wait then try again.

I recently came across this error which I really cannot explain...  

After trying with my usual API keys (well below the monthly limit) i also tried with new API  relying on a new fresh account, but it returns the same error...

On another site same api keys everything works correctly... The only difference is the Process Wire version.
Any ideas? 

PhP 8.1 All requirements fulfilled.
ProcessWire 3.0.246 (error site)
ProcessWire 3.0.229 (No Error site with Fluency)

The error occurs post selection of the translation engine and related API key input

@Mike-it Have you found a solution? I am experiencing the same problem on 3.0.246.

[FireWire]

@snck The issue may be related to the solution I suggested. He didn't respond after my suggestion so it is a good place to start troubleshooting. Please check this first:

On 5/23/2025 at 11:03 AM, FireWire said:

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.

Please report back if this doesn't fix your issue.

@bernhard I've got a hard Friday deadline for a project but as soon as I can get time after that I will work on that improvement. Sorry for the wait, didn't want you to think I forgot about you 👍

[snck]

1 hour ago, FireWire said:

@snck The issue may be related to the solution I suggested. He didn't respond after my suggestion so it is a good place to start troubleshooting. Please check this first:

Please report back if this doesn't fix your issue.

@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!"}]}%

[FireWire]

@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.

 

[snck]

@FireWire Thank you!

I tried that.

I get the following dumps:

The arrays list the available languages:

The request that returns null has status code 429:

[FireWire]

1 minute ago, snck said:

The request that returns null has status code 429:

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.

[snck]

@FireWire No, never used Fluency or the DeepL API before. The account has been created today, the key is fresh and I could successfully use it with curl from the shell without problems. I do not really understand the goal of the requests that are made on the settings page.

As I get status 200 for 3 times, the connection to the API looks fine to me. This looks like requests 2 and 4 are identical (same endpoint, data and method). As they are made immediately after another a rate limit error is to be expected. What is the outcome or behaviour you would expect?

[FireWire]

@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]

@FireWire Thank you so much for your explanation and patience. I got four requests every time I loaded the settings page. I uninstalled the module, reinstalled it, entered the same settings, saved them (2 times) and out of a sudden it worked. I am able to configure the languages and translate. Great experience so far! 👍

One quick observation: I am using @bernhard's RockPageBuilder. In a gallery block that contains multiple images (Pageimages field) I wanted to translate the descriptions. Translating them works as expected (translation is shown in the field), but after saving (clicking Save button or pushing Return key) the field is empty again (translation gone). If I change the field's value (before or after translating), the translation is saved as expected. I noticed that whenever I manually change something in the description field, .InputfieldStateChanged class is added to the inputfield wrapper (#wrap_Inputfield_rpb_gallery_images_repeater1613 in this case), but not if I just click the Translate link. I suspect that the change in the description field is somehow not detected correctly and not saved in consequence? Maybe there is a way for Fluency to trigger the detection of that change?