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.
Beat A
16 steps · drumsMixer
4 channelsimport { 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.