JavaScript SDK

The Kalima JavaScript SDK is the fastest route for websites and browser-rendered product surfaces.

Current hosted script

<script
  src="https://uni-sdk.kalima.digital/kalima.js"
  data-project-key="your-project-key"
  data-show-language-switcher="true"
></script>

Recommended runtime config

<script>
  window.KalimaConfig = {
    projectKey: 'your-project-key',
    apiBaseUrl: 'https://sdk-api.kalima.digital/api/v1',
    defaultLanguage: 'en',
    supportedLocales: ['en', 'fr', 'es'],
    urlMode: 'query',
    languageParam: 'lang',
    showLanguageSwitcher: true,
    enableCssMasking: true,
    maskOnlyWhenNotReady: true,
    maskSafetyTimeoutMs: 400,
    prefetchTranslations: false,
    customCss: '.promo-banner { border-radius: 16px; }',
    instantTranslation: false,
    instantTranslationCacheTtlMs: 600000,
    instantTranslationBatchSize: 25,
    debug: false,
  };
</script>

Important settings

Setting	Purpose	Default behavior
projectKey	Connects the SDK to the right Kalima project	Required
apiBaseUrl	Selects the environment the SDK should call	Production defaults to https://sdk-api.kalima.digital/api/v1
defaultLanguage	Defines the source locale	en
supportedLocales	Limits which locales the SDK should expose	Empty until provided by runtime or project info
urlMode	Controls locale parsing from query or path	query
languageParam	Query parameter used in query mode	lang
showLanguageSwitcher	Displays Kalima language switcher UI	true
enableCssMasking	Masks content until translation state is ready	true
customCss	Injects custom CSS on page startup	Empty string
prefetchTranslations	Prefetches translations early	false
instantTranslation	Allows SDK/API instant translation for approved misses	Project setting or false
instantTranslationCacheTtlMs	Browser cache TTL for instant translation batches	600000
instantTranslationBatchSize	Maximum instant translation batch size	25
debug	Enables SDK debug behavior	false

QA and language behavior

The SDK can:

• Read locale from a query parameter such as ?lang=fr
• Read locale from a path prefix when urlMode is path
• Store the active locale in local storage
• Use approved translations only
• Use instant translation for eligible misses when explicitly enabled
• Fall back to the source text when a translation is not available

Non-DOM translation

Use this when you need to translate strings outside the DOM, such as export labels.

const label = window.Kalima?.translateText('Export List') || 'Export List';

For instant translation, use the async API. Approved translations still win before instant translation is attempted.

const result = await window.Kalima?.translateInstant(
  ['Export List', 'Billing period'],
  { targetLanguage: 'fr', context: 'account settings' },
);

Common implementation notes

• Load the SDK after window.KalimaConfig is defined if you need explicit overrides
• Ensure the project key belongs to the same environment as the API base URL
• Keep supportedLocales aligned with the project configuration in Kalima
• Use debug mode only for troubleshooting, not production defaults

Support

Need help shipping this integration?

If you hit a blocker, contact Kalima with your project key, target environment, and a short description of what failed.

Contact KalimaEmail info@kalima.digital