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:
Parameter | Description | Example |
---|---|---|
$contents | The strings to be translated | ['hello world'] |
$sourceLanguageCode | ISO-639 code of language to translate from | en |
$sourceLanguageName | Language name (in English) to translate from | English |
$targetLanguageCode | ISO-639 code of language to translate to | fr |
$targetLanguageName | Language name (in English) to translate to | French |
$targetCountryCode | ISO-3166 code of country to localize the translation for | FR |
$targetCountryName | Country name (in English) to localize the translation for | France |
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:
Parameter | Description | Example |
---|---|---|
$querySlug | Slug of the query to execute | translate-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:
Parameter | Description |
---|---|
$object | The entity being translated, of type WP_Post (for custom posts and media) or WP_Term (for tags and categories) |
$startingMetaKeys | The 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
);