Internationalization

Register a locale

Locale bundles are opt-in, tree-shakeable exports. Import the ones you use, register them under i18n.messages, and set i18n.locale. A German (de) bundle ships today; English is the built-in base and needs no import.

import { createBankai } from '@bankai-vue/core';
import { de } from '@bankai-vue/core/locales';

app.use(
  createBankai({
    i18n: {
      locale: 'de',
      // Only the bundles you register ship — unregistered locales are tree-shaken away.
      messages: { de },
    },
  }),
);

Under Nuxt it is even less: set i18n.locale and the module auto-injects the matching built-in bundle into its generated plugin — no import, no messages — as a static, tree-shaken, SSR-safe import. Register a bundle in messages only to override it or add a locale core doesn't ship. The config is installed per app, so it stays per-request under SSR.

// nuxt.config.ts — under Nuxt, just set the locale: the module auto-injects the
// matching built-in bundle (here 'de'), so no import or messages registration is needed.
export default defineNuxtConfig({
  modules: ['@bankai-vue/nuxt'],
  css: ['@bankai-vue/theme-bankai'],

  bankai: {
    config: { i18n: { locale: 'de' } },
  },
});

Locale coverage

English is the complete base — 100% by definition. Each shipped bundle covers a share of the message keys; whatever it omits falls through to English. As new components add default strings, a bundle's coverage drops until the new keys are translated.

Override just some strings

A bundle can be partial. Any key you leave out falls through to the complete English base, so you can register a shipped bundle, hand-write a bundle for a locale that has none yet, or tweak a single string — all through the same messages registry.

import { createBankai } from '@bankai-vue/core';

app.use(
  createBankai({
    i18n: {
      locale: 'de',
      messages: {
        // A bundle may be partial — omitted keys fall through to English, never to an
        // empty string. So you can hand-write just the strings you want to change.
        de: { codeBlock: { copy: 'Kopieren' } },
      },
    },
  }),
);

Regional variants & fallback

A regional locale inherits its base language automatically: de-AT resolves every de string, and only the keys you give de-AT override it. Set fallbackLocale for a cross-family fallback (tried before the English base). The full chain is: active locale and its regional parents → fallbackLocale and its parents → English.

createBankai({
  i18n: {
    locale: 'de-AT',      // regional: inherits every 'de' string automatically
    fallbackLocale: 'de', // tried before English for a locale with no bundle
    messages: { de },
  },
});

Precedence

Each default string resolves in this order:

1. a per-instance prop (e.g. <BankaiCodeBlock copy-label="…">) — wins for that element;
2. the active locale bundle resolved from the config;
3. the built-in English default.

Switching at runtime

The config is reactive, so assigning a new i18n.locale re-renders every component's labels — no reload, no re-mount.

<script setup lang="ts">
import { useBankaiConfig } from '@bankai-vue/core';

const config = useBankaiConfig();

// Reactive: flipping the locale re-renders every component's default strings.
function toggle() {
  config.i18n.locale = config.i18n.locale === 'de' ? 'en' : 'de';
}
</script>

See also

BankaiCodeBlock — the first component with localizable strings, and its copyLabel / copiedLabel props.