Skip to content
awesome-tour

Type to search every page.

    BInternationalizationContents

    Internationalization

    Translate every string the primitives render, announce and label — per app, per tour, or per component.

    Your step titles and descriptions are yours, so they’re already in your language. The primitives also render a few strings of their own — the screen-reader announcement on each step, accessible names like “Close tour” and “Show hint”, checklist status text. messages translates all of them.

    Internationalization
    Language
    Loopworknight-drive.lwp
    001.1.1

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    I18nDemo.tsx
    import { createTour, Tour, type TourMessages } from '@awesome-tour/react';
    import { LoopworkApp, parts } from '@loopwork';
    import { useState } from 'react';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { DemoFrame, StartButton, worldButton } from './ui';
    const $ = parts('worldwide');
    type Lang = 'en' | 'pt' | 'ar';
    const messages: Record<Lang, Partial<TourMessages> | undefined> = {
    en: undefined,
    pt: {
    stepOf: (current, total) => `Passo ${current} de ${total}`,
    closeTour: 'Fechar tour',
    tourSteps: 'Passos do tour',
    goToStep: (index) => `Ir para o passo ${index}`,
    },
    ar: {
    stepOf: (current, total) => `الخطوة ${current} من ${total}`,
    closeTour: 'إغلاق الجولة',
    tourSteps: 'خطوات الجولة',
    goToStep: (index) => `انتقل إلى الخطوة ${index}`,
    },
    };
    // One tour, its text in three languages: the Root's `locale` picks one (or `<html lang>`).
    const tour = createTour({
    id: 'docs-i18n',
    steps: [
    {
    id: 'transport',
    target: $('transport'),
    title: { en: 'Transport', pt: 'Transporte', ar: 'أدوات التشغيل' },
    description: {
    en: 'Play, stop and record. The counter reads bar · beat · step.',
    pt: 'Toque, pare e grave. O contador mostra compasso · tempo · passo.',
    ar: 'شغّل وأوقف وسجّل. العدّاد يعرض المازورة · النبضة · الخطوة.',
    },
    },
    {
    id: 'beat',
    target: $('sequencer'),
    title: { en: 'The beat', pt: 'A batida', ar: 'الإيقاع' },
    description: {
    en: 'Click a cell to add a hit. Each row is one bar.',
    pt: 'Clique numa célula para adicionar um toque. Cada linha é um compasso.',
    ar: 'انقر على خانة لإضافة ضربة. كل صف مازورة واحدة.',
    },
    },
    {
    id: 'mixer',
    target: $('mixer'),
    // `start` is the left in LTR and the right in RTL.
    side: 'start',
    title: { en: 'Mixer', pt: 'Mixer', ar: 'المِكسر' },
    description: {
    en: 'Set each channel’s level with its knob, or with the arrow keys.',
    pt: 'Ajuste o volume de cada canal no knob ou com as setas.',
    ar: 'اضبط مستوى كل قناة بالمقبض أو بمفاتيح الأسهم.',
    },
    },
    ],
    });
    const LABELS: Record<Lang, string> = { en: 'EN', pt: 'PT', ar: 'عربي' };
    export function I18nDemo() {
    const [lang, setLang] = useState<Lang>('pt');
    const dir = lang === 'ar' ? 'rtl' : 'ltr';
    return (
    <Tour.Root tour={tour} messages={messages[lang]} dir={dir} locale={lang}>
    <DemoFrame
    title="Internationalization"
    actions={
    <>
    <fieldset className="flex items-center rounded-sm border-2 border-ink">
    <legend className="sr-only">Language</legend>
    {(['en', 'pt', 'ar'] as const).map((l) => (
    <button
    key={l}
    type="button"
    lang={l}
    aria-pressed={lang === l}
    onClick={() => setLang(l)}
    className={`${worldButton.secondary} h-8 rounded-none border-0`}
    >
    {LABELS[l]}
    </button>
    ))}
    </fieldset>
    <StartButton>
    {{ en: 'Start tour', pt: 'Iniciar tour', ar: 'ابدأ الجولة' }[lang]}
    </StartButton>
    </>
    }
    footer={
    lang === 'ar'
    ? 'Right to left: the card mirrors, and → goes back while ← goes forward.'
    : undefined
    }
    >
    <LoopworkApp scope="worldwide" layout="compact" dir={dir} lang={lang} />
    </DemoFrame>
    <div lang={lang} dir={dir}>
    <TourPopover dots />
    </div>
    </Tour.Root>
    );
    }

    Where to set them

    Pass messages to any of these; the nearest one wins, merged over what it inherits:

    • TourProvider — the whole app.
    • Tour.Root — one tour.
    • Hotspot.Root, Checklist.Root — one hint, one checklist.
    import { TourProvider, type TourMessages } from '@awesome-tour/react';
    const ptBR: Partial<TourMessages> = {
    stepOf: (current, total) => `Passo ${current} de ${total}`,
    closeTour: 'Fechar tour',
    tourSteps: 'Passos do tour',
    goToStep: (index) => `Ir para o passo ${index}`,
    showHint: 'Mostrar dica',
    closeHint: 'Fechar dica',
    checklistProgress: 'Progresso do checklist',
    checklistValue: (completed, total) => `${completed} de ${total} concluídos`,
    itemStatus: { pending: 'Pendente', done: 'Concluído', skipped: 'Pulado' },
    dismissChecklist: 'Dispensar checklist',
    };
    <TourProvider messages={ptBR}>…</TourProvider>;

    Step content in several languages

    The messages above are the library’s own strings. Your tours’ text can be translated in place: any title, description or content (and announcement and survey text) can be an object of BCP 47 locale tags:

    createTour({
    id: 'first-session',
    steps: [
    {
    id: 'mixer',
    target: '#mixer',
    title: { en: 'Mixer', 'pt-BR': 'Mixer', ar: 'المِكسر' },
    description: { en: 'Set the levels.', 'pt-BR': 'Ajuste os volumes.', ar: 'اضبط المستويات.' },
    },
    ],
    });
    <TourProvider locale={user.locale} fallbackLocale="en">…</TourProvider>;

    The locale comes from the nearest locale prop (TourProvider or Tour.Root), else from <html lang> — read after hydration, so server and client agree. A text is picked by exact tag (pt-BR), then language (pt), then any regional variant of it (pt-PT), then fallbackLocale, then its first entry. The same objects work in tours as JSON, so translators can edit them in your CMS. useLocalize() resolves them in your own components.

    TourMessages

    Key Default Used by
    stepOf(c, t) Step c of t Live-region announcement on each step.
    closeTour Close tour Tour.Close without children.
    tourSteps Tour steps Tour.Indicators group label.
    goToStep(n) Go to step n Each Tour.Indicators button.
    showHint Show hint Hotspot.Beacon without children.
    closeHint Close hint Hotspot.Close without children.
    checklistProgress Checklist progress Checklist.Progress accessible name.
    checklistValue c of t completed Checklist.Progress value text.
    itemStatus Not completed / Completed / Skipped Checklist.ItemIndicator status.
    dismissChecklist Dismiss checklist Checklist.Dismiss without children.

    Props on a single part still win: aria-label on Tour.Close, getLabel on Tour.Indicators, labels on Checklist.ItemIndicator, announce on Tour.Root.

    Right-to-left

    Set dir="rtl" on Tour.Root: alignment flips and the arrow keys swap, so ← goes to the next step.