Хуки
ХукиПереопределение данных через хуки

Переопределение данных через хуки

В этом разделе описывается, как переопределить данные, используемые для перевода контента, с помощью PHP-хуков.

Промпты для провайдеров AI-перевода

Вы можете настроить промпты, отправляемые провайдерам AI-перевода, с помощью хуков в PHP-коде.

Доступны следующие настройки:

  • Системное сообщение
  • Шаблон промпта
  • Промпт

Для каждого из них предусмотрены два хука:

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

Первый хук используется для изменения переменных для всех провайдеров.

Второй хук используется для изменения переменных для конкретного провайдера.

Поддерживаются следующие имена провайдеров:

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

Приведённые ниже хуки не получают данные о переводимой сущности (например: ID записи, тип записи и т. д.), а только код языка и строки для перевода.

Если вам нужны данные сущности, вы можете получить их через хук действия gatompl:query_execution_start, как в этом примере.

Поскольку хук срабатывает до выполнения запроса, вы можете сохранить данные в переменную и использовать их в любом из фильтрующих хуков ниже.

Системное сообщение

Системное сообщение помогает AI понять контекст перевода. Например:

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

Шаблон промпта

Шаблон промпта включает заполнители переменных, которые будут подставлены во время выполнения. Например:

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

Промпт

Промпт — это фактический промпт, отправляемый AI-сервису после подстановки значений в шаблон. Он добавляет дополнительную информацию для обеспечения корректного формата ответа. Например:

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.

Хуки получают следующие дополнительные параметры:

ПараметрОписаниеПример
$contentsСтроки для перевода['hello world']
$sourceLanguageCodeКод ISO-639 языка, с которого выполняется переводen
$sourceLanguageNameНазвание языка (на английском), с которого выполняется переводEnglish
$targetLanguageCodeКод ISO-639 языка, на который выполняется переводfr
$targetLanguageNameНазвание языка (на английском), на который выполняется переводFrench
$targetCountryCodeКод ISO-3166 страны для локализации переводаFR
$targetCountryNameНазвание страны (на английском) для локализации перевода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
);

Переменные запроса

Gato AI Translations for Polylang выполняет GraphQL-запрос для осуществления перевода. Конфигурация (заданная в настройках плагина) передаётся в запрос через переменные GraphQL.

Вы можете настроить переменные запроса с помощью следующего хука:

  • gatompl:query_variables

Хук получает следующие дополнительные параметры:

ПараметрОписаниеПример
$querySlugСлаг выполняемого запросаtranslate-customposts

Список поддерживаемых слагов запросов доступен в разделе Хуки выполнения запросов.

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

Мета-ключи

Вы можете настроить мета-ключи для синхронизации/перевода с помощью следующих хуков:

  • gatompl:syncable_meta_keys
  • gatompl:translatable_meta_keys
  • gatompl:custompost_and_media_entity_reference_translatable_meta_keys
  • gatompl:taxonomy_entity_reference_translatable_meta_keys

Хуки получают следующие параметры:

ПараметрОписание
$objectПереводимая сущность типа WP_Post (для произвольных записей и медиафайлов) или WP_Term (для тегов и категорий)
$startingMetaKeysМассив мета-ключей, присутствующих в сущности

gatompl:syncable_meta_keys

Мета-ключи для копирования из исходной сущности в переведённую (для записей, медиафайлов, тегов и категорий).

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

Мета-ключи со строками для копирования и перевода из исходной сущности в переведённую.

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

Мета-ключи со ссылками на ID записей (то есть произвольных записей и медиафайлов) для копирования и перевода в соответствующий ID для целевого языка.

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

Мета-ключи со ссылками на ID терминов таксономии (то есть тегов и категорий) для копирования и перевода в соответствующий ID для целевого языка.

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