Localization

Pass languageOverride when initializing the agent to fetch its 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, such as "en", "fr", "es", "de", or "ja".

What gets translated automatically

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

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 them and passing the correct values via setConfiguration:

String	Config property	Where it appears
Entry Message	entryMessage	Placeholder text inside the chat input bar
Agent name	agentDisplayName	Header of the agent panel
Conversation starters	conversationStarters	Entry screen prompts shown to the user

For the full conversation starter reference, see Conversation Starters.

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 and add translations for each language. Translations added there are served automatically when the SDK requests a specific language via languageOverride, so no additional SDK code is needed for starters managed through the admin UI.

Fallback behavior

If the requested language is not available, the agent falls back to English (en). Two console warnings help you 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 an X-Resolved-Language header, so the response may or may not be translated.

If languageOverride is omitted, the agent defaults to English.