Translating Ballmac UI (i18n)

Quick start

npx shadcn@latest add @ballmac/i18n

import { I18nProvider } from "@/lib/ballmac/i18n"
import ar from "@/messages/ar.json"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <I18nProvider locale="ar" messages={ar}>
          {children}
        </I18nProvider>
      </body>
    </html>
  )
}

messages is a flat object from key to text. Anything you leave out stays in English, so you can translate in stages. Download the complete list of keys with their English text from /i18n/en.json, copy it to ar.json, and translate the values.

Placeholders and plurals

{
  "pagination.nextPage": "الصفحة التالية",
  "data-table.pageOf": "الصفحة {page} من {total}",
  "workspace-card.members_one": "عضو واحد",
  "workspace-card.members_two": "عضوان",
  "workspace-card.members_few": "{count} أعضاء",
  "workspace-card.members_many": "{count} عضوًا",
  "workspace-card.members_other": "{count} عضو"
}

{name} is replaced with a value. Where a message depends on a number, add one key per plural category your language has (_zero, _one, _two, _few, _many, _other, chosen with Intl.PluralRules); English needs only _one and _other, which are built in.

Locale: dates, numbers and money

The provider's locale is used by every component that formats a number, a date, a currency or a duration. Without a provider, <html lang> is used, then en-US. A locale prop on a single component always wins. To get Western digits in an Arabic UI, use ar-u-nu-latn.

Your own components

"use client"
import { useLocale, useMessages } from "@/lib/ballmac/i18n"

export function Greeting({ name }: { name: string }) {
  const msg = useMessages()
  return <p>{msg("app.greeting", "Welcome back, {name}", { name })}</p>
}

msg.rich fills placeholders with React nodes (for example a <kbd>). If you already use next-intl, i18next or Lingui, keep them for your app and pass their output to I18nProvider as messages.

What is translated, and what is not

• All components: accessible names, placeholders, hidden text, default button and empty-state text, status words and templated sentences.
• Props still win. closeLabel, emptyMessage, label and similar props override the dictionary.
• Blocks and templates are copy-in starting points. Their headlines and sample copy are props or live in the file, so you edit them as content. The right-to-left layout is covered in RTL.
• Sample values (such as the .env placeholder) and brand names are not messages.

All 467 messages