awaitForTranslation()

The awaitForTranslation function is the primary translation method for Node.js applications using i18n-keyless. It returns translated text for a specific target language and is perfect for server-side applications, APIs, and background services.

warning

awaitForTranslation MUST be awaited to prevent 429 rate limit errors.

Function Signature

awaitForTranslation(
  text: string,
  language: Lang,
  options?: {
    context?: string;
    replace?: Record<string, string>;
    forceTemporary?: string;
    debug?: boolean;
  }
): Promise<string>

Parameters

text

type: string (required)

The text to be translated. This text serves as both the display content and the translation key.

language

type: Lang (required)

The target language code for translation. Must be one of the supported languages: "fr" | "en" | "nl" | "it" | "de" | "es" | "pl" | "pt" | "ro" | "hu" | "sv" | "tr" | "ja" | "cn" | "ru" | "ko" | "ar" | "cz".

options

type: object (optional)

Configuration object with the following optional properties:

context

type: string (optional)

Additional context to help ensure accurate translations. Useful when the same text might have different meanings in different situations.

replace

type: Record<string, string> (optional)

Object for replacing placeholders in the text with dynamic values. Common patterns: {name}, [value], %user%, etc.

forceTemporary

type: string (optional)

Override AI-generated translation with a custom one for the specified target language.

debug

type: boolean (optional)

Enable console logging for debugging translation behavior.

Basic Usage

Simple Translation

import { awaitForTranslation, type Lang } from 'i18n-keyless-node';

async function sendNotifications() {
  const users = await fetchUsers();
  
  for (const user of users) {
    const title = await awaitForTranslation(
      "Come see my app!", 
      user.lang as Lang
    );
    
    const body = await awaitForTranslation(
      "So many new features!", 
      user.lang as Lang
    );
    
    await sendNotification(user, { title, body });
  }
}

With Context

import { awaitForTranslation, type Lang } from 'i18n-keyless-node';

async function generateEmailContent(user: User) {
  const subject = await awaitForTranslation(
    "Welcome to our platform", 
    user.language as Lang,
    { context: "This is an email subject line" }
  );
  
  const greeting = await awaitForTranslation(
    "Back", 
    user.language as Lang,
    { context: "This is a back button in navigation" }
  );
  
  return { subject, greeting };
}

With Replacements

import { awaitForTranslation, type Lang } from 'i18n-keyless-node';

async function personalizedMessage(user: User) {
  const message = await awaitForTranslation(
    "Hello {name}, welcome to {platform}!", 
    user.language as Lang,
    { 
      replace: { 
        '{name}': user.name,
        '{platform}': 'i18n-keyless'
      } 
    }
  );
  
  return message;
}

Force Translation

import { awaitForTranslation, type Lang } from 'i18n-keyless-node';

async function customTranslation(targetLang: Lang) {
  const text = await awaitForTranslation(
    "Retour", 
    targetLang,
    { forceTemporary: "Go Back" }
  );
  
  return text;
}

Batch Processing

import { awaitForTranslation, type Lang } from 'i18n-keyless-node';

async function translateBatch(texts: string[], targetLang: Lang) {
  const translations = [];
  
  for (const text of texts) {
    const translated = await awaitForTranslation(text, targetLang);
    translations.push(translated);
    
    // Small delay to respect rate limits
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return translations;
}

Common Use Cases

• Email templates: Translating email subjects and content for international users
• Push notifications: Sending localized notifications to mobile app users
• API responses: Returning translated error messages and content
• Background jobs: Processing translations in queue workers or cron jobs
• Server-side rendering: Pre-translating content for specific markets
• Log messages: Creating localized log entries for international teams

Important Notes

Rate Limiting

• MUST be awaited to prevent 429 (Too Many Requests) errors
• i18n-keyless handles caching, throttling, debouncing - no worries, as long as you await
• The service has built-in rate limiting to ensure optimal performance

Error Handling

try {
  const translation = await awaitForTranslation("Hello", "fr");
  console.log(translation);
} catch (error) {
  console.error("Translation failed:", error);
  // Fallback to original text or default language
}

Related

• I18nKeyless.init() - Initialize the library
• Types - Type definitions