钩子
钩子通过钩子覆盖数据

通过钩子覆盖数据

本节介绍如何通过 PHP 钩子覆盖用于翻译内容的数据。

AI 翻译提供商的 Prompt

您可以通过 PHP 代码中的钩子自定义发送给 AI 翻译提供商的 prompt。

您可以自定义以下内容:

  • 系统消息
  • Prompt 模板
  • Prompt

对于每一项,都有两个钩子:

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

第一个钩子用于修改所有提供商的变量。

第二个钩子用于修改特定提供商的变量。

支持以下提供商名称:

  • chatgpt
  • claude
  • deepseek
  • gemini
  • mistral
  • openrouter
  • self_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 的 slugtranslate-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_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
);