Substituindo dados via hooks
Esta seção descreve como substituir os dados usados para traduzir conteúdo via hooks PHP.
Prompts para provedores de tradução com IA
Você pode personalizar os prompts enviados aos provedores de tradução com IA via hooks no código PHP.
Você pode personalizar os seguintes itens:
- Mensagem do sistema
- Template de prompt
- Prompt
Para cada um deles, existem dois hooks:
gatompl:<hook_name>gatompl:<hook_name>:<provider_name>
O primeiro hook é usado para modificar as variáveis para todos os provedores.
O segundo hook é usado para modificar as variáveis para um provedor específico.
Os seguintes nomes de provedor são suportados:
chatgptclaudedeepseekgeminimistralopenrouterself_hosted_llm
Os hooks abaixo não recebem os dados da entidade a ser traduzida (ex.: ID do post, custom post type, etc.), mas apenas o código do idioma e as strings a traduzir.
Se você precisar dos dados da entidade, pode recuperá-los via action hook gatompl:query_execution_start, como neste exemplo.
Como o hook é acionado antes da execução da query, você pode armazenar os dados em uma variável e utilizá-los em qualquer um dos filter hooks abaixo.
Mensagem do sistema
A Mensagem do sistema serve para que a IA entenda o contexto da tradução. Ex.:
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;
}
);Template de prompt
O Template de prompt inclui marcadores de variáveis que serão resolvidos em tempo de execução. Ex.:
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
O Prompt é o prompt real enviado ao serviço de IA, após o template de prompt ter sido resolvido. Ele adiciona informações extras para garantir que o formato da resposta esteja correto. Ex.:
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:
- Translate the text inside the HTML tags. (eg: `<p>Hello world</p>` => `<p>Hola mundo</p>`)
- Translate the following properties inside the HTML tags: alt, title, placeholder, aria-label, aria-describedby, aria-labelledby, aria-placeholder. Do not translate any other property.
- Ensure that any double quotes (") within a translated string inside an HTML tag attribute are properly escaped by adding a backslash before them (\"), but only if they haven't been escaped already.
- Ensure that the quotes in HTML tag attributes are not escaped (eg: keep `<mark class="has-inline-color">` as is, do not convert to `<mark class=\"has-inline-color\">`).
- Ensure that slashes within HTML tags are not escaped (eg: keep `<p>Hello world</p>` as is, do not convert to `<p>Hello world<\/p>`).
Keep emojis exactly as they are, do not translate them.
Ensure that the response is encoded using UTF-8 for all characters.Os hooks recebem os seguintes parâmetros adicionais:
| Parâmetro | Descrição | Exemplo |
|---|---|---|
$contents | As strings a serem traduzidas | ['hello world'] |
$sourceLanguageCode | Código ISO-639 do idioma de origem | en |
$sourceLanguageName | Nome do idioma de origem (em inglês) | English |
$targetLanguageCode | Código ISO-639 do idioma de destino | fr |
$targetLanguageName | Nome do idioma de destino (em inglês) | French |
$targetCountryCode | Código ISO-3166 do país para localizar a tradução | FR |
$targetCountryName | Nome do país (em inglês) para localizar a tradução | 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
);Variáveis de query
Gato AI Translations for Polylang executa uma query GraphQL para realizar a tradução. Ele passa a configuração (definida nas configurações do plugin) para a query via variáveis GraphQL.
Você pode personalizar as variáveis de query via o seguinte hook:
gatompl:query_variables
O hook recebe os seguintes parâmetros adicionais:
| Parâmetro | Descrição | Exemplo |
|---|---|---|
$querySlug | Slug da query a ser executada | translate-customposts |
A lista de slugs de query suportados está disponível na seção Hooks de execução de query.
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
);Chaves meta
Você pode personalizar as chaves meta a serem sincronizadas/traduzidas, via os seguintes hooks:
gatompl:syncable_meta_keysgatompl:translatable_meta_keysgatompl:custompost_and_media_entity_reference_translatable_meta_keysgatompl:taxonomy_entity_reference_translatable_meta_keys
Os hooks recebem os seguintes parâmetros:
| Parâmetro | Descrição |
|---|---|
$object | A entidade sendo traduzida, do tipo WP_Post (para custom posts e mídia) ou WP_Term (para tags e categorias) |
$startingMetaKeys | O array de chaves meta presentes na entidade |
gatompl:syncable_meta_keys
Chaves meta para copiar da entidade de origem para a entidade traduzida (para posts, mídia, tags e categorias).
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
Chaves meta com strings, para copiar e traduzir da entidade de origem para a entidade traduzida.
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
Chaves meta com referência a IDs de posts (ou seja, custom posts e mídia), para copiar e traduzir para o ID correspondente no idioma de destino.
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
Chaves meta com referência a IDs de termos de taxonomia (ou seja, tags e categorias), para copiar e traduzir para o ID correspondente no idioma de destino.
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
);