Internationalization

The SDK supports 80+ languages for UI text and error messages.

Setting the Language

Pass the lang property inside the i18n option when you call setup():

import { setup } from '@incodetech/web';

await setup({
  apiURL: API_URL,
  token: session.token,
  i18n: {
    lang: 'es', // Spanish
  },
});

If a language was previously stored by the SDK (for example, when a user picked one from a language selector), that stored choice takes precedence over lang. Treat lang as the default for first-time users, not a hard override.

How It Works

• The lang property sets the UI language for all SDK components within the flow.
• In published 2.3.0 packages, default translations load from bundled locale chunks served with your application. Earlier packages and SDK development builds may use i18nexus at runtime.
• Error messages and instructions are automatically translated.
• The language is also sent to the backend for server-side localization.

Custom Translations

Provide your own translation strings through the i18n option in setup(). Pass a translations object keyed by language code, then by translation key.

import { setup } from '@incodetech/web';

await setup({
  apiURL: API_URL,
  token: session.token,
  i18n: {
    translations: {
      en: {
        phone: { verify: 'Verify your phone number' },
        email: { willSendCode: 'We will email you a one-time code.' },
      },
      es: {
        phone: { verify: 'Verifica tu número de teléfono' },
      },
    },
  },
});

By default, your strings merge on top of the built-in translations, so you only override the keys you list. Any key you omit keeps its default text.

Keys use dotted, camelCase paths in the form module.description (for example phone.verify). Write them as nested objects (above) or as flat dotted keys:

translations: {
  en: { 'phone.verify': 'Verify your phone number' },
}

Use {{variableName}} for values the SDK fills in at runtime — keep the placeholder name unchanged:

translations: {
  en: { selfie: { retryAttempts: 'You have {{count}} attempts left.' } },
}

Translation values are rendered without HTML escaping. Never interpolate user-controlled input directly into a translation string — doing so can introduce a cross-site scripting (XSS) vulnerability. Keep translation values as static, trusted content.

Disable remote translation loading

Set skipRemoteLoad: true to disable the remote backend, including a custom loadPath, while applying your inline overrides:

await setup({
  apiURL: API_URL,
  token: session.token,
  i18n: {
    skipRemoteLoad: true,
    translations: {
      en: {
        /* your translation overrides */
      },
    },
  },
});

In 2.3.0, disabling remote loading doesn't create an inline-only mode. The SDK still loads its bundled translations. If a key isn't in your overrides or in any bundled translation (including the English fallback), the SDK shows the last segment of the key in title case: for example, phone.verify renders as Verify.

Load translations from your own endpoint

To serve translation files from your own host or CDN, set loadPath to a URL template. The SDK fetches one file per language, replacing {{lng}} with the language code and {{ns}} with the namespace (always default):

await setup({
  apiURL: API_URL,
  token: session.token,
  i18n: {
    loadPath: 'https://cdn.example.com/locales/{{lng}}/{{ns}}.json',
  },
});

For example, loading Spanish requests https://cdn.example.com/locales/es/default.json. Each file must be a JSON object of translation keys, using the same module.description structure shown above.

Setting loadPath selects your endpoint instead of the bundled backend (or i18nexus in SDK development builds). Allow that host in your CSP and provide the languages your flow needs, including English fallback. Do not combine it with skipRemoteLoad: true, which disables the custom remote backend.

Supported Languages

The SDK supports the language codes below. Published 2.3.0 packages include generated locale chunks; a custom loadPath uses your hosted files instead.

See Also

• Theming & Styling: Customize appearance
• IncodeFlow Component: Full props reference