Hooks
HooksSubstituindo dados via hooks

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:

  • chatgpt
  • claude
  • deepseek
  • gemini
  • mistral
  • openrouter
  • self_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âmetroDescriçãoExemplo
$contentsAs strings a serem traduzidas['hello world']
$sourceLanguageCodeCódigo ISO-639 do idioma de origemen
$sourceLanguageNameNome do idioma de origem (em inglês)English
$targetLanguageCodeCódigo ISO-639 do idioma de destinofr
$targetLanguageNameNome do idioma de destino (em inglês)French
$targetCountryCodeCódigo ISO-3166 do país para localizar a traduçãoFR
$targetCountryNameNome do país (em inglês) para localizar a traduçãoFrance

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âmetroDescriçãoExemplo
$querySlugSlug da query a ser executadatranslate-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_keys
  • gatompl:translatable_meta_keys
  • gatompl:custompost_and_media_entity_reference_translatable_meta_keys
  • gatompl:taxonomy_entity_reference_translatable_meta_keys

Os hooks recebem os seguintes parâmetros:

ParâmetroDescrição
$objectA entidade sendo traduzida, do tipo WP_Post (para custom posts e mídia) ou WP_Term (para tags e categorias)
$startingMetaKeysO 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
);