Adding New Languages

Relevant source files

The following files were used as context for generating this wiki page:

• src/languages.ts
• src/commands/start.ts
• src/commands/languages.ts
• src/processors/translate.ts
• src/processors/readText.ts
• docker-compose.prod.yml
• stt/src/main.rs
• requirements.txt

This document outlines the process and architectural considerations for adding a new target language to the Discord Live Translator bot. The system is designed to be extensible, but requires configuration changes in several key areas, including the core application code, Text-to-Speech (TTS) models, and the translation service configuration.

The bot's architecture is built around a central speech-to-text (STT) service that transcribes all spoken audio into English text. This English text is then translated into the user's selected target language. This means that adding a new language is primarily about adding a new target for translation and speech synthesis, not a new source for speech recognition.

1. Language Configuration

The primary source of truth for available languages is the languages object defined in src/languages.ts. Adding a new language begins with adding a new entry to this object.

Sources: src/languages.ts

Language Object Structure

Each language is represented by an object with a specific structure. The key of the object is the short language code (e.g., 'en', 'de').

Property	Type	Description
icon	string	A Discord-compatible flag emoji string used for display purposes.
displayName	string	The full, human-readable name of the language. This is shown to users in command options.
translatorCode	string	The language code used by the external translation service (LibreTranslate).
ttsModel	string	The path to the Text-to-Speech model used to generate audio for this language. The models are provided by the Coqui TTS library (TTS in requirements.txt) and are expected to be found within the src/lib/tts directory after being set up.

Sources: src/languages.ts:1-29, src/processors/readText.ts:14, requirements.txt

Example: Adding a New Language

To add Italian, the following object was added to the languages constant:

// File: src/languages.ts:23-27

it: {
  icon: ':flag_it:',
  displayName: 'Italian',
  translatorCode: 'it',
  ttsModel: 'tts_models/it/mai_female/vits'
}

Sources: src/languages.ts:23-27

2. System Integration

Once a language is added to src/languages.ts, it is automatically integrated into several parts of the application, including user-facing commands.

Command Integration

The /start and /languages commands dynamically read from the languages object.

• /start: The languageChoices array is generated by mapping over the languages object, making the new language immediately available as a target option for users.
• /languages: This command iterates over the languages object to build and display a list of all available languages to the user.

This diagram shows how adding a language to the central file updates the user commands without any further code changes.

3. Service Dependencies

Adding a language requires ensuring that the external services for translation and text-to-speech support it.

Translation Service (LibreTranslate)

The bot uses an external translation service, defined by the TRANSLATION_HOST environment variable. The translation processor sends the recognized English text to this service.

The Docker configuration for the libretranslate service uses the LT_LOAD_ONLY environment variable to specify which language models to load into memory. To add a new language, its code must be added to this list.

# File: docker-compose.prod.yml:25-27

environment:
  - LT_LOAD_ONLY=de,en,es,fr,it

If a new language (e.g., 'pt' for Portuguese) were to be added, this line would need to be updated: LT_LOAD_ONLY=de,en,es,fr,it,pt.

The translation flow is depicted below.

This flow highlights a critical architectural detail: the translation source is always hardcoded as 'en'. This is because the upstream Speech-to-Text service is configured to always output English.

Sources: docker-compose.prod.yml:27, src/processors/translate.ts:17-19, stt/src/main.rs:40-41

Text-to-Speech (TTS) Service

The readText processor is responsible for converting the translated text back into speech. It executes a Python script (src/lib/tts/read_text.py) and passes the ttsModel path from the language configuration.

To support a new language, a compatible TTS model must be available. The project uses Coqui TTS, and the models are referenced by paths like tts_models/de/thorsten/vits. The necessary Python libraries for the language's phonemizer (e.g., gruut-lang-de) must also be included in requirements.txt.

The process is as follows:

1. The readText function is called with the translated text and target language.
2. It retrieves the ttsModel path from the languages.ts configuration.
3. It invokes a Python script, passing the model, text, and an output path for the generated .wav file.
4. The generated audio file is then queued for playback in the voice channel.

Sources: src/processors/readText.ts:13-17, requirements.txt

Speech-to-Text (STT) Service Limitation

The STT service, written in Rust and using the Whisper model, is configured to transcribe audio and translate it to English.

// File: stt/src/main.rs:40-41
params.set_translate(true);
params.set_language(Some("en"));

This means the rest of the system only ever deals with English as the source language for translation. This simplifies the translation logic but means the system's multilingual capability is limited to the output side. Any changes to source language recognition would require modifications to the STT service.

Sources: stt/src/main.rs:40-41

Summary

To add a new language to the translator bot, a developer must perform the following steps:

1. Ensure TTS Support: Verify that a Coqui TTS model for the desired language exists and is placed in the correct directory. Add any necessary language-specific Python dependencies to requirements.txt.
2. Update Translation Service: Modify the LT_LOAD_ONLY environment variable in docker-compose.prod.yml to include the new language code for the libretranslate service.
3. Update Language Configuration: Add a new entry for the language in the languages object in src/languages.ts, providing the correct icon, displayName, translatorCode, and ttsModel path.

Once these steps are completed and the application is rebuilt and restarted, the new language will be automatically available to users.