通过钩子覆盖数据
本节介绍如何通过 PHP 钩子覆盖用于翻译内容的数据。
AI 翻译提供商的 Prompt
您可以通过 PHP 代码中的钩子自定义发送给 AI 翻译提供商的 prompt。
您可以自定义以下内容:
- 系统消息
- Prompt 模板
- Prompt
对于每一项,都有两个钩子:
gatompl:<hook_name>gatompl:<hook_name>:<provider_name>
第一个钩子用于修改所有提供商的变量。
第二个钩子用于修改特定提供商的变量。
支持以下提供商名称:
chatgptclaudedeepseekgeminimistralopenrouterself_hosted_llm
以下钩子不接收要翻译的实体数据(例如:文章 ID、自定义文章类型等),只接收语言代码和要翻译的字符串。
如果需要实体数据,可以通过动作钩子 gatompl:query_execution_start 获取,参见此示例。
由于该钩子在 Query 执行之前触发,您可以将数据存储在变量中,并在以下任意过滤器钩子中使用。
系统消息
系统消息用于让 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;
}
);Prompt 模板
Prompt 模板包含将在运行时解析的变量占位符。例如:
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
Prompt 是在 prompt 模板解析完成后发送给 AI 服务的实际 prompt。它会添加额外信息以确保响应格式正确。例如:
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
);Query 变量
Gato AI Translations for Polylang 执行 GraphQL Query 来完成翻译。它通过 GraphQL 变量将插件设置中定义的配置传递给 Query。
您可以通过以下钩子自定义 Query 变量:
gatompl:query_variables
钩子接收以下额外参数:
| 参数 | 说明 | 示例 |
|---|---|---|
$querySlug | 要执行的 Query 的 slug | translate-customposts |
支持的 Query slug 列表可在 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
);元键
您可以通过以下钩子自定义需要同步/翻译的元键:
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
);