Skip to main content
The multilingual template provides best practices for handling multiple languages, including language detection, response formatting, and cultural considerations. This is a composable template designed to enhance other prompts.

Features

  • Automatic language detection
  • Consistent responses in user’s language
  • Cultural sensitivity
  • Translation quality guidelines

Installation

import { multilingual } from "promptsmith-ts/templates";

Basic Usage

The multilingual template is designed to be merged with your domain-specific prompts:
import { multilingual } from "promptsmith-ts/templates";
import { createPromptBuilder } from "promptsmith-ts/builder";

// Create your domain-specific prompt
const myPrompt = createPromptBuilder()
  .withIdentity("You are a customer service assistant")
  .withCapabilities(["Answer questions", "Resolve issues"]);

// Add multilingual support
const multilingualPrompt = myPrompt.merge(
  multilingual({
    supportedLanguages: ["English", "Spanish", "French"],
    defaultLanguage: "English"
  })
);

const prompt = multilingualPrompt.build();

Configuration

supportedLanguages
string[]
Supported languages (optional)Example: ["English", "Spanish", "French"]
defaultLanguage
string
default:"English"
Default language if user’s language is unclear
autoDetect
boolean
default:true
Whether to automatically detect language

Template Implementation

Here’s the complete template source code:
import type { SystemPromptBuilder } from "../builder";
import { createPromptBuilder } from "../builder";

export type MultilingualConfig = {
  supportedLanguages?: string[];
  defaultLanguage?: string;
  autoDetect?: boolean;
};

export function multilingual(
  config: MultilingualConfig = {}
): SystemPromptBuilder {
  const {
    supportedLanguages,
    defaultLanguage = "English",
    autoDetect = true,
  } = config;

  let contextStr = "";
  if (supportedLanguages && supportedLanguages.length > 0) {
    contextStr = `Supported Languages: ${supportedLanguages.join(", ")}\nDefault Language: ${defaultLanguage}`;
  } else {
    contextStr = `Default Language: ${defaultLanguage}`;
  }

  const builder = createPromptBuilder()
    .withContext(contextStr)
    .withCapabilities([
      "Detect and respond in the user's preferred language",
      "Maintain consistent terminology across languages",
      "Adapt communication style to cultural context",
    ]);

  if (autoDetect) {
    builder
      .withConstraint(
        "must",
        "Automatically detect the language of the user's message and respond in the same language"
      )
      .withConstraint(
        "must",
        `If language cannot be detected, default to ${defaultLanguage}`
      );
  }

  builder
    .withConstraint(
      "must",
      "Maintain the same level of formality as the user's message"
    )
    .withConstraint(
      "must",
      "Use culturally appropriate expressions and avoid idioms that don't translate well"
    )
    .withConstraint(
      "must_not",
      "Never mix languages within a single response unless explicitly asked"
    )
    .withConstraint(
      "must_not",
      "Never make assumptions about user preferences based on their language"
    )
    .withConstraint(
      "should",
      "Adapt date, time, number, and currency formats to the user's region"
    )
    .withConstraint(
      "should",
      "Use inclusive and respectful language appropriate for the culture"
    )
    .withConstraint(
      "should",
      "Offer to switch languages if the user struggles or asks"
    )
    .withConstraint(
      "should_not",
      "Don't use machine-translation-style language; aim for natural, fluent communication"
    )
    .withExamples([
      {
        user: "Hola, ¿cómo estás?",
        assistant: "¡Hola! Estoy bien, gracias. ¿En qué puedo ayudarte hoy?",
        explanation:
          "Detect Spanish and respond naturally in Spanish with appropriate formality",
      },
      {
        user: "Bonjour, je voudrais obtenir de l'aide",
        assistant:
          "Bonjour! Je serais ravi de vous aider. Quelle est votre question?",
        explanation:
          "Detect French and respond with appropriate formality (vous instead of tu for professional context)",
      },
    ])
    .withErrorHandling(
      `
Language Handling Guidelines:
- If you detect a language you cannot respond in fluently, politely inform the user and offer supported languages
- If the user switches languages mid-conversation, seamlessly switch to the new language
- If a technical term has no good translation, use the English term with a brief explanation
- For language-specific content (puns, wordplay, cultural references), either adapt appropriately or explain that it doesn't translate well
    `.trim()
    );

  return builder;
}

What It Adds

When you merge the multilingual template, it adds:

Language Detection

  • Automatic language detection from user messages
  • Fallback to default language when unclear
  • Seamless language switching

Cultural Adaptation

  • Appropriate formality levels
  • Culturally sensitive expressions
  • Regional date/time/number formats

Translation Quality

  • Natural, fluent communication
  • Consistent terminology
  • Proper handling of untranslatable terms

Usage Examples

Global Customer Service

import { customerService, multilingual } from "promptsmith-ts/templates";

const builder = customerService({
  companyName: "GlobalStore"
})
  .merge(multilingual({
    supportedLanguages: ["English", "Spanish", "French", "German"],
    defaultLanguage: "English"
  }));

const prompt = builder.build();

Multilingual Documentation Assistant

import { multilingual } from "promptsmith-ts/templates";
import { createPromptBuilder } from "promptsmith-ts/builder";

const builder = createPromptBuilder()
  .withIdentity("You are a technical documentation assistant")
  .withCapabilities([
    "Explain technical concepts",
    "Guide users through documentation"
  ])
  .merge(multilingual({
    supportedLanguages: ["English", "Japanese", "Korean", "Chinese"],
    defaultLanguage: "English"
  }));

const prompt = builder.build();

Specific Language Constraints

import { multilingual } from "promptsmith-ts/templates";
import { createPromptBuilder } from "promptsmith-ts/builder";

const builder = createPromptBuilder()
  .withIdentity("You are a language learning assistant")
  .merge(multilingual({
    supportedLanguages: ["English", "Spanish"],
    autoDetect: false // User must explicitly choose language
  }))
  .withConstraint(
    "must",
    "When teaching Spanish, provide both formal (usted) and informal (tú) versions"
  );

const prompt = builder.build();

Layering Multiple Templates

import { customerService, security, multilingual } from "promptsmith-ts/templates";

// Create a secure, multilingual customer service agent
const builder = customerService({
  companyName: "GlobalStore"
})
  .merge(security())           // Add security guardrails
  .merge(multilingual({        // Add multilingual support
    supportedLanguages: ["English", "Spanish", "French"]
  }));

const prompt = builder.build();

Language Handling Guidelines

The template includes specific language handling behaviors:
  • Unsupported languages: Politely inform user and offer supported options
  • Language switching: Seamlessly switch when user changes languages
  • Untranslatable terms: Use English with brief explanation
  • Cultural content: Adapt or explain when it doesn’t translate well

Example Multilingual Behaviors

Spanish Detection and Response

User: Hola, ¿cómo estás? Assistant: ¡Hola! Estoy bien, gracias. ¿En qué puedo ayudarte hoy?

French with Appropriate Formality

User: Bonjour, je voudrais obtenir de l’aide Assistant: Bonjour! Je serais ravi de vous aider. Quelle est votre question? (Note: Uses “vous” instead of “tu” for professional context)

Handling Unsupported Languages

User: 你好,我需要帮助 (Chinese) Assistant: I apologize, but I currently support English, Spanish, and French. Would you like to continue in English? / Lo siento, pero actualmente admito inglés, español y francés. ¿Le gustaría continuar en inglés? / Je m’excuse, mais je prends actuellement en charge l’anglais, l’espagnol et le français. Souhaitez-vous continuer en anglais?

When to Use This Template

Use the multilingual template when:
  • Building global/international applications
  • Serving diverse user populations
  • Expanding to new markets
  • Required to support multiple languages
  • Wanting to provide localized experiences

Best Practices

  1. List supported languages explicitly in configuration
  2. Test with native speakers for each language
  3. Consider regional variations (e.g., Spanish in Spain vs. Latin America)
  4. Handle formality appropriately (tu/vous in French, tú/usted in Spanish)
  5. Adapt formatting for dates, numbers, currency by region
  6. Avoid idioms that don’t translate well

Constraints Added

MUST Rules

  • Automatically detect language and respond in same language (if autoDetect enabled)
  • Maintain same formality level as user
  • Use culturally appropriate expressions

MUST NOT Rules

  • Never mix languages within a response
  • Never make assumptions based on language

SHOULD Guidelines

  • Adapt regional formats (dates, numbers, currency)
  • Use inclusive and respectful language
  • Offer to switch languages if needed
  • Aim for natural, fluent communication

Accessibility Template

Combine with accessibility for truly inclusive experiences

Customer Service Template

See multilingual support in customer service context

Merging Prompts

Deep dive into composing prompts

Templates Overview

Explore all available templates

Build docs developers (and LLMs) love