Hooks
HooksGhi đè dữ liệu qua hooks

Ghi đè dữ liệu qua hooks

Phần này mô tả cách ghi đè dữ liệu dùng để dịch nội dung thông qua các hooks PHP.

Prompt cho các nhà cung cấp dịch thuật AI

Bạn có thể tùy chỉnh các prompt gửi đến các nhà cung cấp dịch thuật AI thông qua hooks trong mã PHP.

Bạn có thể tùy chỉnh các mục sau:

  • Thông điệp hệ thống
  • Mẫu prompt
  • Prompt

Với mỗi mục, có hai hooks:

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

Hook đầu tiên dùng để sửa đổi các biến cho tất cả các nhà cung cấp.

Hook thứ hai dùng để sửa đổi các biến cho một nhà cung cấp cụ thể.

Các tên nhà cung cấp được hỗ trợ:

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

Các hooks bên dưới không nhận dữ liệu của thực thể cần dịch (ví dụ: ID bài viết, custom post type, v.v.), mà chỉ nhận mã ngôn ngữ và các chuỗi cần dịch.

Nếu bạn cần dữ liệu thực thể, bạn có thể lấy thông qua action hook gatompl:query_execution_start, như trong ví dụ này.

Vì hook được kích hoạt trước khi query được thực thi, bạn có thể lưu dữ liệu vào một biến và sử dụng nó trong bất kỳ filter hook nào bên dưới.

Thông điệp hệ thống

Thông điệp hệ thống giúp AI hiểu ngữ cảnh của bản dịch. Ví dụ:

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

Mẫu prompt

Mẫu prompt bao gồm các ký tự giữ chỗ cho biến, sẽ được giải quyết lúc chạy. Ví dụ:

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 là prompt thực tế được gửi đến dịch vụ AI, sau khi mẫu prompt đã được giải quyết. Nó bổ sung thêm thông tin để đảm bảo định dạng phản hồi là đúng. Ví dụ:

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.

Các hooks nhận các tham số bổ sung sau:

Tham sốMô tảVí dụ
$contentsCác chuỗi cần dịch['hello world']
$sourceLanguageCodeMã ISO-639 của ngôn ngữ nguồnen
$sourceLanguageNameTên ngôn ngữ nguồn (bằng tiếng Anh)English
$targetLanguageCodeMã ISO-639 của ngôn ngữ đíchfr
$targetLanguageNameTên ngôn ngữ đích (bằng tiếng Anh)French
$targetCountryCodeMã ISO-3166 của quốc gia để bản địa hóa bản dịchFR
$targetCountryNameTên quốc gia (bằng tiếng Anh) để bản địa hóa bản dịchFrance

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

Biến query

Gato AI Translations for Polylang thực thi một GraphQL query để thực hiện bản dịch. Nó truyền cấu hình (được định nghĩa trong phần Cài đặt của plugin) tới query thông qua các biến GraphQL.

Bạn có thể tùy chỉnh các biến query thông qua hook sau:

  • gatompl:query_variables

Hook nhận các tham số bổ sung sau:

Tham sốMô tảVí dụ
$querySlugSlug của query cần thực thitranslate-customposts

Danh sách các slug query được hỗ trợ có trong phần Hooks thực thi 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
);

Khóa meta

Bạn có thể tùy chỉnh các khóa meta cần đồng bộ/dịch, thông qua các hooks sau:

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

Các hooks nhận các tham số sau:

Tham sốMô tả
$objectThực thể đang được dịch, kiểu WP_Post (cho custom post và media) hoặc WP_Term (cho tag và danh mục)
$startingMetaKeysMảng các khóa meta có trong thực thể

gatompl:syncable_meta_keys

Các khóa meta để sao chép từ thực thể gốc sang thực thể đã dịch (cho bài viết, media, tag và danh mục).

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

Các khóa meta chứa chuỗi, để sao chép và dịch từ thực thể gốc sang thực thể đã dịch.

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

Các khóa meta chứa tham chiếu đến ID bài viết (tức là custom post và media), để sao chép và dịch sang ID tương ứng cho ngôn ngữ đích.

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

Các khóa meta chứa tham chiếu đến ID thuật ngữ phân loại (tức là tag và danh mục), để sao chép và dịch sang ID tương ứng cho ngôn ngữ đích.

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