Hooks
HooksSobrescribir datos mediante hooks

Sobrescribir datos mediante hooks

Esta sección describe cómo sobrescribir los datos utilizados para traducir el contenido mediante hooks de PHP.

Prompts para los proveedores de traducción por IA

Puedes personalizar los prompts enviados a los proveedores de traducción por IA mediante hooks en código PHP.

Puedes personalizar lo siguiente:

  • Mensaje del sistema
  • Plantilla de prompt
  • Prompt

Para cada uno de ellos hay dos hooks:

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

El primer hook se usa para modificar las variables para todos los proveedores.

El segundo hook se usa para modificar las variables para un proveedor concreto.

Los siguientes nombres de proveedor están soportados:

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

Los hooks de abajo no reciben los datos de la entidad a traducir (p. ej.: ID de la entrada, custom post type, etc.), sino únicamente el código de idioma y las cadenas a traducir.

Si necesitas los datos de la entidad, puedes obtenerlos a través del hook de acción gatompl:query_execution_start, como en este ejemplo.

Como el hook se dispara antes de ejecutar la consulta, puedes almacenar los datos en una variable y utilizarlos en cualquiera de los hooks de filtro de abajo.

Mensaje del sistema

El Mensaje del sistema sirve para que la IA entienda el contexto de la traducción. Por ejemplo:

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

Plantilla de prompt

La Plantilla de prompt incluye marcadores de variable que se resolverán en tiempo de ejecución. Por ejemplo:

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

El Prompt es el prompt real enviado al servicio de IA, una vez resuelta la plantilla de prompt. Añade información extra para garantizar que el formato de la respuesta sea correcto. Por ejemplo:

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.

Los hooks reciben los siguientes parámetros adicionales:

ParámetroDescripciónEjemplo
$contentsLas cadenas a traducir['hello world']
$sourceLanguageCodeCódigo ISO-639 del idioma desde el que traduciren
$sourceLanguageNameNombre del idioma (en inglés) desde el que traducirEnglish
$targetLanguageCodeCódigo ISO-639 del idioma al que traducirfr
$targetLanguageNameNombre del idioma (en inglés) al que traducirFrench
$targetCountryCodeCódigo ISO-3166 del país para localizar la traducciónFR
$targetCountryNameNombre del país (en inglés) para localizar la traducciónFrance

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

Variables de la consulta

Gato AI Translations for Polylang ejecuta una consulta GraphQL para realizar la traducción. Pasa la configuración (definida en los Ajustes del plugin) a la consulta mediante variables de GraphQL.

Puedes personalizar las variables de la consulta mediante el siguiente hook:

  • gatompl:query_variables

El hook recibe los siguientes parámetros adicionales:

ParámetroDescripciónEjemplo
$querySlugSlug de la consulta a ejecutartranslate-customposts

La lista de slugs de consulta soportados está disponible en la sección Hooks de ejecución de consultas.

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

Claves meta

Puedes personalizar las claves meta a sincronizar/traducir mediante los siguientes 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

Los hooks reciben los siguientes parámetros:

ParámetroDescripción
$objectLa entidad que se está traduciendo, de tipo WP_Post (para custom posts y multimedia) o WP_Term (para etiquetas y categorías)
$startingMetaKeysEl array de claves meta presentes en la entidad

gatompl:syncable_meta_keys

Claves meta a copiar desde la entidad de origen a la entidad traducida (para entradas, multimedia, etiquetas y categorías).

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

Claves meta con cadenas, a copiar y traducir desde la entidad de origen a la entidad traducida.

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

Claves meta con referencia a IDs de entrada (es decir, custom posts y multimedia), a copiar y traducir al ID correspondiente para el 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

Claves meta con referencia a IDs de términos de taxonomía (es decir, etiquetas y categorías), a copiar y traducir al ID correspondiente para el 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
);