# Localization

Serve your agent in your user's language with languageOverride, and translate the strings the server does not handle for you.

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.

```javascript
foldspace.agent('YOUR-AGENT-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](#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](/customize/conversation-starters/).

### Example: translating dynamic strings

```javascript
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('YOUR-AGENT-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.