Translation API Reference

This document provides detailed information about the Translation module in the Hooks API, which handles automated content translation using Google Pub/Sub and AI translation services.

Overview

The Translation module does not expose any REST API endpoints. Instead, it works exclusively through Google Pub/Sub messaging for asynchronous content translation.

Communication Channel

Topic: translation

Message Structure

Request Format

Messages sent to the translation topic should follow this format:

{
  "messageName": "casino-game-catalog",
  "data": {
    "id": "game-123",
    "sourceLanguage": "en",
    "targetLanguage": ["es", "fr", "de"],
    "targetFields": [
      {
        "targetField": "title",
        "value": "Game Title in English"
      },
      {
        "targetField": "description",
        "value": "Game description in English with details about gameplay."
      }
    ]
  }
}

Message Names

Currently supported message names:

Message Name	Description
casino-game-catalog	Translation request for casino game catalog content

Field Definitions

Casino Game Catalog Fields

Field	Description
title	Game title
description	Game description

Language Support

The Translation module supports all language codes defined in the Lang enum, including:

• English (en)
• Spanish (es)
• Portuguese (pt)
• French (fr)
• German (de)
• Italian (it)
• And other supported languages

Integration Example

The following example demonstrates how to send a translation request to the Translation module:

import { GooglePubSubProvider } from '@app/providers/googlePubSub/googlePubSub.provider';
import { TRANSLATION_TOPIC } from '@app/providers/googlePubSub/types/topic.consts';
import {
  TranslationMessageNames,
  PayloadType,
} from '@app/providers/googlePubSub/types/translation.interface';
import { CasinoGameCatalogTranslatableFields } from '@app/common/types/enums/casinoGameCatalogTranslatableFields.enum';
import { Lang } from '@app/common/types/enums/lang';

// Create a translation request payload
const catalogPayload: PayloadType<TranslationMessageNames.CASINO_GAME_CATALOG> =
  {
    id: 'game-123',
    sourceLanguage: Lang.EN,
    targetLanguage: [Lang.ES, Lang.PT, Lang.FR],
    targetFields: [
      {
        targetField: CasinoGameCatalogTranslatableFields.TITLE,
        value: 'Exciting Adventure Game',
      },
      {
        targetField: CasinoGameCatalogTranslatableFields.DESCRIPTION,
        value:
          'An exciting adventure game with amazing graphics and challenging levels.',
      },
    ],
  };

// Publish the message to the translation topic
await googlePubSubProvider.publishMessage(
  TRANSLATION_TOPIC,
  TranslationMessageNames.CASINO_GAME_CATALOG,
  catalogPayload,
);

Error Handling

• The Translation module logs errors but does not provide error responses since it operates asynchronously
• Services publishing translation requests should implement their own error handling for cases where translations may not be processed

Operational Considerations

Response Time

• Translation is performed asynchronously and may take varying amounts of time depending on:
  • The number of fields to translate
  • The number of target languages
  • The length of the text content
  • Current AI provider load

Rate Limiting

• Be aware of potential rate limits on the underlying AI translation service
• For large translation jobs, consider batching requests or implementing retry mechanisms

Best Practices

1. Content Size: Keep individual text fields under 5,000 characters for optimal translation quality
2. HTML Content: The translator can handle HTML, but ensure tags are properly balanced
3. Templates: Do not translate template variables (they will be preserved during translation)
4. Context: Provide as much context as possible in the text to improve translation quality