Hooks
HooksSovrascrivere i dati tramite hooks

Sovrascrivere i dati tramite hooks

Questa sezione descrive come sovrascrivere i dati utilizzati per tradurre i contenuti tramite hooks PHP.

Prompt per i provider di traduzione tramite IA

Puoi personalizzare i prompt inviati ai provider di traduzione tramite IA con hooks nel codice PHP.

Puoi personalizzare i seguenti elementi:

  • Messaggio di sistema
  • Modello di prompt
  • Prompt

Per ognuno di essi esistono due hooks:

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

Il primo hook serve a modificare le variabili per tutti i provider.

Il secondo hook serve a modificare le variabili per un provider specifico.

Sono supportati i seguenti nomi di provider:

  • chatgpt
  • claude
  • deepseek
  • gemini
  • mistral
  • openrouter
  • self_hosted_llm

Gli hooks qui sotto non ricevono i dati dell'entità da tradurre (es.: ID dell'articolo, custom post type, ecc.), ma solo il codice della lingua e le stringhe da tradurre.

Se hai bisogno dei dati dell'entità, puoi recuperarli tramite l'action hook gatompl:query_execution_start, come in questo esempio.

Poiché l'hook viene attivato prima dell'esecuzione della query, puoi memorizzare i dati in una variabile e utilizzarli in uno qualsiasi dei filter hooks qui sotto.

Messaggio di sistema

Il Messaggio di sistema serve a far comprendere all'IA il contesto della traduzione. Es.:

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;
  }
);

Modello di prompt

Il Modello di prompt include segnaposto per le variabili che verranno risolti in fase di esecuzione. Es.:

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

Il Prompt è il prompt effettivo inviato al servizio di IA, una volta risolto il modello di prompt. Aggiunge informazioni supplementari per garantire che il formato della risposta sia corretto. Es.:

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.

Gli hooks ricevono i seguenti parametri aggiuntivi:

ParametroDescrizioneEsempio
$contentsLe stringhe da tradurre['hello world']
$sourceLanguageCodeCodice ISO-639 della lingua di origineen
$sourceLanguageNameNome della lingua di origine (in inglese)English
$targetLanguageCodeCodice ISO-639 della lingua di destinazionefr
$targetLanguageNameNome della lingua di destinazione (in inglese)French
$targetCountryCodeCodice ISO-3166 del paese per cui localizzare la traduzioneFR
$targetCountryNameNome del paese (in inglese) per cui localizzare la traduzioneFrance

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
);

Variabili di query

Gato AI Translations for Polylang esegue una query GraphQL per effettuare la traduzione. Trasmette la configurazione (definita nelle impostazioni del plugin) alla query tramite variabili GraphQL.

Puoi personalizzare le variabili di query tramite il seguente hook:

  • gatompl:query_variables

L'hook riceve i seguenti parametri aggiuntivi:

ParametroDescrizioneEsempio
$querySlugSlug della query da eseguiretranslate-customposts

L'elenco degli slug di query supportati è disponibile nella sezione Hooks di esecuzione delle 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
);

Chiavi meta

Puoi personalizzare le chiavi meta da sincronizzare/tradurre tramite i seguenti 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

Gli hooks ricevono i seguenti parametri:

ParametroDescrizione
$objectL'entità in fase di traduzione, di tipo WP_Post (per i custom post e i media) o WP_Term (per i tag e le categorie)
$startingMetaKeysL'array delle chiavi meta presenti nell'entità

gatompl:syncable_meta_keys

Chiavi meta da copiare dall'entità di origine all'entità tradotta (per articoli, media, tag e categorie).

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

Chiavi meta con stringhe, da copiare e tradurre dall'entità di origine all'entità tradotta.

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

Chiavi meta con riferimento a ID di articoli (cioè custom post e media), da copiare e tradurre nell'ID corrispondente per la lingua di destinazione.

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

Chiavi meta con riferimento a ID di termini di tassonomia (cioè tag e categorie), da copiare e tradurre nell'ID corrispondente per la lingua di destinazione.

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
);