Переопределение данных через хуки
В этом разделе описывается, как переопределить данные, используемые для перевода контента, с помощью PHP-хуков.
Промпты для провайдеров AI-перевода
Вы можете настроить промпты, отправляемые провайдерам AI-перевода, с помощью хуков в PHP-коде.
Доступны следующие настройки:
- Системное сообщение
- Шаблон промпта
- Промпт
Для каждого из них предусмотрены два хука:
gatompl:<hook_name>gatompl:<hook_name>:<provider_name>
Первый хук используется для изменения переменных для всех провайдеров.
Второй хук используется для изменения переменных для конкретного провайдера.
Поддерживаются следующие имена провайдеров:
chatgptclaudedeepseekgeminimistralopenrouterself_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_keysgatompl:translatable_meta_keysgatompl:custompost_and_media_entity_reference_translatable_meta_keysgatompl: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
);