Guides

Localization & Translation

AuthCore ships with English and French dictionaries out of the box and exposes a flexible translation system. You can register additional locales, swap dictionaries at runtime, or inject a completely custom translator for advanced workflows.

How the translation system works

  • Provider first. Wrap your app with I18nProvider to make the useI18n() hook available everywhere.
  • Dictionary registry. Use registerDictionary(locale, messages) to expose new locales or override bundled text.
  • Translator injection. Pass a custom translator to I18nProvider when you want to integrate with external i18n platforms or async loaders.
  • No coupling. Components only know about the t() helper, so you can swap languages without touching UI code.

Register a new locale

Dictionaries are plain objects. You can register them at startup, inside a route handler, or during SSR. These overrides cascade on top of the bundled English strings.

register-locale.ts

The helper performs a deep merge, so you only need to provide keys that differ from the defaults.

Inject a custom translator

For enterprise setups you may want to fetch dictionaries from a translation platform or feature flag locales per tenant. The translator prop lets you hand AuthCore any translation function.

translator.tsx
Tip: re-use buildTranslator() to stitch together fallback locales so that missing keys gracefully fall back to English.

Translate inside components

Hooks like useI18n() expose the current locale and the t helper. All core components already use the same keys shown below, so your overrides are immediately reflected.

GreetingBanner.tsx

Sync the glassmorphic theme

The post-install script copies dist/styles/authcore.css into your project automatically. If you need to re-run it manually or bundle the CSS in CI, use the CLI commands below.

Terminal

The installer checks INIT_CWD so the file lands inside your consuming app (for example styles/authcore-theme.css). Import that file once in your application layout to get the glassmorphic tokens used across every component demonstrated in this documentation.

Frequently asked questions

Can I use my existing i18n library?

Yes. Create a bridge function that calls into your library and pass it as the translator prop. AuthCore will use it for every t() call.

What happens if a key is missing?

Missing keys automatically fall back to English. Provide a defaultValue when calling translate() if you need a different fallback.

Where do I import locale JSON files?

Bundle them with your app (for example inside locales/*.json) or fetch them from your API. The translation helpers accept plain objects so you can source data from anywhere.