Hooks
HooksOverriding data via hooks

Overriding data via hooks

This section describes how to override the data used for translating content via PHP hooks.

Prompts for AI translation providers

You can customize the prompts sent to AI translation providers via hooks in PHP code.

You can customize the following:

  • System message
  • Prompt template
  • Prompt

For each of these, there are two hooks:

  • gatompl:<hook_name>
  • gatompl:<hook_name>:<provider_name>

The first hook is used to modify the variables for all providers.

The second hook is used to modify the variables for a specific provider.

The following provider names are supported:

  • chatgpt
  • claude
  • deepseek
  • mistral
  • openrouter

The hooks below do not receive the entity data to translate (eg: post ID, custom post type, etc), but only the language code and strings to translate.

If you need the entity data, you can retrieve it via action hook gatompl:query_execution_start, as in this example.

As the hook is triggered before the query is executed, you can store the data in a variable and use it in any of the filter hooks below.

System message

The System message is for the AI to understand the context of the translation. Eg:

You are a language translator.

gatompl:system_message

add_filter(
  'gatompl:system_message',
  function (string $systemMessage, string $providerName): string {
    return $systemMessage;
  },
  10,
  2
);

gatompl:system_message:<provider_name>

add_filter(
  'gatompl:system_message:chatgpt',
  function (string $systemMessage): string {
    return $systemMessage;
  }
);

Prompt template

The Prompt template includes variable placeholders that will be resolved on runtime. Eg:

I'm working on internationalizing my application.
 
I've created a JSON with sentences in {$sourceLanguage}. Please translate the sentences to {$targetLanguage} from {$targetCountry}.

gatompl:prompt_template

add_filter(
  'gatompl:prompt_template',
  function (string $promptTemplate, string $providerName): string {
    return $promptTemplate;
  },
  10,
  2
);

gatompl:prompt_template:<provider_name>

add_filter(
  'gatompl:prompt_template:chatgpt',
  function (string $promptTemplate): string {
    return $promptTemplate;
  }
);

Prompt

The Prompt is the actual prompt sent to the AI service, after the prompt template has been resolved. It adds extra information to ensure the format of the response is correct. Eg:

I'm working on internationalizing my application.
 
I've created a JSON with sentences in English. Please translate the sentences to French from France.
 
If a sentence contains HTML, only translate the following properties inside the HTML tags: alt, title, placeholder, aria-label, aria-describedby, aria-labelledby, aria-placeholder.
Keep emojis exactly as they are, do not translate them.
Ensure that any double quotes (") within a translated string are properly escaped by adding a backslash before them (\"), but only if they haven't been escaped already.
Ensure that slashes within HTML tags are not escaped.
Ensure that the response is encoded using UTF-8 for all characters.

The hooks receive the following additional parameters:

ParameterDescriptionExample
$contentsThe strings to be translated['hello world']
$sourceLanguageCodeISO-639 code of language to translate fromen
$sourceLanguageNameLanguage name (in English) to translate fromEnglish
$targetLanguageCodeISO-639 code of language to translate tofr
$targetLanguageNameLanguage name (in English) to translate toFrench
$targetCountryCodeISO-3166 code of country to localize the translation forFR
$targetCountryNameCountry name (in English) to localize the translation forFrance

gatompl:prompt

add_filter(
  'gatompl:prompt',
  /**
   * @param string[] $contents The strings to be translated (eg: `['hello world', 'how are you?']`).
   */
  function (
    string $prompt,
    string $providerName,
    array $contents,
    string $sourceLanguageCode,
    string $sourceLanguageName,
    string $targetLanguageCode,
    string $targetLanguageName,
    string $targetCountryCode,
    string $targetCountryName
): string {
    return $prompt;
  },
  10,
  9
);

gatompl:prompt:<provider_name>

add_filter(
  'gatompl:prompt:chatgpt',
  /**
   * @param string[] $contents The strings to be translated (eg: `['hello world', 'how are you?']`).
   */
  function (
    string $prompt,
    array $contents,
    string $sourceLanguageCode,
    string $sourceLanguageName,
    string $targetLanguageCode,
    string $targetLanguageName,
    string $targetCountryCode,
    string $targetCountryName
): string {
    return $prompt;
  },
  10,
  8
);

Query Variables

Gato AI Translations for Polylang executes a GraphQL query to execute the translation. It passes the configuration (defined in the plugin Settings) to the query via GraphQL variables.

You can customize the query variables via the following hook:

  • gatompl:query_variables

The hook receives the following additional parameters:

ParameterDescriptionExample
$querySlugSlug of the query to executetranslate-customposts

The list of supported query slugs is available in the Query execution hooks section.

add_filter(
  'gatompl:query_variables',
  /**
   * @param array<string, mixed> $variables The variables to pass to the query.
   * @return array<string, mixed> The variables to pass to the query.
   */
  function (
    array $variables,
    string $querySlug
): array {
    return $variables;
  },
  10,
  2
);

Meta keys

You can customize the meta keys to be synced/translated, via the following hooks:

  • gatompl:syncable_meta_keys
  • gatompl:translatable_meta_keys
  • gatompl:custompost_and_media_entity_reference_translatable_meta_keys
  • gatompl:taxonomy_entity_reference_translatable_meta_keys

The hooks receive the following parameters:

ParameterDescription
$objectThe entity being translated, of type WP_Post (for custom posts and media) or WP_Term (for tags and categories)
$startingMetaKeysThe array of meta keys present in the entity

gatompl:syncable_meta_keys

Meta keys to copy from origin to translated entity (for posts, media, tags, and categories).

add_filter(
  'gatompl:syncable_meta_keys',
  /**
   * @param string[] $metaKeys
   * @param string[] $startingMetaKeys
   * @return string[]
   */
  function (array $metaKeys, WP_Post | WP_Term $object, array $startingMetaKeys): array
  {
    $metaKeysToCopy = $object instanceof WP_Post ? [
      '_myproject_meta_key_for_posts',
    ] : [
      '_myproject_meta_key_for_terms',
    ];
    return array_merge($metaKeys, array_intersect($startingMetaKeys, $metaKeysToCopy));
  },
  10,
  3
);

gatompl:translatable_meta_keys

Meta keys with strings, to copy and translate from origin to translated entity.

add_filter(
  'gatompl:translatable_meta_keys',
  /**
   * @param string[] $metaKeys
   * @param string[] $startingMetaKeys
   * @return string[]
   */
  function (array $metaKeys, WP_Post | WP_Term $object, array $startingMetaKeys): array
  {
    $metaKeysToCopy = $object instanceof WP_Post ? [
      '_myproject_meta_key_for_posts',
    ] : [
      '_myproject_meta_key_for_terms',
    ];
    return array_merge($metaKeys, array_intersect($startingMetaKeys, $metaKeysToCopy));
  },
  10,
  3
);

gatompl:custompost_and_media_entity_reference_translatable_meta_keys

Meta keys with reference to post IDs (i.e. custom posts and media), to copy and translate to the corresponding ID for the target language.

add_filter(
  'gatompl:custompost_and_media_entity_reference_translatable_meta_keys',
  /**
   * @param string[] $metaKeys
   * @param string[] $startingMetaKeys
   * @return string[]
   */
  function (array $metaKeys, WP_Post | WP_Term $object, array $startingMetaKeys): array
  {
    $metaKeysToCopy = $object instanceof WP_Post ? [
      '_myproject_meta_key_for_posts',
    ] : [
      '_myproject_meta_key_for_terms',
    ];
    return array_merge($metaKeys, array_intersect($startingMetaKeys, $metaKeysToCopy));
  },
  10,
  3
);

gatompl:taxonomy_entity_reference_translatable_meta_keys

Meta keys with reference to taxonomy term IDs (i.e. tags and categories), to copy and translate to the corresponding ID for the target language.

add_filter(
  'gatompl:taxonomy_entity_reference_translatable_meta_keys',
  /**
   * @param string[] $metaKeys
   * @param string[] $startingMetaKeys
   * @return string[]
   */
  function (array $metaKeys, WP_Post | WP_Term $object, array $startingMetaKeys): array
  {
    $metaKeysToCopy = $object instanceof WP_Post ? [
      '_myproject_meta_key_for_posts',
    ] : [
      '_myproject_meta_key_for_terms',
    ];
    return array_merge($metaKeys, array_intersect($startingMetaKeys, $metaKeysToCopy));
  },
  10,
  3
);