@maudit/react-native-localization

Small React Native localization library extracted from the auditor app.

It supports three core jobs:

1. Inject a server URL and auth/session headers.
2. Load/sync localization data from the server into local storage.
3. Read localized text by key with a default fallback value.

What This Package Can Do

• Save server localization locally in React Native AsyncStorage.
• Let you pass any API base URL from your app.
• Let you pass auth/session headers from your app.
• Sync localization for one screen or many screens.
• Sync common backend messages such as validation/error messages.
• Read text by key anywhere in the app.
• Return your fallback text when a key is missing.
• Switch language and sync the new language.
• Use a fallback language when the selected language is missing a key.
• Avoid extra API calls by using cache expiry.
• Track missing keys for debugging.
• Use a React hook in components.

Install

npm install @muhammadmuneebiftikhar/react-native-localization @react-native-async-storage/async-storage

Private Publish

For npm public packages, publish with public access:

npm login
npm run build
npm pack --dry-run
npm publish --access public

For a company registry, copy .npmrc.example to .npmrc and replace the scope/registry with your company values. In CI, set NPM_TOKEN as a secret.

For GitHub Packages, rename the package scope to your GitHub org scope, for example @your-org/react-native-localization, then use:

@your-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Before first publish, confirm the package name in package.json matches the company scope you want consumers to install.

Usage

import {
  configureLocalization,
  hydrateLocalization,
  localizationLoad,
  localizationGet,
} from '@maudit/react-native-localization';

configureLocalization({
  baseUrl: 'https://example.com/api',
  headers: async () => ({
    Key: session.key,
    SessionId: session.sessionId,
    LanguageId: String(session.languageId),
    Culture: session.culture,
  }),
});

await hydrateLocalization();

await localizationLoad({
  languageId: 2,
  screenIds: [3255, 3256, 3257],
  includeMessages: true,
});

const label = localizationGet('auditScheduleEntry##btnSave', 'Save');

Simple App Flow

Use this package in this order:

1. Configure it with your API URL and headers.
2. Hydrate local saved data on app start.
3. Sync data after login or language change.
4. Read labels/messages with localizationGet() or useLocalization().

configureLocalization({
  baseUrl: 'https://your-api.com/api',
  headers: () => ({
    Key: session.key,
    SessionId: session.sessionId,
    LanguageId: String(session.languageId),
    Culture: session.culture,
  }),
});

await hydrateLocalization();

await localizationLoad({
  languageId: Number(session.languageId),
  screenIds: [1001, 1002, 1003],
  includeMessages: true,
});

const title = localizationGet('dashboard##txtTitle', 'Dashboard');

Ten Screens Example

If your app has 10 screens, pass all 10 screen IDs:

const SCREEN_IDS = {
  LOGIN: 1001,
  DASHBOARD: 1002,
  SETTINGS: 1003,
  PROFILE: 1004,
  ORDERS: 1005,
  ORDER_DETAIL: 1006,
  NOTIFICATIONS: 1007,
  REPORTS: 1008,
  HELP: 1009,
  ABOUT: 1010,
} as const;

await localizationLoad({
  languageId: 1,
  screenIds: Object.values(SCREEN_IDS),
  includeMessages: true,
});

Then read text:

localizationGet('login##txtTitle', 'Login');
localizationGet('orderDetail##btnSave', 'Save');
localizationGet('MSG_COMMON_ERROR', 'Something went wrong');

API

• configureLocalization(options) sets baseUrl, endpoints, headers, fetcher, and storage.
• setLocalizationServerUrl(url) changes only the server URL.
• hydrateLocalization() loads the persisted local dump into memory.
• localizationLoad(options) fetches server localization and persists it locally.
• localizationGet(key, defaultValue?, languageId?) reads from local storage and falls back to defaultValue.
• localizationSet(languageId, entries) manually stores key/value pairs.
• setSelectedLanguageId(languageId) changes the default lookup language.
• clearLocalization() clears local localization data.
• localizationInit(options) configures, hydrates, and optionally syncs in one call.
• changeLocalizationLanguage(options) switches language and optionally syncs the new language.
• useLocalization(languageId?) returns a React hook-friendly { t, languageId }.
• getMissingLocalizationKeys() returns keys that fell back because no localized value existed.

The default parser supports the auditor/.NET shapes:

• Security/GetScreenConfiguration?screenId=...
• Security/GetConfigurations with Messages[]

Custom projects can provide parseScreenResponse or parseMessagesResponse in localizationLoad.

Optional Features

Cache Expiry

Avoid hitting the server on every app start:

await localizationLoad({
  languageId: 1,
  screenIds: [3255, 3256],
  includeMessages: true,
  maxAgeMinutes: 60,
});

Pass force: true to ignore cache expiry and sync immediately.

Fallback Language

Try another local language before returning the default value:

configureLocalization({
  baseUrl,
  fallbackLanguageId: 1,
});

const title = localizationGet('dashboard##txtTitle', 'Dashboard', 2);

Lookup order is: selected language -> fallback language -> default value -> key.

React Hook

import { useLocalization } from '@muhammadmuneebiftikhar/react-native-localization';

function SaveButton() {
  const { t } = useLocalization();
  return <Text>{t('auditScheduleEntry##btnSave', 'Save')}</Text>;
}

Missing Key Debugging

localizationGet('missing##key', 'Default');
console.log(getMissingLocalizationKeys());

Scoped Clear

await clearLocalization({ languageId: 2 });
await clearLocalization({ languageId: 2, keyPrefix: 'auditScheduleEntry##' });

Calling clearLocalization() with no arguments still clears everything.