Translations

Code

const messages = {  en: { nav: { home: "Home" }, inbox_one: "{count} message", inbox_other: "{count} messages" },  ar: { nav: { home: "الرئيسية" }, inbox_zero: "لا رسائل", inbox_one: "رسالة واحدة", inbox_two: "رسالتان", inbox_few: "{count} رسائل", inbox_many: "{count} رسالة", inbox_other: "{count} رسالة" },};<NasaqProvider>  <TranslationsProvider messages={messages}>    <App />  </TranslationsProvider></NasaqProvider>;function Nav({ unread }: { unread: number }) {  const { t, setLocale } = useT();  return (    <>      <a href="/">{t("nav.home")}</a> · {t("inbox", { count: unread })}      <button onClick={() => setLocale("ar")}>العربية</button>    </>  );}

Utilities · beta

Live examples and controls: Translations in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/translations.json

A small i18n layer for your own strings that shares one locale with Nasaq. TranslationsProvider reads and drives NasaqProvider's locale, so switching language also flips direction and the built-in component strings. useT() returns t(key, vars) over dictionaries you pass in. No i18n library is needed.

When to useCopy Anchor Link

• An app built on Nasaq that needs its own strings in English, Arabic or more.
• When the server suggests a language (an account setting, Accept-Language) that should apply only until the reader picks one: seedLocale.

When not to useCopy Anchor Link

• Nasaq components' own strings: they already follow the locale; pass labels to change them.
• An app already on i18next or FormatJS: keep it, and sync its language with useNasaq().setLocale.

ImportCopy Anchor Link

import { TranslationsProvider, useT } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

const messages = {
  en: { nav: { home: "Home" }, inbox_one: "{count} message", inbox_other: "{count} messages" },
  ar: { nav: { home: "الرئيسية" }, inbox_zero: "لا رسائل", inbox_one: "رسالة واحدة", inbox_two: "رسالتان", inbox_few: "{count} رسائل", inbox_many: "{count} رسالة", inbox_other: "{count} رسالة" },
};

<NasaqProvider>
  <TranslationsProvider messages={messages}>
    <App />
  </TranslationsProvider>
</NasaqProvider>;

function Nav({ unread }: { unread: number }) {
  const { t, setLocale } = useT();
  return (
    <>
      <a href="/">{t("nav.home")}</a> · {t("inbox", { count: unread })}
      <button onClick={() => setLocale("ar")}>العربية</button>
    </>
  );
}

AnatomyCopy Anchor Link

TranslationsProvider   context only, renders no element
└─ useT()              { t, locale, setLocale, seedLocale, hasStoredLocale }

APICopy Anchor Link

TranslationsProviderCopy Anchor Link

t(key, vars?)Copy Anchor Link

• Keys: nav.home, nav:home (namespace), or a flat key containing dots. A flat key wins.
• Interpolation: {name} and {{name}}. Numbers are formatted for the locale (Arabic digits in ar).
• Plurals: with a numeric count, key_zero (for 0), then the CLDR form (_one, _two, _few, _many) and key_other are tried, then key.
• Fallback: ar-EG, ar, the fallback locale, then vars.defaultValue, then the key itself.

useT()Copy Anchor Link

useOptionalT() returns null outside a provider. createTranslator(bundle, locale, fallback) is the same t without React, for servers and tests.

AccessibilityCopy Anchor Link

• NasaqProvider sets lang and dir from the locale, so screen readers switch voice and the layout mirrors.
• Keep whole sentences as one key so translators can reorder words.

RTL & i18nCopy Anchor Link

Arabic has six plural forms; give at least _zero, _one, _two, _few, _many and _other. Missing forms fall back to _other.

Styling & tokensCopy Anchor Link

None: this is logic only.

Do / Don'tCopy Anchor Link

• Do use seedLocale for server defaults so a reader's own choice is never overwritten.
• Don't build sentences from fragments (t("you_have") + n + t("messages")); use one key with {count}.

RelatedCopy Anchor Link

• Switchers
• LangTag

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-utilities-translations--docs