Skip to content

Commit 62ae123

Browse files
committed
feat: translatable UI labels for LanguageSwitcher, PhoneInput, NavBar and TranslationWidget (#30)
1 parent 2953bb0 commit 62ae123

14 files changed

Lines changed: 582 additions & 35 deletions

File tree

‎content/docs/components/inputs/phone-input.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,8 @@ export function PhoneField() {
128128
| `side` | `"top" \| "bottom"` | No | Preferred menu side; flips when there is no room (default: `"bottom"`) |
129129
| `searchPlaceholder` | `string` | No | Placeholder for the country search (default: `"Search countries..."`) |
130130
| `emptyMessage` | `ReactNode` | No | Shown when the search matches nothing (default: `"No countries found."`) |
131+
| `labels` | `Partial<PhoneInputLabels>` | No | Override the built-in English UI text (see below) |
132+
| `displayLocale` | `string` | No | Locale for country names, e.g. `"fr"` (default: English names) |
131133
| `maxHeight` | `number \| string` | No | Max height of the scrolling country list (default: `"15rem"`) |
132134
| `label` | `string` | No | Accessible label for the input |
133135
| `className` | `string` | No | Classes for the root wrapper |
@@ -256,6 +258,50 @@ Every part takes its own classes through `classNames`, merged after the defaults
256258
/>
257259
```
258260

261+
### Translated UI text
262+
263+
Pass `labels` to translate the country menu's text, and `displayLocale` to show
264+
country names in another language. Names come from the browser's
265+
[`Intl.DisplayNames`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames),
266+
so their exact wording can vary slightly between browsers. Searching matches the
267+
translated name, while `onValueChange` still reports the country's English `name`.
268+
The `searchPlaceholder` and `emptyMessage` props still work, and win over `labels`
269+
when both are set.
270+
271+
```tsx
272+
"use client";
273+
274+
import { PhoneInput } from "@/components/ui/phone-input";
275+
276+
export default function App() {
277+
return (
278+
<PhoneInput
279+
defaultCountry="FR"
280+
displayLocale="fr"
281+
label="Numéro de téléphone"
282+
placeholder="Numéro de téléphone"
283+
labels={{
284+
trigger: "Choisir un pays",
285+
searchPlaceholder: "Rechercher un pays…",
286+
searchLabel: "Rechercher un pays",
287+
clearSearch: "Effacer la recherche",
288+
emptyMessage: "Aucun pays trouvé.",
289+
listbox: "Choisir un pays",
290+
}}
291+
/>
292+
);
293+
}
294+
```
295+
296+
| Key | Default | Used for |
297+
| ------------------- | ----------------------- | ----------------------------- |
298+
| `trigger` | `"Select country"` | Country trigger label |
299+
| `searchPlaceholder` | `"Search countries..."` | Search field placeholder |
300+
| `searchLabel` | `"Search countries"` | Search field accessible label |
301+
| `clearSearch` | `"Clear search"` | Clear button accessible label |
302+
| `emptyMessage` | `"No countries found."` | Shown when nothing matches |
303+
| `listbox` | `"Select country"` | Country list accessible label |
304+
259305
## Keyboard support
260306

261307
The country menu follows the WAI-ARIA combobox pattern: focus stays in the search

‎content/docs/components/language-switchers/language-switcher.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ export function LocaleSwitcher() {
130130
| `searchable` | `boolean` | No | Show the search field (default: `true`) |
131131
| `searchPlaceholder` | `string` | No | Search placeholder (default: `"Search languages..."`) |
132132
| `emptyMessage` | `ReactNode` | No | Shown when the search matches nothing (default: `"No languages found."`) |
133+
| `labels` | `Partial<LanguageSwitcherLabels>` | No | Override the built-in English UI text (see below) |
133134
| `disabled` | `boolean` | No | Disable the trigger |
134135
| `renderOption` | `(locale, state) => ReactNode` | No | Replace each option row's content; `state` has `selected`, `active`, `label`, `flag` |
135136
| `classNames` | `LanguageSwitcherClassNames` | No | Per-part classes: `trigger`, `content`, `search`, `list`, `item`, `empty` |
@@ -267,6 +268,46 @@ The switcher is styled with shadcn theme tokens, so it follows your theme. Use
267268
/>
268269
```
269270

271+
### Translated UI text
272+
273+
The search placeholder, empty state and accessible labels default to English. Pass
274+
`labels` to translate them — any key you leave out keeps its English default. The
275+
`searchPlaceholder` and `emptyMessage` props still work, and win over `labels` when
276+
both are set.
277+
278+
```tsx
279+
"use client";
280+
281+
import { LanguageSwitcher } from "@/components/ui/language-switcher";
282+
283+
export default function App() {
284+
return (
285+
<LanguageSwitcher
286+
locales={[{ code: "en" }, { code: "fr" }, { code: "es" }]}
287+
defaultValue="fr"
288+
label="native"
289+
labels={{
290+
searchPlaceholder: "Rechercher une langue…",
291+
searchLabel: "Rechercher une langue",
292+
clearSearch: "Effacer la recherche",
293+
emptyMessage: "Aucune langue trouvée.",
294+
listbox: "Choisir la langue",
295+
current: (name) => `Langue actuelle : ${name}`,
296+
}}
297+
/>
298+
);
299+
}
300+
```
301+
302+
| Key | Default | Used for |
303+
| ------------------- | --------------------------------------- | ----------------------------- |
304+
| `searchPlaceholder` | `"Search languages..."` | Search field placeholder |
305+
| `searchLabel` | `"Search languages"` | Search field accessible label |
306+
| `clearSearch` | `"Clear search"` | Clear button accessible label |
307+
| `emptyMessage` | `"No languages found."` | Shown when nothing matches |
308+
| `listbox` | `"Select language"` | Option list accessible label |
309+
| `current` | `(name) => "Current language: " + name` | Trigger accessible label |
310+
270311
## Keyboard support
271312

272313
The popup follows the WAI-ARIA combobox pattern: focus stays in the search field,

‎content/docs/components/navigation/navbar.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ export function SiteNav() {
137137
| `showFlags` | `boolean` | No | Show flags in language selector (default: `true`) |
138138
| `maxHeight` | `number \| string` | No | Max height of the scrolling language menu (default: `"15rem"`) |
139139
| `linkComponent` | `React.ElementType` | No | Component used for internal links (default: `"a"`) |
140+
| `labels` | `Partial<NavBarLabels>` | No | Override the built-in English UI text (see below) |
140141
| `classNames` | `NavBarClassNames` | No | Per-part class overrides (see below) |
141142
| `className` | `string` | No | Additional CSS classes |
142143

@@ -361,6 +362,40 @@ export default function App() {
361362
}
362363
```
363364

365+
### Translated UI text
366+
367+
The language menu, mobile menu button and GitHub link carry English accessible
368+
labels by default. Pass `labels` to translate them — any key you leave out keeps
369+
its English default.
370+
371+
```tsx
372+
"use client";
373+
374+
import { NavBar } from "@/components/ui/navbar";
375+
376+
export default function App() {
377+
return (
378+
<NavBar
379+
logo={<span className="font-bold">MyApp</span>}
380+
locales={[{ code: "en" }, { code: "fr" }]}
381+
defaultValue="fr"
382+
labels={{
383+
listbox: "Choisir la langue",
384+
current: (name) => `Langue actuelle : ${name}`,
385+
toggleMenu: "Ouvrir le menu",
386+
}}
387+
/>
388+
);
389+
}
390+
```
391+
392+
| Key | Default | Used for |
393+
| ------------ | --------------------------------------- | --------------------------------- |
394+
| `listbox` | `"Select language"` | Language menu accessible label |
395+
| `current` | `(name) => "Current language: " + name` | Language trigger accessible label |
396+
| `toggleMenu` | `"Toggle menu"` | Mobile menu button label |
397+
| `github` | `"GitHub"` | GitHub icon link label |
398+
364399
## Keyboard support
365400

366401
The language menu follows the WAI-ARIA listbox pattern. With no text field in the

‎content/docs/components/translation/translation-widget.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,7 @@ export function Translate() {
170170
| `showClear` | `boolean` | No | Show a clear button under an editable source (default: `true`) |
171171
| `showCopy` | `boolean` | No | Show a copy-to-clipboard button under the target (default: `true`) |
172172
| `onTargetCopy` | `(text: string) => void` | No | Called with the target text after it is copied |
173+
| `labels` | `TranslationWidgetLabels` | No | Override any subset of the built-in English UI text (see below) |
173174
| `loading` | `boolean` | No | Show a skeleton in the target pane and mark it `aria-busy` |
174175
| `classNames` | `TranslationWidgetClassNames` | No | Per-part class overrides: `root`, `header`, `pane`, `textarea`, `footer`, `swap`, `chip` |
175176
| `dir` | `"ltr" \| "rtl"` | No | Override the auto-detected layout direction |
@@ -293,6 +294,39 @@ async function translate(text: string) {
293294
<TranslationWidget loading={loading} /* … */ />;
294295
```
295296

297+
## Translated UI text
298+
299+
The pane placeholders and labels have their own props (`sourcePlaceholder`,
300+
`sourceLabel` and so on). The rest of the built-in text — toolbar buttons, the copy
301+
announcement and the word read after the character count — comes from `labels`.
302+
Any key you leave out keeps its English default.
303+
304+
```tsx
305+
<TranslationWidget
306+
sourceLocale="fr"
307+
targetLocale="en"
308+
sourcePlaceholder="Texte source"
309+
sourceLabel="Texte source"
310+
labels={{
311+
swap: "Inverser les langues",
312+
copy: "Copier la traduction",
313+
copied: "Copié",
314+
copiedStatus: "Traduction copiée dans le presse-papiers",
315+
clearSource: "Effacer le texte source",
316+
characters: (count) => (count === 1 ? "caractère" : "caractères"),
317+
}}
318+
/>
319+
```
320+
321+
| Key | Default | Used for |
322+
| -------------- | ----------------------------------- | ------------------------------------- |
323+
| `swap` | `"Swap languages"` | Swap button accessible label |
324+
| `copy` | `"Copy translation"` | Copy button accessible label |
325+
| `copied` | `"Copied"` | Copy button label right after a copy |
326+
| `copiedStatus` | `"Translation copied to clipboard"` | Screen reader announcement after copy |
327+
| `clearSource` | `"Clear source text"` | Clear button accessible label |
328+
| `characters` | `(count) => "characters"` | Read after the character count |
329+
296330
## Customization
297331

298332
Every part takes extra classes through `classNames`, merged after the defaults with

‎content/docs/customization/interfaces.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,35 @@ export interface LanguageSwitcherProps {
6565
showFlags?: boolean;
6666
/** Display labels in native language or English (default: "english") */
6767
label?: "native" | "english";
68+
/** Override the built-in English UI text — any key you omit keeps its default */
69+
labels?: Partial<LanguageSwitcherLabels>;
6870
/** Additional CSS classes */
6971
className?: string;
7072
}
7173
```
7274

75+
### LanguageSwitcherLabels
76+
77+
```ts
78+
export interface LanguageSwitcherLabels {
79+
/** Placeholder for the search field (default: "Search languages...") */
80+
searchPlaceholder: string;
81+
/** Accessible label for the search field (default: "Search languages") */
82+
searchLabel: string;
83+
/** Accessible label for the button that clears the search (default: "Clear search") */
84+
clearSearch: string;
85+
/** Content shown when the search matches nothing (default: "No languages found.") */
86+
emptyMessage: React.ReactNode;
87+
/** Accessible label for the option list (default: "Select language") */
88+
listbox: string;
89+
/** Accessible label for the trigger (default: "Current language: {name}") */
90+
current: (name: string) => string;
91+
}
92+
```
93+
94+
Pass any subset as `labels` — keys you omit keep their English default. The same
95+
holds for every `*Labels` interface below.
96+
7397
## Phone Input
7498

7599
### Country
@@ -109,6 +133,29 @@ export interface PhoneInputProps {
109133
showFlags?: boolean;
110134
/** Accessible label for the input */
111135
label?: string;
136+
/** Override the built-in English UI text — any key you omit keeps its default */
137+
labels?: Partial<PhoneInputLabels>;
138+
/** BCP 47 locale used to display country names, e.g. "fr" (default: English names) */
139+
displayLocale?: string;
140+
}
141+
```
142+
143+
### PhoneInputLabels
144+
145+
```ts
146+
export interface PhoneInputLabels {
147+
/** Accessible label for the country trigger (default: "Select country") */
148+
trigger: string;
149+
/** Placeholder for the country search field (default: "Search countries...") */
150+
searchPlaceholder: string;
151+
/** Accessible label for the country search field (default: "Search countries") */
152+
searchLabel: string;
153+
/** Accessible label for the button that clears the search (default: "Clear search") */
154+
clearSearch: string;
155+
/** Content shown when the search matches nothing (default: "No countries found.") */
156+
emptyMessage: React.ReactNode;
157+
/** Accessible label for the country list (default: "Select country") */
158+
listbox: string;
112159
}
113160
```
114161

@@ -159,11 +206,49 @@ export interface NavBarProps {
159206
sticky?: boolean;
160207
/** Show flags in language selector (default: true) */
161208
showFlags?: boolean;
209+
/** Override the built-in English UI text — any key you omit keeps its default */
210+
labels?: Partial<NavBarLabels>;
162211
/** Additional CSS classes */
163212
className?: string;
164213
}
165214
```
166215

216+
### NavBarLabels
217+
218+
```ts
219+
export interface NavBarLabels {
220+
/** Accessible label for the language list (default: "Select language") */
221+
listbox: string;
222+
/** Accessible label for the language menu triggers (default: "Current language: {name}") */
223+
current: (name: string) => string;
224+
/** Accessible label for the mobile menu button (default: "Toggle menu") */
225+
toggleMenu: string;
226+
/** Accessible label for the GitHub icon link (default: "GitHub") */
227+
github: string;
228+
}
229+
```
230+
231+
## Translation Widget
232+
233+
### TranslationWidgetLabels
234+
235+
```ts
236+
export interface TranslationWidgetLabels {
237+
/** Accessible label for the swap button (default: "Swap languages") */
238+
swap: string;
239+
/** Accessible label for the copy button (default: "Copy translation") */
240+
copy: string;
241+
/** Accessible label for the copy button right after a copy (default: "Copied") */
242+
copied: string;
243+
/** Screen reader announcement after a copy (default: "Translation copied to clipboard") */
244+
copiedStatus: string;
245+
/** Accessible label for the clear button (default: "Clear source text") */
246+
clearSource: string;
247+
/** Screen reader word read after the character count (default: "characters") */
248+
characters: (count: number) => string;
249+
}
250+
```
251+
167252
## Extending Interfaces
168253

169254
Because Babelize Elements components are fully owned by you once installed, you can extend these interfaces directly in the component files. For example, to add a custom `meta` field to each locale, add it to the `Locale` interface in your local copy:

‎src/registry/components/index.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ export { LanguageSwitcher } from "./language-switcher";
66
export type {
77
LanguageSwitcherProps,
88
LanguageSwitcherClassNames,
9+
LanguageSwitcherLabels,
910
LanguageSwitcherOptionState,
1011
} from "./language-switcher";
1112

@@ -16,10 +17,19 @@ export type {
1617
} from "./language-switcher-pill";
1718

1819
export { PhoneInput, COUNTRIES } from "./phone-input";
19-
export type { PhoneInputProps, PhoneInputClassNames, Country } from "./phone-input";
20+
export type {
21+
PhoneInputProps,
22+
PhoneInputClassNames,
23+
PhoneInputLabels,
24+
Country,
25+
} from "./phone-input";
2026

2127
export { NavBar } from "./navbar";
22-
export type { NavBarProps, NavBarClassNames, NavLink } from "./navbar";
28+
export type { NavBarProps, NavBarClassNames, NavBarLabels, NavLink } from "./navbar";
2329

2430
export { TranslationWidget } from "./translation-widget";
25-
export type { TranslationWidgetProps, TranslationWidgetClassNames } from "./translation-widget";
31+
export type {
32+
TranslationWidgetProps,
33+
TranslationWidgetClassNames,
34+
TranslationWidgetLabels,
35+
} from "./translation-widget";

0 commit comments

Comments
 (0)