Localization

Pass languageOverride when initializing the agent to fetch the configuration in a specific language. The SDK sends the language code to the server, which returns translated content for that locale.

foldspace.agent('API-KEY', {
  languageOverride: "fr"
});

The value must be an ISO 639-1 language code (e.g. "en", "fr", "es", "de", "ja").

What gets translated automatically

When languageOverride is set, the server returns the agent configuration with conversation starters translated into the requested language — provided translations have been set up in advance (see below).

What requires developer translation

The following UI strings are not translated automatically by the server. If your application supports multiple languages, you are responsible for translating and passing the correct values via setConfiguration:

Example — translating dynamic strings

const translations = {
  en: {
    agentDisplayName: "Support Agent",
    entryMessage: "Ask me anything...",
    starters: {
      KNOWLEDGE: [
        { title: "What is your return policy?" },
        { title: "How do I track my order?" }
      ],
      ACTION: [
        { title: "Schedule a demo" },
        { title: "Contact support" }
      ]
    }
  },
  fr: {
    agentDisplayName: "Agent d'assistance",
    entryMessage: "Posez-moi une question...",
    starters: {
      KNOWLEDGE: [
        { title: "Quelle est votre politique de retour ?" },
        { title: "Comment suivre ma commande ?" }
      ],
      ACTION: [
        { title: "Planifier une démo" },
        { title: "Contacter le support" }
      ]
    }
  }
};

const userLang = "fr";
const t = translations[userLang];

const agent = foldspace.agent('API-KEY', {
  languageOverride: userLang
});

agent.setConfiguration({
  agentDisplayName: t.agentDisplayName,
  entryMessage: t.entryMessage
});

agent.setConversationStarters(t.starters);

Translating conversation starters in the admin UI

You can translate conversation starters directly from the Foldspace admin panel without writing any code. Go to your agent's Starters page under Customize, where you can add translations for each language. Translations added there are served automatically when the SDK requests a specific language via languageOverride — no additional SDK code is needed for starters managed through the admin UI.

Fallback behavior

If the requested language is not available, the agent always falls back to English (en). Two console warnings help identify translation issues:

• [Foldspace] Requested language "xx" is not supported. Serving "en" instead. — the server did not have translations for the requested language and returned English.
• [Foldspace] Requested language "xx" — server did not confirm language resolution. Translations may not be available. — the server did not return a X-Resolved-Language header; the response may or may not be translated.

If languageOverride is omitted, the agent defaults to English.