الترجمة المباشرة باستخدام Gemini Live API

تتيح واجهة برمجة التطبيقات Gemini Live API ترجمة الكلام في الوقت الفعلي بين أكثر من 70 لغة باستخدام نموذج gemini-3.5-live-translate-preview. من خلال ضبط Live API باستخدام إعدادات الترجمة، يمكنك بث الصوت بلغة معيّنة وتلقّي مصدر إخراج الصوت مترجَمًا بلغة أخرى، ما يتيح ترجمة سلسة من صوت إلى صوت في الوقت الفعلي.

الفرق بين ميزة "الرد المباشر على المكالمات الهاتفية" وميزة "الترجمة المباشرة"

مع أنّ كلتا الميزتَين تستخدمان واجهة Live API، يختلف النموذج الذهني لميزة "الترجمة المباشرة" عن التفاعلات الحوارية في الوقت الفعلي مع الوكيل.

موظّف دعم يقدّم خدمة مباشرة الترجمة المباشرة
يعمل النموذج كمساعد. يستمع إليك، ويفكّر، ويتّخذ إجراءات نيابةً عنك. يعمل النموذج كمترجم. وهي تعمل كمسار ترجمة في الوقت الفعلي.
تستخدِم تفاعلات بالتناوب. تعتمد على التوقف المؤقت ورصد النية وتتعامل مع المقاطعات. استخدام معالجة البث المستمر: تترجم الميزة الكلام أثناء تحدث المتحدث بدون انتظار دوره.
يتوافق مع الأدوات وموظفي الدعم إتاحة ميزة "استدعاء الدوال" و"بحث Google" و"التعليمات" بشكلٍ مدمج يتيح هذا التطبيق الترجمة فقط. الترجمة بوقت استجابة منخفض جدًا بدون دعم للأدوات أو التعليمات
متعدد الوسائط بالكامل: يتيح إدخال النصوص والمقاطع الصوتية والفيديوهات والصور. تم حظر الصوت. يقتصر الإدخال على الصوت لضمان الالتزام الصارم بحدود زمن الاستجابة في الوقت الفعلي.
الإعدادات الدقيقة: تستخدم هذه النماذج إنشاء المحتوى والكلام والأدوات وتعليمات النظام. إعدادات مبسّطة: اضبط target_language_code وعناصر التحكّم مثل echo_target_language.

البدء

توضّح الأمثلة التالية كيفية تهيئة عميل والاتصال بواجهة Live API باستخدام إعدادات الترجمة.

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client()

model = "gemini-3.5-live-translate-preview"
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    translation_config=types.TranslationConfig(
        target_language_code="pl",
        echo_target_language=True
    )
)

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started with translation")
        # Start receiving the translated audio stream
        async for response in session.receive():
            if response.server_content:
                if response.server_content.input_transcription:
                    print(f"Input transcript: {response.server_content.input_transcription.text}")
                if response.server_content.output_transcription:
                    print(f"Output transcript: {response.server_content.output_transcription.text}")
                if response.server_content.model_turn:
                    for part in response.server_content.model_turn.parts:
                        if part.inline_data:
                            audio_data = part.inline_data.data
                            # Play or process the translated audio chunk
                            print(f"Received audio chunk ({len(audio_data)} bytes)")

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.5-live-translate-preview';
const config = {
    responseModalities: [Modality.AUDIO],
    inputAudioTranscription: {},
    outputAudioTranscription: {},
    translationConfig: {
        targetLanguageCode: 'pl',
        echoTargetLanguage: true
    }
};

async function main() {
  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: {
      onopen: () => console.debug('Opened'),
      onmessage: (message) => {
        const content = message.serverContent;
        if (content?.inputTranscription) {
          console.log('Input transcript:', content.inputTranscription.text);
        }
        if (content?.outputTranscription) {
          console.log('Output transcript:', content.outputTranscription.text);
        }
        if (content?.modelTurn?.parts) {
          for (const part of content.modelTurn.parts) {
            if (part.inlineData) {
              const audioData = part.inlineData.data;
              // Play or process the translated audio chunk (base64 encoded)
              console.debug(`Received audio chunk (${audioData.length} bytes)`);
            }
          }
        }
      },
      onerror: (e) => console.debug('Error:', e.message),
      onclose: (e) => console.debug('Close:', e.reason),
    },
  });

  console.debug("Session started with translation");
}

main();

WebSockets

const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.5-live-translate-preview";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;

const websocket = new WebSocket(WS_URL);

websocket.onopen = () => {
  console.log('WebSocket Connected');

  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      generationConfig: {
        responseModalities: ['AUDIO'],
        inputAudioTranscription: {},
        outputAudioTranscription: {},
        translationConfig: {
          targetLanguageCode: 'pl',
          echoTargetLanguage: true
        }
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  if (response.serverContent) {
    const content = response.serverContent;
    if (content.inputTranscription) {
      console.log('Input transcript:', content.inputTranscription.text, `(${content.inputTranscription.languageCode})`);
    }
    if (content.outputTranscription) {
      console.log('Output transcript:', content.outputTranscription.text, `(${content.outputTranscription.languageCode})`);
    }
    if (content.modelTurn?.parts) {
      for (const part of content.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data;
          // Play or process the translated audio chunk (base64 encoded)
          console.debug(`Received audio chunk (${audioData.length} bytes)`);
        }
      }
    }
  }
};

إرسال الصوت

لبث الإدخالات الصوتية بغرض الترجمة، عليك إرسال صوت PCM أولي بتنسيق little-endian وبدقة 16 بت.

  • تنسيق الصوت المُدخَل: تنسيق PCM الأولي بمعدّل 16 بت عند 16 كيلوهرتز (أحادي، little-endian).
  • تنسيق الصوت الناتج: PCM خام بمعدل 16 بت عند 24 كيلوهرتز (أحادي، little-endian)
  • حجم الأجزاء ووقت الاستجابة: إرسال الصوت في أجزاء تبلغ مدتها 100 ملي ثانية

توضّح الأمثلة التالية كيفية إرسال أجزاء من الصوت إلى الجلسة.

Python

# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)

JavaScript

// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});

WebSockets

// Assuming 'chunk' is a Buffer of raw PCM audio
function sendAudioChunk(chunk) {
  if (websocket.readyState === WebSocket.OPEN) {
    const audioMessage = {
      realtimeInput: {
        audio: {
          data: chunk.toString('base64'),
          mimeType: 'audio/pcm;rate=16000'
        }
      }
    };
    websocket.send(JSON.stringify(audioMessage));
  }
}

التهيئة

لتفعيل الترجمة، يجب تحديد translationConfig ضمن generationConfig أثناء إعداد الجلسة.

إعدادات رسائل الإعداد

يتيح generationConfig الحقول التالية لتفعيل النصوص:

  • inputAudioTranscription: عنصر يتيح للنموذج، عند توفّره، إرسال نصوص صوتية للمحتوى الصوتي المُدخَل.
  • outputAudioTranscription: عنصر يتيح للنموذج، عند توفّره، إرسال نصوص صوتية (مترجمة) للمحتوى الصوتي الناتج.

تتيح translationConfig استخدام الحقول التالية:

  • استبدِل targetLanguageCode برمز اللغة BCP-47 الذي تريد أن يترجم النموذج إليه (مثل "pl" للغة البولندية أو "es" للغة الإسبانية). القيمة التلقائية هي "en".
  • echoTargetLanguage: قيمة منطقية تشير إلى كيفية التعامل مع الصوت الذي تم إدخاله والموجود أصلاً باللغة المستهدَفة. إذا تم ضبطها على true، سيعيد النموذج صدى (محاكاة) الصوت المُدخَل الذي يكون باللغة المستهدَفة. إذا تم ضبطها على false، سيظل النموذج صامتًا عندما يكون الكلام المُدخَل باللغة المستهدَفة. القيمة التلقائية هي false.

في ما يلي مثال على بنية رسالة الإعداد:

"setup": {
    "model": "models/gemini-3.5-live-translate-preview",
    "generationConfig": {
      "responseModalities": [
        "AUDIO"
      ],
      "inputAudioTranscription": {},
      "outputAudioTranscription": {},
      "translationConfig": {
        "targetLanguageCode": "pl",
        "echoTargetLanguage": true
      }
    }
}

استخدام الرموز المميزة المؤقتة في التطبيقات من جهة العميل

بالنسبة إلى التطبيقات التي تتواصل بين العميل والخادم، يمكنك استخدام الرموز المميزة المؤقتة (المتوفّرة حاليًا في v1beta) لتجنُّب الكشف عن مفتاح واجهة برمجة التطبيقات.

عند استخدام الرموز المميزة المؤقتة مع ميزة "الترجمة المباشرة":

  1. يجب استخدام نقطة النهاية v1beta.
  2. إعدادات القفل: بشكلٍ تلقائي، يجب تحديد translationConfig في قيود إنشاء الرمز المميّز على خادمك. يضمن ذلك أنّ إعدادات الترجمة مقفلة ولا يمكن للعميل التلاعب بها.
  3. إعدادات إلغاء القفل: إذا كنت تريد أن تتمكّن من ضبط translationConfig من جهة العميل (على سبيل المثال، للسماح للمستخدم باختيار اللغة المستهدَفة)، عليك إغفالها من طلب إنشاء الرمز المميّز وضبط "lock_additional_fields": [] بدلاً من ذلك. سيؤدي ذلك إلى إتاحة ضبط translationConfig من جهة العميل.

إنشاء رمز مميّز مؤقت محدود

توضّح الأمثلة التالية كيفية إنشاء رمز مميز مؤقت مع قيود الترجمة.

Python

import datetime
from google import genai

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client()

token = client.auth_tokens.create(
    config = {
        'uses': 1,
        'expire_time': now + datetime.timedelta(minutes=30),
        'live_connect_constraints': {
            'model': 'gemini-3.5-live-translate-preview',
            'config': {
                'translation_config': {
                    'target_language_code': 'pl',
                    'echo_target_language': True
                }
            }
        },
    }
)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
        uses: 1,
        expireTime: expireTime,
        liveConnectConstraints: {
            model: 'gemini-3.5-live-translate-preview',
            config: {
                responseModalities: ['AUDIO'],
                inputAudioTranscription: {},
                outputAudioTranscription: {},
                translationConfig: {
                    targetLanguageCode: 'pl',
                    echoTargetLanguage: true
                }
            }
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "liveConnectConstraints": {
      "model": "models/gemini-3.5-live-translate-preview",
      "config": {
        "responseModalities": ["AUDIO"],
        "inputAudioTranscription": {},
        "outputAudioTranscription": {},
        "translationConfig": {
          "targetLanguageCode": "pl",
          "echoTargetLanguage": true
        }
      }
    }
  }'

القيود

  • طُرق الإدخال: لا تتوفّر الترجمة إلا من خلال إدخال الصوت. لا يمكن إدخال نص.
  • تقليد الصوت: قد يكون تقليد الصوت غير متسق. قد تتغير الأصوات بعد فترات توقّف طويلة، أو يتم تحديد الجنس بشكل خاطئ استنادًا إلى طريقة بدء الكلام، أو قد يتم استخدام صوت واحد فقط أثناء المحادثات السريعة التي يشارك فيها عدة متحدثين.
  • اكتشاف اللغة: يواجه نظام اكتشاف اللغة صعوبة في التعرّف على اللهجات الثقيلة أو اللغات المتشابهة (مثل الإسبانية والبرتغالية) أو التبديل السريع بين اللغات. ملاحظة: من المفترض أن يؤثر ذلك في نص الإدخال فقط. يجب أن تظل رموز اللغة والترجمة النهائية دقيقة.
  • الصوت في الخلفية: تم تصميم النموذج لفلترة الضوضاء والموسيقى لإنتاج كلام واضح، ولكن قد لا يتم تجاهل كل الصوت في الخلفية.
  • لغة الاستهداف Echo: عند تفعيل echoTargetLanguage: true، قد تؤدي الضوضاء في الخلفية أو الموسيقى إلى حدوث تشوّش في الصوت المترجَم عندما يكون الصوت المُدخَل باللغة المستهدَفة.

اللغات المتاحة

تتوفّر ميزة "الترجمة المباشرة" باللغات التالية.

اللغة رمز BCP-47 اللغة رمز BCP-47
الأفريقانية af الكازاخية kk
الأكانية ak الخميرية كلم
الألبانية sq الكينيارواندا rw
الأمهرية am الكورية ko
العربية ar لاو lo
الأرمينية hy اللاتفية lv
أذربيجان az الليتوانية lt
الباسك eu المقدونية mk
البيلاروسية be الماليزية مللي ثانية
البنغالية bn المالايالامية ml
البلغارية bg المراثية mr
البورمية (ميانمار) my المنغولية mn
الكتالانية ca النيبالية ne
الصينية (المبسطة) zh-Hans النرويجية no, nb
الصينية (التقليدية) zh-Hant الفارسية fa
الكرواتية ساعة البولندية pl
التشيكية cs البرتغالية (البرازيل) pt-BR
الدانماركية da برتغالي (البرتغال) pt-PT
الهولندية nl البنجابية pa
الإنجليزية en الرومانية ro
الإستونية et الروسية ru
الفلبينية fil الصربية sr
الفنلندية fi السندية دقة عادية
الفرنسية fr السنهالية si
الغليشيانية gl السلوفاكية sk
الجورجية ka السلوفينية sl
الألمانية de الإسبانية es
اليونانية el السندانية su
الغوجاراتية gu السواحيلية sw
الهوسا هكتار السويدية sv
العبرية هو التاميلية ta
الهندية hi التيلوغوية te
الهنغارية hu التايلاندية th
الأيسلندية هو التركية tr
الإندونيسية id الأوكرانية uk
الإيطالية it الأوردية ur
اليابانية ja الأوزبكية uz
الجافانية jv الفيتنامية vi
الكانادا kn الزولو zu

الخطوات التالية