Skip to main content
Version: v8001

Translate the SDK

BlinkID ships UI translations for many languages, but how a language gets selected and how you override wording differs by platform.

  • On Android and iOS, the bundled translations are applied automatically based on the device language. You only do something when you want to change the wording or add a language the SDK doesn't bundle.
  • On Web, the running UI always uses English unless you supply strings yourself. The SDK source includes ready-made translations for many languages that you copy from, but it does not auto-detect the browser language.

Each platform is covered separately below.

Web​

Default behavior​

The Web SDK always renders its UI in English. It does not read the browser's language and does not switch locales on its own. To show any other language, or to change any wording, you pass strings through feedbackUiOptions.localizationStrings when you call createBlinkId.

localizationStrings is a deep partial set of localization strings: pass only the keys you want to set, and every key you leave out falls back to the built-in English copy.

Switch to another language​

The SDK source includes ready-made translations.

To show one of these languages, copy the desired file and import it.

import frenchStrings from './fr.ts';

const blinkId = await createBlinkId({
  licenseKey: "your-license-key",
  feedbackUiOptions: {
    localizationStrings: frenchStrings,
  },
});

Because localizationStrings is a partial, you can also start from a bundled translation and adjust individual phrases on top of it.

Change a single message​

To tweak one or two strings, override just those keys:

const blinkId = await createBlinkId({
  licenseKey: "your-license-key",
  feedbackUiOptions: {
    localizationStrings: {
      feedback_messages: {
        blur_detected: "Hold the document and phone steady",
        glare_detected: "Tilt the document to remove the reflection",
      },
    },
  },
});

Anything you don't list keeps its English default.

Android​

Default behavior​

On Android, the UI strings are standard Android string resources, prefixed with mb_. The SDK bundles translations for many locales through the usual values-<locale> resource folders, and Android automatically picks the right one based on the device language. No setup is required for the bundled languages to work.

There is no API to force a specific language from code: the SDK follows the device locale, like any other Android resources. To present a different language regardless of the device setting, change the device locale or use Android's per-app language feature.

Override strings with resources​

To change the wording or add a language, redefine the same string keys in your own app. Android resource resolution lets your app's resources take precedence over the SDK's, so a string you declare with a matching name overrides the bundled one:

<!-- app/src/main/res/values/strings.xml -->
<resources>
    <string name="mb_blur_detected">Hold steady</string>
</resources>

To translate into a language the SDK doesn't bundle, add the same keys under a locale-specific folder, for example app/src/main/res/values-sv/strings.xml for Swedish.

iOS​

Default behavior​

On iOS, the UI strings ship inside the SDK framework as a String Catalog (Localizable.xcstrings), keyed by mb_-prefixed identifiers, with translations for many languages. The SDK resolves these strings from its own framework bundle and selects a language based on the device locale, falling back to English when the device language isn't bundled. The bundled translations work without any setup.

Overriding strings​

Because the strings are resolved from the framework bundle rather than your app bundle, the iOS SDK does not expose a public API for overriding individual strings or for supplying a language it doesn't already bundle. The scanning UX configuration (ScanningUXSettings) has no localization options. To change the displayed language, change the device locale; the SDK follows it.

Last updated on