Troubleshooting
TroubleshootingCommon issues

Common issues

If the translation doesn't go through, check the cause of the issue.

Here are some known issues.

The API returns an error

The API service may fail at processing the request, for their own reasons.

For instance, DeepSeek might return error "Unsuccessful request: POST https://api.deepseek.com/chat/completions resulted in a 200 OK response'".

Claude may return the error "Server error: POST https://api.anthropic.com/v1/messages resulted in a 529 response:\n{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"Overloaded\"}}"

Whenever any of these happens, you can then trigger the translation again (eg: via the Bulk Actions), until it works.

Tags/categories/media items are not being synced

Most likely those tags/categories/media items are not translated yet.

When translating a post, all tags, categories, and media items must have been translated in advance, so that the translated post can be assigned the corresponding translated tag/category/featured image.

Simply translate all your existing tags/categories/media via Bulk Actions and trigger the post translation again.

WordPress becomes slow or even unresponsive

Executing a request to the translation API can be slow.

For instance, DeepSeek Reasoner is particularly slow. Translating a very long Classic Editor-based post (in the order of 50.000 characters) can take over 15 min.

Here are some way to handle this:

  1. Trigger the translation only when nobody else is working on the webserver.
  2. Switch to a faster API provider: Whereas DeepSeek Reasoner might take 15 min, translating an equally-long post with ChatGPT or Claude might take around 5 min.
  3. Trigger the translation when the API is not busy.

Memory issues

If you get an error message like this:

PHP Fatal error: Allowed memory size of 268435456 bytes exhausted (tried to allocate 20480 bytes)
in /public/wp-content/plugins/gato-ai-translations-for-polylang/vendor/pop-schema/extended-schema-commons/src/HelperServices/ArrayOrJSONObjectTraversionHelperService.php on line 75

...it means that the PHP server has run out of memory.

That may happen when translating many posts at once, for multiple languages.

Make sure your PHP server has enough memory.

To increase the max memory limit in WordPress, you can add the following code to the wp-config.php file:

if ( !defined('WP_MEMORY_LIMIT') ) {
  define( 'WP_MEMORY_LIMIT', '1G' ); // 1GB
}
if ( !defined('WP_MAX_MEMORY_LIMIT') ) {
  define( 'WP_MAX_MEMORY_LIMIT', '1G' ); // 1GB for admin dashboard
}

Translating a long Classic Editor-based post fails

Translating a long Classic Editor-based post might fail when using an API that offers a small number of max tokens (eg: DeepSeek V3 offers only 8K max tokens).

The reason is that the Classic Editor contains a single blob of HTML content to translate. If this string is longer than the number of max tokens, then it can't be sent over the request.

You will then see the following error message in the logs:

🔴 ERROR [Query "translate-customposts"] Execution with errors: String to translate exceeds max length of '...': ...

As solution, you can:

  • Switch to an API service that offers a higher number of max tokens
  • Switch to the Gutenberg editor, migrating the single HTML content to multiple Gutenberg html blocks, where each block does not exceed 8000 characters

Posts based on the Gutenberg editor are organized via blocks, and the block properties can be translated independently. As the multitude of strings is split into multiple requests, it doesn't matter if the post is long.

The format for the translated post is different than the original

Quite likely, the post is based on a theme, plugin, or page builder that adds meta to that post.

For instance, Elementor adds meta entry "_elementor_template_type" => "page".

To fix it, you must synchronize all these additional meta entries, so they are also copied to the translated post.

You can do that under Settings > Meta Configuration, and specifying the meta keys to synchronize.

Avoiding timeouts in the PHP server

The request sent to the AI service's API includes as many strings to translate as possible. The longer the request, the more time will the API take to process it.

A slow response may produce a timeout on your PHP server (eg: if the max time for executing a PHP script is 30 seconds).

To avoid a timeout, you can:

  • Increase the max execution time on the PHP configuration
  • Reduce the payload size sent to the API in the plugin settings

When reducing the payload size, the request will be split into multiple requests, each of which will be resolved faster.

Go to Settings > Service Configuration > [AI service], and set the Max request payload length option to an adequate number of characters that will avoid a timeout error:

Setting the 'Max request payload length' option
Setting the 'Max request payload length' option

Reaching the rate limits

When translating to multiple languages, some APIs (such as Claude) may return a 429 Too Many Requests rate limit error.

If possible, you can increase the rate limits on the API service to solve the issue.

Otherwise, you can go to Setting > Plugin Configuration > Translation Options, and set the Use parallel multi-language translation? option to Sequential (slower):

Setting the 'Use parallel multi-language translation?' option to 'Sequential (slower)'
Setting the 'Use parallel multi-language translation?' option to 'Sequential (slower)'

The requests will then be sent one by one, so that the rate limits are not exceeded.

Unexpected string escaped character '&'

If you see this error message:

Unexpected string escaped character '&'

...like here:

{"message":"Unexpected string escaped character '&'","locations":[{"line":2596,"column":87}],"extensions":{"code":"gqlparser@4","specifiedBy":"https://spec.graphql.org/draft/#sec-Language"}}

The solution is: deactivate and reactivate the plugin.

After you do so, if you have any DB cache plugin, you must also flush the DB cache.

Explanation of the issue

The source of the issue is that GraphQL query "translate-customposts" has been stored erroneously in the database.

It seems to happen only the first time the plugin is installed, and only if the license had been provided in advance, so this error is very rare.

For some reason (that escapes to us), WordPress may corrupt the content of the query when storing it.

Even though the original query reads this:

    @underJSONObjectProperty(
      by: { key: "coreMediaTextAlt" }
      affectDirectivesUnderPos: [1, 6]
    )
      @underJSONObjectProperty(
        by: { key: "from" }
        affectDirectivesUnderPos: [1, 4],
      )
        @underEachJSONObjectProperty
          @underEachArrayItem(
            passValueOnwardsAs: "value"
          )
            @applyField(
              name: "_sprintf",
              arguments: {
                string: "#(<!-- wp:media-text .*?-->\\n?<div .*><figure .*><img .*?alt=\\\")%s(\\\")#",
                values: [$value]
              },
              setResultInResponse: true
            )
        @export(
          as: "coreMediaTextAltReplacementsFrom",
        )
      @underJSONObjectProperty(
        by: { key: "to" }
      )
        @export(
          as: "coreMediaTextAltReplacementsTo",
        )

...WordPress stores it in the DB like this:

    @underJSONObjectProperty(
      by: { key: "coreMediaTextAlt" }
      affectDirectivesUnderPos: [1, 6]
    )
      @underJSONObjectProperty(
        by: { key: "from" }
        affectDirectivesUnderPos: [1, 4],
      )
        @underEachJSONObjectProperty
          @underEachArrayItem(
            passValueOnwardsAs: "value"
          )
            @applyField(
              name: "_sprintf",
              arguments: {
                string: "#(<!-- wp:media-text .*?-->\\n?<div><figure>&lt;img .*?alt=\\\&quot;)%s(\\\&quot;)#&quot;,
                values: [$value]
              },
              setResultInResponse: true
            )
        @export(
          as: &quot;coreMediaTextAltReplacementsFrom&quot;,
        )
      @underJSONObjectProperty(
        by: { key: &quot;to&quot; }
      )
        @export(
          as: &quot;coreMediaTextAltReplacementsTo&quot;,
        )

When disabling and re-enabling the plugin, the query is re-saved in the database, and the issue is fixed.