Internationalization

SWAN's internationalization (i18n) system allows SWAN components to render with fully translated and accessible text out-of-the-box. This will help to ensure a consistent user experience of our components across all supported locales.

Opting-In to i18n

Note i18n in SWAN is optional in v3 but will become required in v4.

The i18n system is enabled through our existing <SwanProvider>. You need to provide two props: swanLocale and translations.

The key is to dynamically load only the translation file for the user's current locale. The method for doing this varies depending on your application's environment.

What to Do After Opting In

Once you've configured the <SwanProvider>, SWAN components will automatically receive their translated and accessible text from the i18n context. You can now clean up your code by removing all the deprecated accessibleText... and other localized text props. The custom SWAN ESLint plugin will warn you of any existing usage of these deprecated props that you can now remove so ensure you also upgrade it to the latest version (more on linter configuration below).

Note for UBIK Consumers: The documentation for UBIK Fragments below says "No action is required" because the i18n system is enabled for you automatically. However, you can and should still perform this cleanup step. We highly recommend reviewing your code and removing any redundant text props to get the full benefit of the new system.

Setting Up Your Project For i18n

UBIK FragmentsNext.js ApplicationsClient-Side Rendered (CSR) ApplicationsGatsby Applications

No action is required. The UBIK platform's implementation of <SwanProvider>will handle loading and providing the locale and translations for you automatically. Your SWAN components will be internationalized by default.

In server-side rendering environments like Next.js, you can fetch the translations in getServerSideProps based on the incoming request's locale.

pages/_app.tsxpages/index.tsx

CopyShare

import { SwanProvider } from '@vp/swan'
export default function App({ Component, pageProps }) {
  const { locale, translations } = pageProps
  return (
    <SwanProvider locale={locale} translations={translations}>
      <Component {...pageProps} />
    </SwanProvider>
  )
}

import { SwanProvider } from '@vp/swan' export default function App({ Component, pageProps }) { const { locale, translations } = pageProps return ( <SwanProvider locale={locale} translations={translations}> <Component {...pageProps} /> </SwanProvider> ) }

CopyShare

export async function getServerSideProps(context) {
  // Get the locale from the Next.js context (determined by URL path/domain)
  const locale = context.locale || 'en-US'
  // Dynamically import only the required translation file
  const translations = (
    await import(`@vp/swan/i18n/${locale.toLowerCase()}.json`)
  ).default
  return {
    props: {
      translations,
      locale,
    },
  }
}

export async function getServerSideProps(context) { // Get the locale from the Next.js context (determined by URL path/domain) const locale = context.locale || 'en-US' // Dynamically import only the required translation file const translations = ( await import(`@vp/swan/i18n/${locale.toLowerCase()}.json`) ).default return { props: { translations, locale, }, } }

In a CSR application (like one using Vite or Create React App), you can fetch the translations in a useEffect hook and hold them in state. Note bundlers like Vite and Rollup don’t support dynamic imports with 3rd party libraries so you need to use something similar to thegetSwanTranslations example below. If you don’t need localization support in your application, such as for internal tooling applications, you can just pass en-us to the translations instead.

App.tsxgetSwanTranslations.tsx

CopyShare

import { SwanProvider } from '@vp/swan'
import { useState, useEffect } from 'react'
import getSwanTranslations from './getSwanTranslations'

export default function App() {
  const [i18n, setI18n] = useState({ loaded: false, translations: {} })
  const [locale, setLocale] = useState('en-US')
  useEffect(() => {
    const loadTranslations = async () => {
      // 1. Detect the user's locale from the browser
      const userLocale = navigator.language || 'en-US'
      setLocale(userLocale)
      // 2. Fetch only the required translation file
      const translations = await getSwanTranslations(userLocale)
      setI18n({ loaded: true, translations })
    }
    loadTranslations()
  }, [])
  if (!i18n.loaded) {
    return <div>Loading...</div>
  }
  // 3. Pass the loaded data to the SwanProvider
  return (
    <SwanProvider locale={locale} translations={i18n.translations}>
      {/* Your application content */}
    </SwanProvider>
  )
}

import { SwanProvider } from '@vp/swan' import { useState, useEffect } from 'react' import getSwanTranslations from './getSwanTranslations' export default function App() { const [i18n, setI18n] = useState({ loaded: false, translations: {} }) const [locale, setLocale] = useState('en-US') useEffect(() => { const loadTranslations = async () => { // 1. Detect the user's locale from the browser const userLocale = navigator.language || 'en-US' setLocale(userLocale) // 2. Fetch only the required translation file const translations = await getSwanTranslations(userLocale) setI18n({ loaded: true, translations }) } loadTranslations() }, []) if (!i18n.loaded) { return <div>Loading...</div> } // 3. Pass the loaded data to the SwanProvider return ( <SwanProvider locale={locale} translations={i18n.translations}> {/* Your application content */} </SwanProvider> ) }

CopyShare

// Helper map and function to dynamically load translation files.
// This is often required by bundlers like Vite and Rollup, which cannot handle
// fully dynamic import paths in third-party libraries.
const translationImports: Record<string, () => Promise<any>> = {
  'da-dk': () => import('@vp/swan/i18n/da-dk.json'),
  'de-at': () => import('@vp/swan/i18n/de-at.json'),
  'de-ch': () => import('@vp/swan/i18n/de-ch.json'),
  'de-de': () => import('@vp/swan/i18n/de-de.json'),
  'en-au': () => import('@vp/swan/i18n/en-au.json'),
  'en-ca': () => import('@vp/swan/i18n/en-ca.json'),
  'en-gb': () => import('@vp/swan/i18n/en-gb.json'),
  'en-ie': () => import('@vp/swan/i18n/en-ie.json'),
  'en-in': () => import('@vp/swan/i18n/en-in.json'),
  'en-nz': () => import('@vp/swan/i18n/en-nz.json'),
  'en-sg': () => import('@vp/swan/i18n/en-sg.json'),
  'es-es': () => import('@vp/swan/i18n/es-es.json'),
  'es-us': () => import('@vp/swan/i18n/es-us.json'),
  'fi-fi': () => import('@vp/swan/i18n/fi-fi.json'),
  'fr-be': () => import('@vp/swan/i18n/fr-be.json'),
  'fr-ca': () => import('@vp/swan/i18n/fr-ca.json'),
  'fr-ch': () => import('@vp/swan/i18n/fr-ch.json'),
  'fr-fr': () => import('@vp/swan/i18n/fr-fr.json'),
  'it-ch': () => import('@vp/swan/i18n/it-ch.json'),
  'it-it': () => import('@vp/swan/i18n/it-it.json'),
  'nb-no': () => import('@vp/swan/i18n/nb-no.json'),
  'nl-be': () => import('@vp/swan/i18n/nl-be.json'),
  'nl-nl': () => import('@vp/swan/i18n/nl-nl.json'),
  'pt-pt': () => import('@vp/swan/i18n/pt-pt.json'),
  'sv-se': () => import('@vp/swan/i18n/sv-se.json'),
  'en-us': () => import('@vp/swan/i18n/en-us.json'),
}

async function getSwanTranslations(locale: string) {
  const importFn =
    translationImports[locale.toLowerCase()] || translationImports['en-us']
  const module = await importFn()
  return module.default
}

// Helper map and function to dynamically load translation files. // This is often required by bundlers like Vite and Rollup, which cannot handle // fully dynamic import paths in third-party libraries. const translationImports: Record<string, () => Promise<any>> = { 'da-dk': () => import('@vp/swan/i18n/da-dk.json'), 'de-at': () => import('@vp/swan/i18n/de-at.json'), 'de-ch': () => import('@vp/swan/i18n/de-ch.json'), 'de-de': () => import('@vp/swan/i18n/de-de.json'), 'en-au': () => import('@vp/swan/i18n/en-au.json'), 'en-ca': () => import('@vp/swan/i18n/en-ca.json'), 'en-gb': () => import('@vp/swan/i18n/en-gb.json'), 'en-ie': () => import('@vp/swan/i18n/en-ie.json'), 'en-in': () => import('@vp/swan/i18n/en-in.json'), 'en-nz': () => import('@vp/swan/i18n/en-nz.json'), 'en-sg': () => import('@vp/swan/i18n/en-sg.json'), 'es-es': () => import('@vp/swan/i18n/es-es.json'), 'es-us': () => import('@vp/swan/i18n/es-us.json'), 'fi-fi': () => import('@vp/swan/i18n/fi-fi.json'), 'fr-be': () => import('@vp/swan/i18n/fr-be.json'), 'fr-ca': () => import('@vp/swan/i18n/fr-ca.json'), 'fr-ch': () => import('@vp/swan/i18n/fr-ch.json'), 'fr-fr': () => import('@vp/swan/i18n/fr-fr.json'), 'it-ch': () => import('@vp/swan/i18n/it-ch.json'), 'it-it': () => import('@vp/swan/i18n/it-it.json'), 'nb-no': () => import('@vp/swan/i18n/nb-no.json'), 'nl-be': () => import('@vp/swan/i18n/nl-be.json'), 'nl-nl': () => import('@vp/swan/i18n/nl-nl.json'), 'pt-pt': () => import('@vp/swan/i18n/pt-pt.json'), 'sv-se': () => import('@vp/swan/i18n/sv-se.json'), 'en-us': () => import('@vp/swan/i18n/en-us.json'), } async function getSwanTranslations(locale: string) { const importFn = translationImports[locale.toLowerCase()] || translationImports['en-us'] const module = await importFn() return module.default }

In Gatsby, you create localized pages in gatsby-node.js and then use the wrapPageElement browser/SSR API to provide the i18n context.

gatsby-node.jsgatsby-ssr.js & gatsby-browser.js (same code in both)

CopyShare

export const onCreatePage = async ({ page, actions }) => {
  const { createPage, deletePage } = actions
  deletePage(page)
  // Create a new version of the page for each locale
  mySupportedLocales.forEach(async supportedLocale => {
    const locale = supportedLocale.toLowerCase()
    const translations = await import(`@vp/swan/translations/${locale}.json`)
    const localizedPath =
      locale === defaultLocale
        ? page.path
        : `/${locale.split('-')[0]}${page.path}`
    createPage({
      ...page, // Copy original page data
      path: localizedPath,
      // Pass locale and translations into the context.
      // This makes the data available to the page component and wrapPageElement.
      context: {
        ...page.context,
        locale,
        translations,
      },
    })
  })
}

export const onCreatePage = async ({ page, actions }) => { const { createPage, deletePage } = actions deletePage(page) // Create a new version of the page for each locale mySupportedLocales.forEach(async supportedLocale => { const locale = supportedLocale.toLowerCase() const translations = await import(`@vp/swan/translations/${locale}.json`) const localizedPath = locale === defaultLocale ? page.path : `/${locale.split('-')[0]}${page.path}` createPage({ ...page, // Copy original page data path: localizedPath, // Pass locale and translations into the context. // This makes the data available to the page component and wrapPageElement. context: { ...page.context, locale, translations, }, }) }) }

CopyShare

import React from 'react'
import { SwanProvider, SwanI18nProviderProps } from '@vp/swan'

export const wrapPageElement = ({ element, props }) => {
  const locale = props.pageContext.locale as SwanI18nProviderProps['locale']
  const translations = props.pageContext
    .translations as SwanI18nProviderProps['translations']

  return (
    <SwanProvider locale={locale} translations={translations}>
      {element}
    </SwanProvider>
  )
}

import React from 'react' import { SwanProvider, SwanI18nProviderProps } from '@vp/swan' export const wrapPageElement = ({ element, props }) => { const locale = props.pageContext.locale as SwanI18nProviderProps['locale'] const translations = props.pageContext .translations as SwanI18nProviderProps['translations'] return ( <SwanProvider locale={locale} translations={translations}> {element} </SwanProvider> ) }

i18n and the SWAN ESLint Plugin

Our ESLint plugin (@vp/eslint-plugin-swan) includes a rule called required-accessibility-props. This rule was created to enforce certain accessibility props (like accessibleTextFor...) that are optional in a component's TypeScript interface but are functionally required for an accessible experience.

When you opt-in to SWAN's i18n system, the i18n provider handles these props for you automatically. However, the ESLint rule doesn't know you've opted in and will continue to report them as missing, creating unnecessary errors.

To solve this, the rule includes an ignoreI18nSupportedProps option. If your project has opted into the SWAN i18n system, you should enable this option in your .eslintrc.json file to prevent these false positives.

CopyShare

{
  "rules": {
    "@vp/swan/required-accessibility-props": [
      "error",
      {
        "ignoreI18nSupportedProps": true
      }
    ]
  }
}

{ "rules": { "@vp/swan/required-accessibility-props": [ "error", { "ignoreI18nSupportedProps": true } ] } }

When ignoreI18nSupportedProps is set to true, the rule will stop reporting errors for props that are now handled by the i18n provider (e.g. accessibleTextForIcon on AlertBox). Importantly, it will still enforce other required accessibility props that are not related to i18n (e.g. headingLevel on Collapsible), so you don't lose any of the rule's other benefits.

Overriding Default Translations

Sometimes a default string doesn't fit your specific context. You can override any translation by using the exported <SwanI18nProvider>.

For example, a Carousel's default accessible text for previous and next slide button is “Go to previous slide” and “Go to next slide”. When displaying multiple Carousel’s on the same page, it is necessary to override these strings making them more specific for each one to maintain accessibility. For a Carousel of product categories, you might use something like “Explore all categories: Go to next category” etc.

To do this, wrap the specific part of your component tree with <SwanI18nProvider> and pass a translations prop containing only the keys you want to change mapped to the localized string value.

CopyShare

import { SwanProvider, SwanI18nProvider, Carousel } from '@vp/swan'
export const MyPage = () => {
  // Define only the translations you want to override with localized strings
  const overrideTranslations = {
    'carousel.accessible-text-for-next-button': 'Explore all categories: Next',
  }
  return (
    <SwanProvider locale={locale} translations={swanTranslations}>
      {/* This Carousel will use the default "Go to next slide" string */}
      <Carousel />
      <SwanI18nProvider translations={overrideTranslations}>
        {/* This Carousel will use the overridden "Explore all categories: Next" message */}
        <Carousel />
      </SwanI18nProvider>
    </SwanProvider>
  )
}

import { SwanProvider, SwanI18nProvider, Carousel } from '@vp/swan' export const MyPage = () => { // Define only the translations you want to override with localized strings const overrideTranslations = { 'carousel.accessible-text-for-next-button': 'Explore all categories: Next', } return ( <SwanProvider locale={locale} translations={swanTranslations}> {/* This Carousel will use the default "Go to next slide" string */} <Carousel /> <SwanI18nProvider translations={overrideTranslations}> {/* This Carousel will use the overridden "Explore all categories: Next" message */} <Carousel /> </SwanI18nProvider> </SwanProvider> ) }

Finding Translation Keys

To override a translation, you need to know its key (e.g. carousel.accessible-text-for-next-button). You can find the SWAN translation keys and values in the en-us translation file.

Placeholders/Variables

Note some translations require placeholders, please ensure any override strings contain the required placeholders matching the placeholder name and placing them inside double curly braces. You can find these in the existing translations in the link above.

CopyShare

{
  "greeting": "Hello {{name}}!"
}

{ "greeting": "Hello {{name}}!" }