Hooks
HooksNadpisywanie danych przez hooks

Nadpisywanie danych przez hooks

Ta sekcja opisuje, jak nadpisywać dane używane do tłumaczenia treści za pomocą hooks PHP.

Prompts dla dostawców tłumaczeń AI

Możesz dostosowywać prompts wysyłane do dostawców tłumaczeń AI za pomocą hooks w kodzie PHP.

Możesz dostosować następujące elementy:

  • Wiadomość systemowa
  • Szablon promptu
  • Prompt

Dla każdego z nich istnieją dwa hooks:

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

Pierwszy hook służy do modyfikowania zmiennych dla wszystkich dostawców.

Drugi hook służy do modyfikowania zmiennych dla konkretnego dostawcy.

Obsługiwane są następujące nazwy dostawców:

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

Poniższe hooks nie otrzymują danych encji do przetłumaczenia (np.: ID posta, custom post type itp.), lecz tylko kod języka i ciągi tekstowe do przetłumaczenia.

Jeśli potrzebujesz danych encji, możesz je pobrać za pomocą action hook gatompl:query_execution_start, jak w tym przykładzie.

Ponieważ hook jest wyzwalany przed wykonaniem query, możesz przechować dane w zmiennej i użyć ich w dowolnym z poniższych filter hooks.

Wiadomość systemowa

Wiadomość systemowa pozwala AI zrozumieć kontekst tłumaczenia. Np.:

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

Szablon promptu

Szablon promptu zawiera symbole zastępcze zmiennych, które zostaną rozwiązane w czasie wykonywania. Np.:

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 to rzeczywisty prompt wysyłany do usługi AI, po rozwiązaniu szablonu promptu. Dodaje dodatkowe informacje, aby zapewnić poprawny format odpowiedzi. Np.:

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.

Hooks otrzymują następujące dodatkowe parametry:

ParametrOpisPrzykład
$contentsCiągi tekstowe do przetłumaczenia['hello world']
$sourceLanguageCodeKod ISO-639 języka źródłowegoen
$sourceLanguageNameNazwa języka źródłowego (w języku angielskim)English
$targetLanguageCodeKod ISO-639 języka docelowegofr
$targetLanguageNameNazwa języka docelowego (w języku angielskim)French
$targetCountryCodeKod ISO-3166 kraju, dla którego lokalizowane jest tłumaczenieFR
$targetCountryNameNazwa kraju (w języku angielskim), dla którego lokalizowane jest tłumaczenieFrance

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

Zmienne query

Gato AI Translations for Polylang wykonuje query GraphQL w celu przeprowadzenia tłumaczenia. Przekazuje konfigurację (zdefiniowaną w ustawieniach wtyczki) do query za pomocą zmiennych GraphQL.

Możesz dostosować zmienne query za pomocą następującego hook:

  • gatompl:query_variables

Hook otrzymuje następujące dodatkowe parametry:

ParametrOpisPrzykład
$querySlugSlug query do wykonaniatranslate-customposts

Lista obsługiwanych slugów query jest dostępna w sekcji Hooks wykonywania 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
);

Klucze meta

Możesz dostosować klucze meta do synchronizacji/tłumaczenia za pomocą następujących hooks:

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

Hooks otrzymują następujące parametry:

ParametrOpis
$objectEncja poddawana tłumaczeniu, typu WP_Post (dla custom posts i mediów) lub WP_Term (dla tagów i kategorii)
$startingMetaKeysTablica kluczy meta obecnych w encji

gatompl:syncable_meta_keys

Klucze meta do skopiowania z encji źródłowej do przetłumaczonej encji (dla postów, mediów, tagów i kategorii).

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

Klucze meta z ciągami tekstowymi, do skopiowania i przetłumaczenia z encji źródłowej do przetłumaczonej encji.

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

Klucze meta z odwołaniem do ID postów (tj. custom posts i mediów), do skopiowania i przetłumaczenia na odpowiednie ID w języku docelowym.

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

Klucze meta z odwołaniem do ID terminów taksonomii (tj. tagów i kategorii), do skopiowania i przetłumaczenia na odpowiednie ID w języku docelowym.

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